From 7425ab3c8e73c2db9eda7d591416c6287abfebbe Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 29 Jul 2026 16:18:46 +1000 Subject: [PATCH] G-128 achieved: flip, archive record, reference sweep - punkbin route verified LIVE Post-push verification against the live server: punkres-x86_64-windows-0.3.1.exe fetched from gitea punkbin, sha1 matches the published sha1sums row and the staged value (166cd176...), fetched binary runs. Every acceptance clause is satisfied (full evidence in the detail file's flip entry: post-hoc stamping with tool-self read-back + twapi cross-check, boots, convergence, both section shapes, file-relative refusal/consented preserve crc-verified, zip64/multi-disk refusal, WSL non-windows e2e with host recorded, seam selection + parity + zig-optional degradation, distribution both ways now LIVE, RT_VERSION-ready tree handling, licensing/provenance). Flip mechanics: detail Status achieved 2026-07-29 with evidence appended; index entry moved to GOALS-archive.md (record format incl. that file's arrow convention); reference sweep - G-127 cross-host mention, G-134 Related line and G-101's container-review rider gain achieved/archive markers, PROVENANCE.md's explicit detail path repointed to the archive. goals_xref: no live pairs were bridged solely by G-128. Archive MOVE of the detail file follows as a separate pure-rename commit (Doc Restructures move/edit separation). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS-archive.md | 4 ++++ GOALS.md | 4 ---- goals/G-101-tcl86-kit-container-strategy.md | 6 +++-- goals/G-127-crosstarget-vfs-bake.md | 5 +++- goals/G-128-portable-pe-resource-stamping.md | 24 ++++++++++++++++++- ...-134-baked-kits-pinned-archive-relative.md | 4 +++- src/tools/punkres/PROVENANCE.md | 4 ++-- 7 files changed, 40 insertions(+), 11 deletions(-) diff --git a/GOALS-archive.md b/GOALS-archive.md index 5649a1ae..e08e26b4 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -230,3 +230,7 @@ Acceptance: the vendored source builds under the repo's pinned zig 0.16 toolchai ### G-135 [achieved 2026-07-28] Asset provenance records: a verifiable master-to-derived icon chain with a platform-neutral generator → detail: goals/archive/G-135-asset-provenance-records.md Scope: src/assets/logo/ (per-asset *.assetorigin.toml sidecars, masters and generated icons); src/assets/logo/make-ico.ps1 (replaced in place by a Tcl generator, then removed); scriptlib/developer/ (provenance checker, sibling to goals_lint and architecture_lint); checker home revisited if it becomes a bake step (a punk:: module rather than scriptlib, which make.tcl must not depend on); src/runtime/punkshell.ico and src/vfs/_vfscommon.vfs/punkshell.ico (recorded as derived copies, not relocated) Acceptance: the `.assetorigin.toml` sidecar format is documented with a `schema` key, the recorded asset bound by the sidecar's own filename (suffix stripped, same directory) and the source reference relative to that directory, files ending in the suffix being records, never assets; a reader tolerates a missing sidecar, unknown keys and an unrecognised schema version without erroring; a checker written in plain Tcl - no rasterizer, no external binary, runnable under any punkshell runtime - classifies each asset it examines as exactly one of `unrecorded` (no sidecar), `verified`, `artifact-absent` (a sidecar whose paired asset is gone), `source-absent`, `replaced` or `stale` per the state table in this file, where `verified` requires every hash the sidecar records to match, so a sidecar carrying only the artifact hash is verified on that alone, demonstrably distinguishing `stale` (source changed since the artifact was generated) from `replaced` (artifact changed since recording) and from `artifact-absent` on constructed fixtures, and is advisory only, never failing a build, in the manner of the G-133 payload checks; the icon generator is reimplemented with no Windows-only component (`System.Drawing` in particular), regenerating every generated `.ico` under `src/assets/logo/` byte-identically to the current `make-ico.ps1` under the invocation profile that produced it before that script is removed, and (re)writing the sidecar of each artifact it produces - artifact and source hashes plus the invocation options - so regeneration cannot leave a stale record; and sidecars exist and verify for every generated artifact under `src/assets/logo/`, `alternative/`, `web/` and `project-default/`. + +### G-128 [achieved 2026-07-29] Portable PE resource stamping: a vendored zig tool that icons a finished kit from any host → detail: goals/archive/G-128-portable-pe-resource-stamping.md +Scope: src/tools/punkres/ (vendored zig source - tool name settled in the work - with provenance and licence records); src/make.tcl (mechanism selection at the G-057 seam, sharing G-126's tool build step); bin/tools/zig* (pinned toolchain as consumed); bin/punkres.exe (untracked build output); src/tests/ (characterization - icon replaced, payload intact, idempotent, overlay-unsafe refusal); TEMP_REFERENCE/tcl-sfe (read-only reference for the resource structures) +Acceptance: the vendored tool, built by the same make.tcl tool step G-126 establishes, replaces RT_ICON/RT_GROUP_ICON in a pre-built PE that already carries an appended zip overlay, for the kit shapes we build (kit, zip, zipcat per mapvfs.config): the new icon is confirmed by reading the resources back with the tool ITSELF (so verification does not require a windows host or twapi) and cross-checked once on windows with twapi::extract_resources; the stamped kit still boots to a working punk shell reading its payload; re-stamping converges with no resource accumulation; it works where .rsrc is NOT the last section - the shape our own runtimes have (tclsfe-x64/punk91: .text .rdata .data .pdata .rsrc .reloc; suite-built tclsh9.0.5-punk: .text .rdata .buildid .data .pdata .tls .rsrc .reloc) - by appending a section and repointing the resource data directory rather than growing .rsrc in place; the appended payload survives the file-offset shift this causes, which is safe for an ARCHIVE-relative zip and not for a file-relative one; a file-relative payload is REFUSED BY DEFAULT with an error naming the reason and the rewrap remedy, but an explicit consent flag (tool CLI and the G-057 seam, never an interactive prompt in non-interactive runs) stamps it by shifting the overlay AND rewriting every central-directory local-header offset plus the EOCD directory offset by the shift delta - deliberately PRESERVING the file-relative convention, with a notification that the format is non-standard - verified by re-reading the stamped artifact (offsetstyle still file, members crc-verified); zip64 and multi-disk archives are refused even with consent; one end-to-end run from a NON-WINDOWS host produces a stamped win32 kit whose icon a windows machine confirms (recorded here: which host); G-057's seam selects the tool when present and falls back to its twapi path otherwise, with a parity check showing both mechanisms yield equivalent resource content from the same input, and zig stays optional - with no tool built, G-057 behaves exactly as it does without this goal; the tool's distribution is settled and recorded - buildable from the vendored source with the pinned toolchain AND publishable as a punkbin artifact through the G-123/G-006 channels, so a no-toolchain user has a route that does not depend on the committed twapi; the tool's structure handling is written so the parked RT_VERSION stamping needs no second tool; licensing and upstream provenance of the vendored tree are recorded per G-063 and G-026. diff --git a/GOALS.md b/GOALS.md index c7da8d93..d6e46805 100644 --- a/GOALS.md +++ b/GOALS.md @@ -387,10 +387,6 @@ Detail: goals/G-123-thirdparty-runtime-tiers.md Scope: src/make.tcl (target-keyed output location and deploy folder, kit-name disambiguation by target, payload/target mismatch reporting, retirement of the kit-loop cross-platform TODO); src/runtime/vendorlib_vfs.toml (per-target payload declaration - format coordinated with G-115 and G-024); src/runtime/mapvfs.config (one vfs definition paired with several targets); src/vfs/ (per-target payload convention with punk9linux.vfs as the migration case); bin/kits// (non-native kit output tier, beside the existing bin/runtime// input tier); src/tests/shell/testsuites/punkexe/ (characterization - two-target bake, no-collision, mismatch report); bin/AGENTS.md + src/AGENTS.md (where cross-target kits land) Detail: goals/G-127-crosstarget-vfs-bake.md -### G-128 [active] Portable PE resource stamping: a vendored zig tool that icons a finished kit from any host -Scope: src/tools/punkres/ (vendored zig source - tool name settled in the work - with provenance and licence records); src/make.tcl (mechanism selection at the G-057 seam, sharing G-126's tool build step); bin/tools/zig* (pinned toolchain as consumed); bin/punkres.exe (untracked build output); src/tests/ (characterization - icon replaced, payload intact, idempotent, overlay-unsafe refusal); TEMP_REFERENCE/tcl-sfe (read-only reference for the resource structures) -Detail: goals/G-128-portable-pe-resource-stamping.md - ### G-130 [proposed] 32-bit windows runtimes from the buildsuites, both Tcl generations Scope: src/buildsuites/suite_tcl90/ and src/buildsuites/suite_tcl86/ (the win32-ix86 target invocation and any recipe or flag divergence 32-bit forces); src/buildsuites/ (target dimension as settled by G-105 - no per-target tree copies); bin/runtime/win32-ix86/ (output tier - already holds the third-party comparison runtimes); punkbin per-target artifact layout with G-103 metadata carrying the target Detail: goals/G-130-32bit-windows-buildsuites.md diff --git a/goals/G-101-tcl86-kit-container-strategy.md b/goals/G-101-tcl86-kit-container-strategy.md index 2a68dd01..9303f4ae 100644 --- a/goals/G-101-tcl86-kit-container-strategy.md +++ b/goals/G-101-tcl86-kit-container-strategy.md @@ -45,7 +45,9 @@ unblocked; activation is the user's call. ## Notes -- From G-128 (2026-07-29): when this goal settles the 8.6 container, include a +- From G-128 (2026-07-29; achieved 2026-07-29 - see + goals/archive/G-128-portable-pe-resource-stamping.md): when this goal + settles the 8.6 container, include a POST-HOC STAMPING-SUPPORT review for whatever it chooses - the punkres overlay taxonomy handles zip payloads natively, metakit was MEASURED move-safe (a punksys.exe copy stamped via -allow-opaque-overlay boots and @@ -53,7 +55,7 @@ unblocked; activation is the user's call. end), and any OTHER container remains unclassified (opaque-consent path, move-safety unmeasured). The G-128 acceptance's 'kit' shape is treated as satisfied-for-now on that measurement (user decision 2026-07-29, recorded in - the G-128 detail). + the archived G-128 detail). - DOWNSTREAM: G-131 (back-pointer added 2026-07-27) wants a runtime that boots from EITHER container - metakit or zipfs - detected at boot, so that the container becomes a bake-time choice and the deliverable count stops being multiplied by container. That has a direct diff --git a/goals/G-127-crosstarget-vfs-bake.md b/goals/G-127-crosstarget-vfs-bake.md index a49014ce..9acfc4b6 100644 --- a/goals/G-127-crosstarget-vfs-bake.md +++ b/goals/G-127-crosstarget-vfs-bake.md @@ -120,7 +120,10 @@ exists locally (empty but for sha1sums.txt) and punkbin upstream carries - used where embedding applies, ignored elsewhere. Every target's kit gets a .resources.toml sidecar either way (a linux-target kit records not-applicable; a win32 kit cross-baked from a non-windows host records - unavailable with the G-128 remedy named - both proven live 2026-07-29, WSL + unavailable with the G-128 remedy named (G-128 achieved 2026-07-29 - see + goals/archive/G-128-portable-pe-resource-stamping.md; cross-host kits now + EMBED via the punkres arm when bin/punkres is present, demonstrated by the + linux cross-bake in its Progress) - both proven live 2026-07-29, WSL cross-bake included), so this goal's per-target outputs inherit working record semantics. - Related: G-105 - produces the cross-target RUNTIMES this consumes for custom kits. diff --git a/goals/G-128-portable-pe-resource-stamping.md b/goals/G-128-portable-pe-resource-stamping.md index a3347d6f..b042c2b2 100644 --- a/goals/G-128-portable-pe-resource-stamping.md +++ b/goals/G-128-portable-pe-resource-stamping.md @@ -1,6 +1,6 @@ # G-128 Portable PE resource stamping -Status: active +Status: achieved 2026-07-29 Scope: src/tools/punkres/ (vendored zig source - tool name settled in the work - with provenance and licence records); src/make.tcl (mechanism selection at the G-057 seam, sharing G-126's tool build step); bin/tools/zig* (pinned toolchain as consumed); bin/punkres.exe (untracked build output); src/tests/ (characterization - icon replaced, payload intact, idempotent, overlay-unsafe refusal); TEMP_REFERENCE/tcl-sfe (read-only reference for the resource structures) Goal: punkshell can stamp windows resources into a FINISHED kit executable from any build host - no twapi, no windows host, no disturbing the appended vfs payload - so a cross-target win32 kit is not condemned to its runtime's icon, and resource stamping becomes a post-hoc operation on a built artifact rather than something wired into the middle of the kit wrap. G-057's mechanism seam selects this implementation when it is present and keeps its twapi path otherwise. Acceptance: the vendored tool, built by the same make.tcl tool step G-126 establishes, replaces RT_ICON/RT_GROUP_ICON in a pre-built PE that already carries an appended zip overlay, for the kit shapes we build (kit, zip, zipcat per mapvfs.config): the new icon is confirmed by reading the resources back with the tool ITSELF (so verification does not require a windows host or twapi) and cross-checked once on windows with twapi::extract_resources; the stamped kit still boots to a working punk shell reading its payload; re-stamping converges with no resource accumulation; it works where .rsrc is NOT the last section - the shape our own runtimes have (tclsfe-x64/punk91: .text .rdata .data .pdata .rsrc .reloc; suite-built tclsh9.0.5-punk: .text .rdata .buildid .data .pdata .tls .rsrc .reloc) - by appending a section and repointing the resource data directory rather than growing .rsrc in place; the appended payload survives the file-offset shift this causes, which is safe for an ARCHIVE-relative zip and not for a file-relative one; a file-relative payload is REFUSED BY DEFAULT with an error naming the reason and the rewrap remedy, but an explicit consent flag (tool CLI and the G-057 seam, never an interactive prompt in non-interactive runs) stamps it by shifting the overlay AND rewriting every central-directory local-header offset plus the EOCD directory offset by the shift delta - deliberately PRESERVING the file-relative convention, with a notification that the format is non-standard - verified by re-reading the stamped artifact (offsetstyle still file, members crc-verified); zip64 and multi-disk archives are refused even with consent; one end-to-end run from a NON-WINDOWS host produces a stamped win32 kit whose icon a windows machine confirms (recorded here: which host); G-057's seam selects the tool when present and falls back to its twapi path otherwise, with a parity check showing both mechanisms yield equivalent resource content from the same input, and zig stays optional - with no tool built, G-057 behaves exactly as it does without this goal; the tool's distribution is settled and recorded - buildable from the vendored source with the pinned toolchain AND publishable as a punkbin artifact through the G-123/G-006 channels, so a no-toolchain user has a route that does not depend on the committed twapi; the tool's structure handling is written so the parked RT_VERSION stamping needs no second tool; licensing and upstream provenance of the vendored tree are recorded per G-063 and G-026. @@ -434,3 +434,25 @@ the parked RT_VERSION stamping wants, since the project version is known late. - REMAINS for acceptance: the maintainer push of punkbin 1b471fc (making the fetch URL live). On push, every acceptance clause reads satisfied - flagging the achieved flip for confirmation at that point. +- 2026-07-29 PUBLICATION LIVE - acceptance FULLY MET (flip evidence): after + the maintainer push of punkbin 1b471fc, the route was verified against the + live server: punkres-x86_64-windows-0.3.1.exe fetched from + https://www.gitea1.intx.com.au/jn/punkbin/raw/branch/master/win32-x86_64/tools/, + sha1 matches the server's sha1sums.txt row and the staged value + (166cd17628f6f9457f927eb67d34c9f01c5c5646), and the fetched binary runs + (punkres 0.3.1). With that, every acceptance clause is satisfied: post-hoc + stamping with tool-self read-back + one-time twapi cross-check; kit boots; + convergent re-stamping; append-and-repoint on both documented section + shapes; file-relative default-refusal + consented offset-rewriting preserve + (offsetstyle re-verified, members crc-verified); zip64/multi-disk refusal; + the non-windows-host e2e (WSL2 Ubuntu 24.04, increment 1e, host recorded); + seam selection with twapi fallback, parity evidence and zig-optional + degradation; distribution settled BOTH ways (vendored-source build via the + pinned toolchain, and the now-live punkbin artifact route); generic + resource-tree handling ready for RT_VERSION; licensing + provenance + recorded (PROVENANCE.md per G-063/G-026). Verified on kits/runtimes: + punk91 (tclsfe 6-section shape), tclsh9.0.5-punk (8-section + .buildid/.tls), tclsh90b4_piperepl (file-relative), punksys/punk86 + (metakit via consent), punkluck86 (PE32, live bakes both arms + linux + cross-bake), zipcat construction; suites punkres upstream 33/33 both + platforms, punkres.test 8/8, punkexe 83/0. Remaining manual items: none. diff --git a/goals/G-134-baked-kits-pinned-archive-relative.md b/goals/G-134-baked-kits-pinned-archive-relative.md index b5f127ff..04c42d5c 100644 --- a/goals/G-134-baked-kits-pinned-archive-relative.md +++ b/goals/G-134-baked-kits-pinned-archive-relative.md @@ -54,7 +54,9 @@ asserts only what OUR pipeline emits by default. recapped BUILD-WARNING convention, guarded-require degradation and `make.tcl check` reporting this probe follows. - Related: G-125 - the hard-gate contrast recorded under Alternatives. -- Related: G-128 - the consumer that motivated the pin: its stamper refuses +- Related: G-128 (achieved 2026-07-29 - see + goals/archive/G-128-portable-pe-resource-stamping.md) - the consumer that + motivated the pin: its stamper refuses file-relative payloads by default (consent-flag preserve per the 2026-07-27 amendment); without this pin a pipeline regression surfaces there first, on our own kits. diff --git a/src/tools/punkres/PROVENANCE.md b/src/tools/punkres/PROVENANCE.md index ac99f345..452f8e84 100644 --- a/src/tools/punkres/PROVENANCE.md +++ b/src/tools/punkres/PROVENANCE.md @@ -10,8 +10,8 @@ state commit below identifies the exact upstream state in any clone. - Vendored state: commit `f0af880e1a1e2f27897b71bd63aa27a80ba0355e` (punkres v0.3.1, 2026-07-29; upstream working tree clean at copy time) -- Vendored: 2026-07-29 for goal G-128 (see - `goals/G-128-portable-pe-resource-stamping.md`) +- Vendored: 2026-07-29 for goal G-128 (achieved 2026-07-29 - see + `goals/archive/G-128-portable-pe-resource-stamping.md`) - Lineage: first-party punkshell tool, written 2026-07-29 for G-128 - no external code lineage. It is the portable counterpart to the twapi icon stamping of G-057: replaces RT_ICON/RT_GROUP_ICON in a FINISHED PE (including