punkshell/goals/G-006-prebuilt-artifact-download.md

G-006 Optional pre-built binary artifact download with consent gating

Status: proposed Scope: src/runtime/, src/make.tcl integration, user-config (consent flags) Goal: pre-built binary artifacts can be downloaded from a separate related binary-artifacts repository or user-configured sources, gated by explicit user consent/configuration by default. Acceptance: a download mechanism fetches binary artifacts (the same set the zig build produces) from a configured source on demand; by default the download is gated behind explicit user consent (a config flag or interactive prompt) and does not occur silently; a user-configured source URL overrides the default binary-artifacts repo; downloaded artifacts satisfy the same build requirements as zig-built artifacts so tclsh src/make.tcl project succeeds with downloaded artifacts in place of built ones.

Context

Not every user of Punkshell will have the zig toolchain installed or want to build binary dependencies from source. This goal provides the alternative: download pre-built artifacts. It is the complementary mechanism to G-005 (zig build); both produce the same artifact set that G-004 requires in place of committed binaries.

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.

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.

Approach

1. Download mechanism. Implement a downloader (likely in src/runtime/ or integrated into make.tcl) that fetches a named artifact from a configured source URL to the location the build expects. Verify checksums/signatures where the artifact source provides them.

2. Consent gate. Before any download, check a consent flag in user config. If unset, either prompt interactively (when the build is interactive) or fail with an actionable message telling the user how to set the flag (when non-interactive). Once set, record the consent so subsequent builds don't re-prompt. The gate must not be bypassable by accident — a silent download on first build is a failure of this goal's acceptance.

3. Source configuration. A config value for the artifact source URL, defaulting to the separate binary-artifacts repo. A user-configured value overrides the default. Document the config key and the expected source format (URL layout, artifact naming convention).

4. Integration with make.tcl. When make.tcl needs a binary artifact that isn't present and the zig build path (G-005) is not available or not chosen, the download path is offered/followed per the consent gate. The integration must make tclsh src/make.tcl project succeed with downloaded artifacts in place of built ones — the artifacts are interchangeable from the build's perspective.

5. Artifact equivalence. Downloaded artifacts must satisfy the same build requirements as zig-built ones (same file shape, same location, same version). If a downloaded artifact differs in a way the build cares about (e.g. different Tcl9 patchlevel), the build must detect and reject it rather than producing a subtly broken system.

Alternatives considered

• Always download silently on first build. Rejected: the user's requirement is explicit consent gating. Silent network access on first build is a privacy/security concern and surprising behaviour.
• Download only, no build path (drop G-005). Rejected: the user wants both paths. Build-from-source (G-005) is the reproducible/auditable path; download is the convenience path.
• Interactive prompt only, no config flag. Rejected: non-interactive builds (CI, scripts) would have no way to consent. Both a config flag (for non-interactive) and a prompt (for interactive) are needed.
• Bundle the binary-artifacts repo into this repo. Rejected: that would defeat G-004's aim — the binary artifacts would still be in version control, just in a sub-repo. The artifacts repo is separate by design.

Notes

• Parallel to G-005. Both feed G-004.
• The separate binary-artifacts repository is a sibling to this source repo, not a subdirectory or submodule. Its maintenance is out of scope for this goal; this goal only consumes from it.
• The consent gate is the defining behavioural requirement of this goal. A download mechanism without the gate fails the acceptance even if the artifacts arrive correctly.
• Consider version-pinning: downloaded artifacts should match the versions the build expects, not "latest". The source URL scheme should encode version so a user gets a consistent artifact set.
• If a user configures a source that serves a malicious/tampered artifact, checksum/signature verification is the mitigation. Whether the default binary-artifacts repo signs artifacts is a decision for that repo; this goal's acceptance is satisfied by the download + consent mechanism, with verification as a hardening step.
• No persisted prior chat on this topic was found in project sessions; the motivation is the user's stated intent.