punkshell/goals/G-157-exeless-kits-materialized.md

G-157 Exe-less kits materialized, never committed

Status: proposed Scope: repo-wide commit policy for opaque-container VFS artifacts (metakit/cookfs kit files and similar non-zip containers); bin/sdx.kit + src/bin/sdx.kit (tracked instances); src/project_layouts/vendor/punk/project-0.1/bin/sdx.kit (layout-shipped instance, seeding replacement, binary-glob note); src/make.tcl (sdx resolution ladder materialization rung, store->modpod sync exclusions); src/buildsuites/suite_tcl86/patches/ (sdx source capture, rebuild arm); punkbin tools tier (external c:/repo/jn/punkbin download channel); root AGENTS.md (no-new-binaries rule extension); G-004 scan extension (content-signature detection) Goal: the committed punkshell repository contains no exe-less kits or other artifacts in opaque VFS-container formats (metakit, cookfs, and similar non-zip containers), executable-headed or not: any such artifact the project uses - the sdx.kit wrapping tool today - is materialized on demand via a build step or a consent-gated download (the punkbin tools/libs pattern), and the committed tree carries only transparent sources (scripts, zip archives per G-004 content rules) sufficient to produce it. Acceptance: a content-signature scan of the committed tree (the G-004 step-4 scanner or a sibling check recognising metakit and cookfs container signatures regardless of extension or script header) reports zero opaque-container artifacts; bin/sdx.kit, src/bin/sdx.kit and src/project_layouts/vendor/punk/project-0.1/bin/sdx.kit are no longer tracked; on a clean checkout the make.tcl 'kit' wrap path succeeds by materializing its wrapping tool via the build or consent-gated download rung; a generated project's kit-wrap need is met by generation-time injection or its own materialization step with no kit stored in the layout store; the settled generic terminology is recorded in this detail file and used in the scan's report vocabulary.

Context

G-004 bans committed EXECUTABLES. Metakit-based exe-less kits (sdx.kit and kin: tkchat.kit, critcl.kit, twapi-dtp.kit, oomk.kit, ratcl.kit) are not technically executables - typically a shebang/script header, a ctrl-z, then the vfs payload - and metakit is an open format under an open-source license. They would pass a naive executable scan. But they are OPAQUE compared to zip: third-party package managers, scanners and reviewers cannot list or inspect them with stock tooling. The same applies to cookfs images and any other niche container format. Opacity, not executability, is the property this goal adds to the commit policy: the two axes are orthogonal, and G-004 + G-157 together cover the quadrant grid (executables banned by G-004 whatever the container; opaque containers banned here whether or not runnable).

The transparent-container set is zip today, matching G-004's zip-based .tm exception vocabulary and its content-not-extension rule (a zip-based exe-less kit follows the same content rule: allowed only if it embeds no executables). Extending the transparent set (e.g. tar) is a policy decision to record here if it arises; the tarjar-artifact dispositions were confirmed under G-111 (achieved 2026-08-03, all keeps - see goals/archive/G-111-modpod-tidy-tests.md).

Current tracked instances - exactly three, all sdx.kit:

• bin/sdx.kit: the locally-patched 2011-era sdx that make.tcl's 'kit' wrap path resolves as its last-resort rung (src/make.tcl sdx ladder ~:7639).
• src/bin/sdx.kit: sole file in src/bin/; no live references found (apparently vestigial - disposition confirmed at inventory).
• src/project_layouts/vendor/punk/project-0.1/bin/sdx.kit: deliberately layout-shipped (the layout's .fossil-settings/binary-glob documents it), so generated projects receive a copy.

The exit is unusually well prepared:

• The store->modpod layout sync already EXCLUDES bin/sdx.kit (make.tcl:7011,7028 "no new binaries") - this goal completes that started hygiene.
• sdx upstream is GONE (svn.equi4.com, last ChangeLog 2011-03-17), but the payload is 64 plain Tcl files; the single-file local patch (wrap.tcl) is captured byte-exact with its stock baseline in src/buildsuites/suite_tcl86/patches/ (see its README).
• G-101 (achieved 2026-08-02) broke the sdx bootstrap circularity: the suite-built tclsh86t + fork-built Mk4tcl run sdx.kit end-to-end including the wrap surface (qwrap/lsk/unwrap round-trip verified). Wrap-on-demand from transparent sources is therefore proven, and this goal does not depend on the full G-005/G-006 arcs to become achievable.

Mirror of G-004's working-mode preservation: the ban is on the COMMITTED punkshell tree only. Uncommitted kits dropped into the working tree stay first-class for local experimentation; producing exe-less kits as build OUTPUTS stays fully supported (the 'kit' bake type, G-131's either-container world); derived projects set their own policy (the layout's permissive binary-glob posture is the generated project's prerogative).

