punkshell/goals/G-004-no-committed-binaries.md

G-004 No executable binaries committed to the repository

Status: proposed Scope: repo-wide (bin/, src/vfs/, src/vendorlib/, src/vendormodules/, src/bootsupport/) Goal: the committed repository contains no executable binaries; zip-based .tm modules are allowed but not if they embed executables. Acceptance: a scan of the committed tree finds no executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O); any zip-based .tm modules present contain no embedded executables; the binary artifacts previously committed are retrievable via G-005 (build from source) or G-006 (pre-built download) so their removal does not break builds.

Context

The ultimate aim is that the committed repository contains no executable binaries. This is a hygiene and reproducibility goal: binaries in version control are opaque to review, bloat the repo, and make the build non-reproducible from source. Today the repo violates this — binary libraries are committed in the VFS folders (src/vfs/), src/vendorlib/, src/vendormodules/, and src/bootsupport/. These are present because there is currently no automated way to rebuild or retrieve them; removing them before an alternative exists would break builds on a clean checkout.

Two further motivations recorded 2026-07-22 (user framing):

• Third-party distribution eligibility: a binary-free punkshell is a candidate for distribution platforms that disallow checked-in binaries.
• The consent promise as a product commitment: punkshell guards the promise that binaries reach the user's machine over the network ONLY by explicit user action/consent unless configured otherwise (the G-006 gate and its G-067 sibling are the enforcement points). A binary-free repo makes the promise auditable: everything binary is retrieved, and every retrieval is consented.

Zip-based .tm modules are a permitted exception to the "no binaries" rule because they are module archives, not executables — but a zip-based .tm that embeds an executable (e.g. a native shared library packaged inside the module) is not permitted. The distinction is content, not file extension.

This goal is the integrating outcome of two enabling goals:

• G-005 provides the build-from-source path (zig build of Tcl9 and other dependencies).
• G-006 provides the pre-built download path with consent gating.

Both must be in place before the committed binaries can be removed without breaking builds, so G-004 sequences after both.

A standing repo-wide rule in root AGENTS.md (User Preferences) already directs agents not to commit new executable binaries, while explicitly not hassling the developer about existing vendor/vfs binaries committed pending this goal's achievement.

Approach

1. Inventory. Identify every executable binary currently committed across bin/, src/vfs/, src/vendorlib/, src/vendormodules/, and src/bootsupport/. Classify each by what it is (Tcl9 shared lib, twapi, other native extension) and which goal path (G-005 build / G-006 download) will replace it.

2. Verify alternatives work. Before removing any binary, confirm the corresponding G-005 build or G-006 download produces an artifact that satisfies the build. Removal without a working replacement breaks clean-checkout builds — the acceptance explicitly requires the alternative retrieval to work.

3. Remove. Delete the committed binaries from the tree. Update .gitignore / .fossil-settings/ignore-glob if needed to prevent re-addition.

4. Add a scan to verification. Add a scan step (script or make.tcl target) that checks the committed tree for executable binaries and fails if any are found, so regressions are caught. The scan must recognise the zip-based .tm exception: a .tm that is a zip is allowed; a .tm (or any zip) containing an embedded executable is not.

5. DOX update. Once achieved, the AGENTS.md "no binaries" user-preference note can be simplified from "agents must not; existing violations pending" to "agents must not; scan enforced" — but the rule itself stays.

Alternatives considered

• Delete binaries now, document manual fetch. Rejected: no automated retrieval, so every contributor hand-fetches. The intended system (G-005/G-006) exists precisely to avoid this.
• Allow committed binaries permanently. Rejected: this is the explicit ultimate aim the user stated. Not a real alternative.
• Permit zip-based .tm with embedded executables. Rejected: the user's wording is explicit — "those zip-based .tm modules that contain executables should also not be directly checked in." The content matters, not the extension.
• Fold G-005 and G-006 into this goal. Rejected: the build system and download system are each large bodies of work with their own acceptance, and they're independently useful before all binaries are removed. Bundling would make G-004 uncheckable until two large systems are built, and would grow past a one-line-safe summary.

Notes

• 2026-07-22 (user framing): achieving this goal must NOT stop binaries OPERATING in the tree - the no-checkin policy is about the COMMITTED tree only. Two working modes stay first-class forever: (a) quick local experimentation with uncommitted binaries dropped into the working tree; (b) derived projects (dev project.new) with a PERMISSIVE binary policy - generated projects may commit binaries under their own rules. Consequences for the Approach: the step-4 scan targets the committed tree (never a working-tree police); ignore rules added at removal time double as the drop-in enablement (local binaries stay conveniently uncommitted); and boot/loading machinery (auto_path platform dirs, tm roots, libunknown, modpod) must keep supporting in-tree binaries indefinitely - G-114's same-version drop-in-replacement acceptance is the tm-side expression of the same requirement. Layout seeding keeps the binary policy per-project (punkshell strict, derived projects owner-chosen).
• 2026-07-22 (user framing + assessment): EXIT PATHS for the src/vfs/*.vfs interim exception - the .vfs binary payloads leave the committed tree via some mix of: (i) suite-built runtime batteries (G-103, achieved 2026-07-22
  • see goals/archive/G-103-runtime-kit-family.md - attached images already shrink kit .vfs payloads toward pure punkshell script payload); (ii) per-package punkbin LIBRARY artifacts (G-067 channel - buildsuite-built .tm/pkg libraries as a second punkbin artifact class) declared into kit assembly; (iii) possibly whole zipped binary-carrying .vfs archives as a THIRD punkbin artifact class. Assessment 2026-07-22 (agent, user question): prefer (i)+(ii) as the primary paths - per-package artifacts dedupe across kits, keep provenance/versioning granular, reuse the platform canon and the G-103 metadata pattern, and share one consent story; whole-.vfs archives couple unrelated components and churn on any payload change, so (iii) is recorded as an OPEN option for release-snapshot/derived-project convenience rather than the primary mechanism - decide when removal actually forces the payloads out. A declarative .vfs composition surface (toml-defined payload pulling from (i)/(ii), preserving drop-in simplicity) is the candidate glue - see the G-115 proposal (2026-07-22) if adopted.
• Depends on G-005 and G-006. Sequence G-005 ∥ G-006, then G-004.
• The scan in step 4 should distinguish "executable binary" from "zip archive" and from "zip archive containing an executable." A naive extension-based check is insufficient; content inspection (file magic, zip listing) is required.
• The AGENTS.md user-preference rule is the transition guard: it stops agents from adding new binaries during the G-005/G-006 development period while the developer's existing vendor/vfs binary commits are known and intentional.
• No persisted prior chat on this topic was found in project sessions; the motivation is the user's stated ultimate aim.