diff --git a/goals/G-004-no-committed-binaries.md b/goals/G-004-no-committed-binaries.md index edd2b509..bb7d1971 100644 --- a/goals/G-004-no-committed-binaries.md +++ b/goals/G-004-no-committed-binaries.md @@ -9,6 +9,16 @@ Acceptance: a scan of the committed tree finds no executable binaries (shared li 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: @@ -40,6 +50,37 @@ A standing repo-wide rule in root `AGENTS.md` (User Preferences) already directs ## 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 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. diff --git a/goals/G-006-prebuilt-artifact-download.md b/goals/G-006-prebuilt-artifact-download.md index 58315b3c..6e08d350 100644 --- a/goals/G-006-prebuilt-artifact-download.md +++ b/goals/G-006-prebuilt-artifact-download.md @@ -13,7 +13,7 @@ Two source categories: 1. **Default:** a separate, related binary-artifacts repository (sibling to this source repo, not part of it) holding pre-built artifacts for supported platforms. 2. **User-configured:** a user-supplied source URL (internal mirror, local file server, etc.) that overrides the default. -The critical behavioural requirement is **consent gating by default**: the download must not happen silently. A first-time build that silently reaches out to a remote source would be surprising and a network-exfiltration concern. The user must explicitly opt in — via a config flag set before the build, or an interactive prompt at build time — before any download occurs. Once consent is given (e.g. a config flag persisted), subsequent builds for the same artifact set don't re-prompt. +The critical behavioural requirement is **consent gating by default**: the download must not happen silently. A first-time build that silently reaches out to a remote source would be surprising and a network-exfiltration concern. (2026-07-22 user framing: this gate is a PRODUCT COMMITMENT, not just anti-surprise hygiene - punkshell promises that binaries are only retrieved from the network by explicit user action/consent unless configured otherwise. This goal and its G-067 sibling are the enforcement points; a binary-free repo per G-004 is what makes the promise auditable.) The user must explicitly opt in — via a config flag set before the build, or an interactive prompt at build time — before any download occurs. Once consent is given (e.g. a config flag persisted), subsequent builds for the same artifact set don't re-prompt. This goal is parallel to and independent of G-005. A user with zig uses G-005; a user without zig (or choosing not to build) uses G-006. Either path satisfies G-004's retrieval requirement. diff --git a/goals/G-067-module-artifact-channel.md b/goals/G-067-module-artifact-channel.md index d651e845..2fe79d37 100644 --- a/goals/G-067-module-artifact-channel.md +++ b/goals/G-067-module-artifact-channel.md @@ -42,3 +42,16 @@ and pull (G-065) instead of re-vendoring by hand. name .tm (TIP 590) are plain-tclsh loadable; multi-require-name .tm need libunknown (punkshell-only, must be documented). Generation + multi-name discovery detail: G-066 Notes. +- 2026-07-22 (user framing): the zig BUILDSUITES are a producing source for this + channel - libraries the suites build (thread/tk/tcltls-class) get packaged as + per-platform .tm/pkg artifacts when they are not going directly into a kit, and + published to punkbin, which grows from a runtimes-only repo into MULTIPLE + ARTIFACT CLASSES (runtimes + module/library artifacts; a possible third class - + whole zipped binary .vfs archives - is recorded as open in G-004 Notes with a + prefer-per-package assessment). Library artifacts follow the platform canon + (punk::platform dir names; one platform per file per G-114's segregation + rationale) and carry G-103-style metadata (versions, provenance uuids, + toolchain, G-107 test evidence). Retrieval-target interplay with G-004: fetches + land in working-tree vendor areas - in punkshell itself ignore rules keep them + UNCOMMITTED (the committed tree stays binary-free; the promise stays auditable), + while derived projects commit them or not per their own binary policy. diff --git a/goals/G-114-per-platform-tm-roots.md b/goals/G-114-per-platform-tm-roots.md index d67d35cf..534855e5 100644 --- a/goals/G-114-per-platform-tm-roots.md +++ b/goals/G-114-per-platform-tm-roots.md @@ -38,6 +38,13 @@ inside a .tm loads via the extraction path investigated there), G-034 (8.6 modpod mount path - bears on the 8.6 leg of acceptance), punk::platform (canonical platform names; 'help platforms'). +Provenance boundary (2026-07-22 user framing, G-004): the binary .tm these +roots hold are NEVER checked into punkshell - they arrive via the G-067 +artifact channel (punkbin library-class artifacts, consent-gated) or as local +uncommitted drop-ins, and the same-version drop-in acceptance below is the +tm-side expression of G-004's binaries-must-still-operate-in-tree +requirement. Derived projects may commit them under their own binary policy. + Nothing needs this until binary-bearing .tm distribution starts in earnest - creating empty tm-root siblings ahead of that machinery would be speculative structure (2026-07-22 assessment). The goal exists so the layout and boot