Browse Source
Follow-on to G-004, extending the commit ban from executables to opaque-container VFS artifacts (metakit/cookfs and similar non-zip containers), executable-headed or not. Index entry + detail file with overlap survey; tracked instances inventoried (bin/sdx.kit, src/bin/sdx.kit, layout-shipped project-0.1 copy); goals_lint clean. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
2 changed files with 146 additions and 0 deletions
@ -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). |
||||
Loading…
Reference in new issue