Approach

1. Terminology. Settle the generic moniker and record it here and in the scan's report vocabulary. Recommended: "exe-less kit" for the runtime-external runnable artifact (any container), "starkit" retained as the metakit-specific historical instance, "opaque-container artifact" as the policy classification the scan reports.
2. Inventory by content signature (metakit tail signature, cookfs signature) over the tracked tree - confirm the three sdx.kit copies are the only instances, and settle src/bin/sdx.kit's vestigial status.
3. Secure transparent provenance for sdx before any removal: unwrap the patched kit to a tracked source tree (per-file license verification, G-063 posture - 2011-era Tcl-licensed components) and/or publish the kit to the punkbin tools tier with provenance (G-128 punkres route). Prefer source-tree + wrap-on-demand; G-101's reduction-not-refresh posture applies to any rebuild.
4. Materialization rungs in make.tcl's sdx resolution ladder: wrap-from- source under a mk4-capable suite shell (folds in G-101's recorded follow-on to add the suite-shell rung) and/or consent-gated punkbin fetch using the existing libfetch/punk-runtime trust-flag shape, absorbed by G-006's mechanism when that lands.
5. Layout seeding: remove the layout-store kit; meet the generated project's need per the G-136 pattern (generation-time injection from a single punkshell-held artifact) or via the generated project's own synced make.tcl materialization rung; update the store->modpod sync exclusion and the layout's binary-glob comment accordingly.
6. Remove the three tracked copies only after 3-5 verify on a clean checkout; add ignore rules so local drop-in copies stay conveniently uncommitted.
7. Extend the G-004 step-4 scan (or a sibling check) with opaque-container content signatures so regressions are caught; share its verification surface.
8. DOX: extend the root AGENTS.md no-new-binaries standing rule to opaque-container artifacts as the interim guard (agents must not ADD new ones; the existing sdx.kit copies stay known-and-intentional pending this goal).

Alternatives considered

• Ban by .kit extension - rejected: extension-based classification misses renamed containers and false-positives transparent zip kits; content signature is the established G-004 lesson.
• Treat exe-less kits as permitted because the format is open and the license is open-source - rejected: openness of the format does not give third-party packagers practical inspectability; opacity is the operative property (the user's framing motivating this goal).
• Fold into G-004 by widening its acceptance - rejected: G-004's contract is executables and is already load-bearing across many notes; a sibling goal keeps that contract stable, and this goal is achievable earlier (tiny artifact set, proven run-stack).
• Keep bin/sdx.kit tracked alongside a vendored source tree - rejected: the kit is derivable from the source tree; keeping both re-introduces the opaque artifact the goal exists to remove.

Notes

• Related: G-004 - parent policy; this goal extends the commit ban from executables to opaque-container non-executables and shares its step-4 scan seam.
• Related: G-006 - the consent-gated download channel this goal's fetch rung rides (interim libfetch/punk-runtime trust flags absorbed by G-006 when it lands).
• Related: G-005 - the build-from-source channel; the sdx rebuild arm is suite work (suite_tcl86).
• Related: G-142 - a published sdx.kit artifact would appear in the punkbin tools-tier listing manifests.
• Related: G-131 - consumption-side sibling: runtimes mounting either container keep exe-less kits first-class as inputs/outputs; this goal governs only what is committed.
• Related: G-136 - the layout-seeding pattern analogue (single punkshell-held master, generation-time injection, nothing stored in layout trees) for the layout's sdx.kit slot.
• Archived context: G-101 (sdx provenance, circularity broken, suite-owned writer option (b) recorded - see goals/archive/G-101-tcl86-kit-container-strategy.md); G-153 (metakit fork buildable from source); G-128 (punkres, first punkbin tools-tier artifact - the download-route precedent); G-126 (archived - punkzip, vendored-source tool precedent); G-139 (archived - consent-flag shape).
• Overlap survey 2026-08-02 (goals_xref paths over bin/sdx.kit, src/bin, src/project_layouts, src/buildsuites/suite_tcl86, src/vfs, src/make.tcl): surveyed and judged not related in substance: G-137, G-141, G-147 (bin/ path siblings only), G-105/G-130 (buildsuite target dimension), G-047/G-086/G-114/G-156 and G-031 (achieved 2026-08-02, since archived) (layout-store neighbours).
• Related: G-171 - shares the working-modes-stay-first-class posture, and moves the store->modpod sync (whose exclusion list this goal edits for bin/sdx.kit) out of the mint commands into an explicitly-invoked command.