Browse Source
Index entry + detail file written per the draft presented and approved 2026-07-29/30. Status proposed. Carries the 2026-07-10 requirements sketch from the G-057 archive (copyright carry-over default, ProductName naming the core Tcl version, toml config direction), the punkres-only-arm decision with the twapi/sfe BuildVersionResource alternative recorded under Alternatives, the three-surfaces reconciliation obligation with G-025/G-117, and Related lines for G-023/G-024/G-025/G-028/G-006/G-004 plus the archived G-057/G-117/G-128/G-134 anchors. Overlap survey recorded (no live goals intersect src/tools/punkres or src/make.tcl; bin/ surfaced G-004 + G-023). Two in-parens punctuation adjustments vs the presented draft (inner '; ' became ' - ') so the Scope line parses as single elements under goals_lint's '; ' element grammar. goals_lint clean; no dangling references. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
2 changed files with 104 additions and 0 deletions
@ -0,0 +1,100 @@
|
||||
# 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. |
||||
Loading…
Reference in new issue