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