diff --git a/GOALS.md b/GOALS.md index d11fb7a2..9d9c9dd1 100644 --- a/GOALS.md +++ b/GOALS.md @@ -402,3 +402,7 @@ Detail: goals/G-151-punkargs-annotated-success-render.md Scope: src/modules/punk/mix/cli-999999.0a1.0.tm + src/modules/punk/mix/base-999999.0a1.0.tm (mint-named installer surface, identity migration); src/make.tcl (BUILDCOPY -> BAKECOPY, identity references, buildversion.txt readers); modules/.punkcheck + derived-project .punkcheck ledgers (identity migration or accepted re-record); src/modules/*-buildversion.txt sidecar convention + module-header boilerplate (disposition decided at activation); scriptlib/developer/ (census scanner + committed census report); src/project_layouts + src/modules/punk/mix/#modpod-templates-999999.0a1.0/ (re-seeded identities via established sync channels); machine-wide census over user-confirmed roots (fossil config-db enumeration + bounded filesystem scan, punkorigin.toml + pre-G-087 marker fallbacks, siblings incl c:/repo/jn/tclmodules/tomlish + c:/repo/jn/serversecretsync + c:/repo/jn/punkbin); punkbin repo schema fields (build_id, build_sha1sums.tcl - disposition only) Detail: goals/G-156-alpha-window-identifier-alignment.md +### G-157 [proposed] Exe-less kits (starkits etc.) and other opaque-container artifacts are materialized, never committed +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) +Detail: goals/G-157-exeless-kits-materialized.md + diff --git a/goals/G-157-exeless-kits-materialized.md b/goals/G-157-exeless-kits-materialized.md new file mode 100644 index 00000000..063ff520 --- /dev/null +++ b/goals/G-157-exeless-kits-materialized.md @@ -0,0 +1,142 @@ +# 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; tarjar disposition stays with G-111. + +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).