punkshell/goals/archive/G-134-baked-kits-pinned-archive-relative.md

G-134 Baked kits pinned archive-relative: advisory offset-style probe on assembled kit images

Status: achieved 2026-07-29 Scope: src/make.tcl (post-assembly offset-style probe at the G-133 advisory-check seam, recapped reporting); src/modules/punkboot/utils-999999.0a1.0.tm (probe predicate beside the G-133 scan helpers, guarded require; bootsupport copies via established sync channels); src/tests/modules/punkboot/utils/ + src/tests/shell/testsuites/punkexe/ (characterization); src/AGENTS.md (what the pin does and does not guarantee) Goal: every kit image make.tcl assembles is verified to carry an ARCHIVE-relative zip payload - probed with punk::zip::archive_info post-assembly - so the bake pipeline's archive-relative output property becomes a checked contract rather than a by-construction accident, and any future assembly path (new kit type, modpod or accelerator change) that emits file-relative offsets surfaces at bake time instead of when G-128's stamper refuses punkshell's own kits. Acceptance: each assembled kit image is probed with punk::zip::archive_info and a recapped BUILD-WARNING naming the kit is emitted when offsetstyle is file (advisory per the G-133 posture - the kit still builds and deploys, unlike the G-125 hard gate); plain and none results (no zip attached - the metakit kit shape G-131 targets) are silence, not warnings: the pin covers zip offset convention, not the presence of a zip; today's bakes produce no warning (G-124's measured baseline: every built kit archive-relative); the probe predicate lives in punkboot::utils beside the G-133 scan helpers, called through the same guarded require so a stale bootsupport snapshot degrades it to a NOTE, and tclsh src/make.tcl check reports its ACTIVE/UNAVAILABLE state; characterization pins the warning on a file-relative kit fixture and silence on the archive-relative kit set; scope is make.tcl's own assembly paths only - punk::zip::mkzip -offsettype file and modpod's equivalent REMAIN available for deliberate manual creation of file-relative artifacts (user decision 2026-07-27: the format works and serves naive zip-tooling/SFX-repair interop, it is simply not what our pipeline emits), and external zip-repair tools' file-relative output remains tolerated on input by the G-124 reader and normalized away by any re-bake.

Context

Archive-relative output has been by-construction, never contractual: it falls out of mkzip's -offsettype archive default and modern zipfs mkimg, and G-124 measured it across the store 2026-07-26 (15 archive-relative runtimes plus every built kit; the single file-relative artifact is tclsh90b4_piperepl.exe, the historical mkimg convention). Input artifacts may legitimately be file-relative - 3rd-party zipfs kits, external zip-repair output - and the merge normalizes them because the payload is always rebuilt from extracted members. But nothing fails loudly if a future assembly path regresses the output convention; the first symptom would be G-128's stamper refusing punkshell's own kits. This goal pins the property at the seam G-133 established for advisory payload checks.

Decided 2026-07-27 alongside G-128's consented file-relative preserve amendment: the file-relative format is supported everywhere it can arrive (the reader tolerates it, the stamper preserves it with consent, the writers can emit it on request) - this pin asserts only what OUR pipeline emits by default.

Approach

• One probe at the post-assembly seam beside G-133's binary-arch scan: punk::zip::archive_info on the finished image; BUILD-WARNING unless offsetstyle is archive, recapped at end of run. Per-kit cost is one EOCD scan + central-directory walk, only when the kit rebuilds (G-124 measured ~735ms for an 841-member archive - the same order as G-133's arch scan).
• Advisory, matching G-133: warnings never block build or deploy.
• No new instrument: G-124's archive_info is the whole probe; the punkboot::utils predicate wraps it so it unit-tests without a bake.

Alternatives considered

• Hard gate (G-125-style kit failure) - rejected (user decision 2026-07-27): the property holds by construction today and make.tcl has no deliberate file-relative path; a hard gate would fire only on a regression already loud in tests and would block any future deliberate per-kit opt-out. G-125's gate exists for user-facing undeployable kits; this is a developer-facing convention notice.
• Documentation-only pin in src/AGENTS.md - rejected as enforcement-free: prose does not fire when the regression lands.

Notes

• Related: G-124 (achieved 2026-07-26 - see goals/archive/G-124-punkzip-reader.md) - supplies the probe (archive_info: offsetstyle archive|file|plain|none plus dataoffset) and the store survey that is this pin's baseline.
• Related: G-133 (achieved 2026-07-27 - see goals/archive/G-133-bake-payload-consistency-checks.md) - the advisory-check seam, 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 (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.
• Related: G-122 (achieved - see goals/archive/G-122-host-target-platform-split.md) / G-127 - the zipfs-less and cross-target assembly paths under the probe; both assemble via mkzip/mkimg archive-relative defaults today.
• Related: G-131 - metakit-shape kits carry no zip; the probe's none result is silence, not a warning.
• Overlap survey 2026-07-27: goals_xref paths src/make.tcl src/bootsupport src/tests
  • no live goals intersect src/make.tcl or src/tests; src/bootsupport produced weak lexical hits only (G-004, G-024, G-026, G-132 - bootsupport path mentions, no semantic overlap with an offset-style probe). goals_xref report reviewed: no unlinked pair concerns an output offset-convention check. The G-124/G-133 anchors are archived; the relations above are from reading.

Progress

• 2026-07-29 implemented and ACHIEVED same day (flip evidence): predicate punkboot::utils::kit_offsetstyle_report landed (punkboot::utils 0.6.0, full PUNKARGS argdoc; thin classification wrapper over punk::zip::archive_info - offsetstyle archive|file|plain|none|unreadable + dataoffset + detail), synced through make.tcl modules + bootsupport (a stale src/bootsupport/.punkcheck.lock from a dead pid was removed per the recorded recovery procedure en route) and promoted into _vfscommon via vfscommonupdate (kits carry 0.6.0 from their next bake). make.tcl gained get_kit_offsetstyle_report (same guarded-require shape as the G-125/G-133 getters), the post-assembly probe beside the smoke-require block (recapped BUILD-WARNING only when offsetstyle is file; plain/none/unreadable silent; NOTE when bootsupport is stale) and the 'check' report row ("kit offset-style pin (G-134): ACTIVE (advisory)" with the contract lines). Characterization: offsetstyle.test 7/7 (plain/archive/file fixtures built hermetically with punk::zip::mkzip -runtime/-offsettype - the deliberately available manual file-relative path exercised as the fixture generator - plus none on text and metakit-magic binary, unreadable-with-detail on a missing path, and the src/_build baseline sweep asserting no kit image probes file); maketclpayloadcheck.test gains maketcl_check_offsetstyle_pin (4/4 - status line + contract lines, ESC-free harness). Full utils suite 69/69; full punkexe suite 81 passed 0 failed. Live bake (punkluck86 rebuilt): probe silent - no NOTE (available), no BUILD-WARNING (archive-relative), matching the acceptance's today's-bakes-produce-no- warning clause. Docs per the acceptance: src/AGENTS.md gains the pin bullet with the does/does-not-guarantee statement, bin/AGENTS.md's deployed-kit section and ARCHITECTURE.md's check-family bullet extended. punkshell 0.30.7. Every acceptance clause satisfied; remaining manual items: none.