punkshell/goals/G-137-kit-version-resources.md

G-137 Kit version resources: RT_VERSION stamping from punkproject.toml via punkres

Status: proposed Scope: src/tools/punkres/ (VS_VERSIONINFO construction, set-version + field-level read-back - upstream at c:/repo/jn/zig/punkres); src/make.tcl (version stamping at the G-057/G-128 kit-icon seam, punkres arm); bin/*.resources.toml sidecar format + bin/AGENTS.md (version fields and status vocabulary); punkproject.toml (field source - configurable overrides); src/tests/ (characterization) Goal: every win32-target kit a bake produces carries a truthful RT_VERSION resource - project version, product identity naming the embedded Tcl generation, and a copyright carried over from the input runtime rather than silently dropped - stamped by punkres with the same overlay-preserving guarantees as its icon stamping, so Explorer's file-properties pane becomes a provenance surface that tells the same story as the G-025 kit stamp and the G-117 embedded artifact record. Acceptance: punkres constructs and stamps RT_VERSION (VS_FIXEDFILEINFO plus StringFileInfo/VarFileInfo) into finished PEs with its existing overlay guarantees intact, replaces any prior RT_VERSION without disturbing other resource types (icons in particular), converges on re-stamping, and reads the result back FIELD-LEVEL itself (porcelain-pinned) so verification needs no windows host, cross-checked once on windows with twapi::extract_resources; the kit-icon seam stamps every win32-target kit during the bake via the punkres arm with fields derived per rules recorded in the detail file - FileVersion/ProductVersion from the punkproject.toml project version (the 4-part numeric mapping stated), ProductName indicating the kit's core Tcl version, copyright defaulting to the value carried in the INPUT runtime's version resource (configurable via punkproject.toml, never silently dropped) - and the <kit>.resources.toml sidecar records the stamped fields with a distinct version status when stamping did not run; with punkres absent the twapi icon arm behaves exactly as today and the sidecar records the version skip with the build/fetch remedy; stamped kits boot reading their payloads, demonstrated on the punk91-family plus one PE32 kit; the field-to-source mapping is recorded as the shared story reconciling this surface with G-025's kit stamp and G-117's embedded record (without blocking on G-025's implementation).

Context

This is the follow-on G-057 parked and G-128 was structured for. The pieces are all in place: punkres's resource-tree model is deliberately generic over types (G-128 acceptance: "the tool's structure handling is written so the parked RT_VERSION stamping needs no second tool"), its post-hoc stamping removed G-057's ordering constraint (the project version is known late - a version resource can be stamped after wrap, or on the stub during the bake, without endangering the payload), and the per-kit sidecar was named <kit>.resources.toml rather than an icon-specific name precisely so version fields extend the same record. The payoff is a provenance surface users already know how to read: Explorer's file-properties Details pane on any punkshell kit.

The G-128 fleet work also settled the group-icon identity (PUNKSHELL, derived from the icon filename); RT_VERSION completes the kit's external identity the same way - derived from punkproject.toml, applied by the same seam, recorded in the same sidecar.

Approach

• punkres owns the structure: VS_VERSIONINFO construction (VS_FIXEDFILEINFO + StringFileInfo/VarFileInfo tables), a set-version operation with the same refusal/consent overlay semantics as set-icon, and a field-level read-back (porcelain-pinned) so a non-windows host can verify what it stamped. Whether icon and version stamp in one invocation or two is a work decision - both must converge and preserve each other.
• One implementation: version stamping runs via the punkres arm only. With no punkres built, icons keep working through the twapi arm exactly as today and the sidecar records the version skip with both acquisition remedies (build from vendored source, or fetch the punkbin artifact - the G-128 routes).
• Field mapping recorded in this file as the single story: FileVersion / ProductVersion from the punkproject.toml project version (4-part numeric mapping to be stated, e.g. MAJOR.MINOR.PATCH.0), ProductName carrying the kit's core Tcl version, copyright carried over from the input runtime's existing version resource by default with a punkproject.toml override.
• Config surface anticipates the established toml direction (punkproject.toml now; per-kit overrides only if a real need surfaces - and then via the G-024 mapvfs toml grammar, not the legacy line format).

Alternatives considered

• twapi arm gains RT_VERSION too (sfe-0.2.tm BuildVersionResource is direct prior art) - set aside at drafting (2026-07-30): a second VS_VERSIONINFO builder is a permanent parity burden for structures far richer than icon groups, and the no-toolchain windows persona now has a no-toolchain punkres route (the G-128 punkbin artifact). Recorded as user-selectable if the skip-on-twapi-only degradation proves annoying in practice.
• Post-hoc fleet re-stamp on version bump without rebake - enabled by punkres's post-hoc capability and deliberately NOT required by the acceptance; parked as a possible later convenience (a version-only stamp of deployed kits).

Notes

• Requirements sketch agreed 2026-07-10 (recorded in the G-057 archive detail, "Follow-on candidate goal"): copyright defaults to the copyright already present in the INPUT kit runtime's version resource (the runtime authors' copyright is not ours to silently drop), configurable via punkproject.toml and/or per-vfs config; ProductName should indicate the core Tcl version of the runtime by default; other fields settled at goal time; config surface anticipates the toml direction.
• Related: G-025 - the reconciliation partner: its vfs-stamped version/runtime/vfs identity and in-shell self-report, G-117's embedded punkbin-artifact record (archived), and this goal's RT_VERSION are three surfaces that must tell ONE story; the field-to-source mapping this goal records is that story's canonical table. This goal must not block on G-025's implementation.
• Related: G-023 - version-named binaries draw on the same punkproject.toml source; its versioned/dev outputs are rewritten every build, the cadence the seam already handles.
• Related: G-024 - if per-kit version overrides are ever wanted, they land in its mapvfs toml grammar.
• Related: G-028 - a locked kit exe blocks a resource update exactly as it blocks deploy; its locker-report direction applies to version stamping failures too.
• Related: G-006 - punkres version bumps produced by this goal ride the punkbin tools-tier channel (first artifact already published under G-128); the make.tcl-integrated fetch leaning is recorded in G-006's Notes.
• Related: G-004 - bin/punkres.exe stays an untracked built/fetched artifact; nothing this goal adds is committed as a binary.
• Anchors (archived): G-057 (the parked sketch and the sidecar's resources-not-icon naming - goals/archive/G-057-kit-icon-embedding.md), G-128 (the tool, its overlay guarantees, read-back discipline and the PUNKSHELL group naming - goals/archive/G-128-portable-pe-resource-stamping.md), G-117 (the embedded artifact record schema - goals/archive/G-117-self-describing-runtimes.md), G-134 (the archive-relative pin the stamper's payload handling upholds - goals/archive/G-134-baked-kits-pinned-archive-relative.md).
• Overlap survey 2026-07-29 (drafting): goals_xref paths src/tools/punkres src/make.tcl bin/ punkproject.toml - no live goals intersect src/tools/punkres or src/make.tcl; bin/ surfaced G-004 and G-023 (both carried as Related above); goals_xref report reviewed - no unlinked pair concerns version resources. The G-057/G-117/G-128/G-134 anchors are archived; the remaining relations are from reading.