From 0f2f95cc7e26c880178b860634e903dd0958e0a7 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Thu, 30 Jul 2026 04:20:48 +1000 Subject: [PATCH] G-137 drafted (user-approved): kit version resources - RT_VERSION stamping from punkproject.toml via punkres 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.com --- GOALS.md | 4 ++ goals/G-137-kit-version-resources.md | 100 +++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 goals/G-137-kit-version-resources.md diff --git a/GOALS.md b/GOALS.md index 63d9a90e..133add41 100644 --- a/GOALS.md +++ b/GOALS.md @@ -402,3 +402,7 @@ Detail: goals/G-132-tcl-windows-errno-catchall-report.md ### G-136 [proposed] Generated projects are seeded with a default icon from a single punkshell-held master Scope: src/assets/logo/project-default/ (the single held seed artwork); src/modules/punk/mix/commandset/project-999999.0a1.0.tm (generation-time asset injection beside bootsupport_inject); src/project_layouts/ (per-layout icon-slot declaration with no artwork stored in layout trees); src/modules/punkcheck-999999.0a1.0.tm (install records for injected assets) Detail: goals/G-136-generated-project-icon-seeding.md + +### G-137 [proposed] Kit version resources: RT_VERSION stamping from punkproject.toml via punkres +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) +Detail: goals/G-137-kit-version-resources.md diff --git a/goals/G-137-kit-version-resources.md b/goals/G-137-kit-version-resources.md new file mode 100644 index 00000000..c235dff8 --- /dev/null +++ b/goals/G-137-kit-version-resources.md @@ -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 `.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 `.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.