punkshell/goals/G-067-module-artifact-channel.md

G-067 Module artifact channel: publish prepared .tm modules to and retrieve from configurable artifact servers

Status: proposed Scope: src/make.tcl or punk::mix dev commandset (publish/retrieve surface - settled in the work); user-config (consent flag + server list, G-006 pattern); src/vendormodules/ + src/vendorlib/ (retrieval targets) Goal: prepared .tm module artifacts (typically G-066 repackaged zipkits) can be published to a punkshell official artifact server and retrieved into punkshell or derived projects on declaration, following G-006's established patterns - consent gating by default, a default official source, user-configured alternative servers as replacement or addition, version pinning encoded in the artifact addressing, checksum verification where provided - sharing rather than duplicating G-006 machinery where it exists. Acceptance: a retrieve operation fetches a named module artifact at a pinned version from a configured server into the project's vendor area and the module loads via package require; no retrieval happens without explicit consent (config flag or interactive prompt; non-interactive use without the flag fails with an actionable message, never downloads silently); multiple servers are configurable with a documented precedence and both replacement and additional semantics available; artifact checksums are verified when the server supplies them and a mismatch aborts the install; a publish path to the official server is documented and demonstrated (authentication mechanism decided in the work); retrieval works from a derived project, or derived-project support is recorded as deferred with rationale; the relationship to G-006's downloader (shared implementation vs parallel with recorded justification) is a recorded design decision.

Context

G-006 establishes consent-gated artifact download for binary build artifacts (the zig-built set). Modules are a distinct artifact class with the same retrieval-shaped needs, and G-027's remote-pull question already names the G-006 channel as a candidate transport - three goals converge on one artifact-retrieval substrate. Rather than widening G-006's tightly binary-scoped acceptance, this goal gives modules their own contract on the same design pattern. The publish side is what makes the official server populatable: repackage (G-066), then push, so developers on other machines can declare and pull (G-065) instead of re-vendoring by hand.

Approach

• Addressing scheme encodes name + version (and unit id/version where the artifact belongs to a G-066 distribution unit) so pinned retrieval is a URL construction, not a server-side search.
• Consent and server-list configuration reuse the G-006 config surface (same keys or a documented sibling namespace) - one consent story for all remote artifact fetching.
• Retrieval integrates as an upstream kind in the G-065 manifest ("from artifact server X" alongside "from git repo Y"), so declared vendoring and artifact retrieval are one developer experience.
• Official-server operation (hosting, retention, signing policy) is out of scope beyond what publish/retrieve need to interoperate with it, mirroring G-006's stance on the binary-artifacts repo.

Notes

• Related: G-006 (pattern source and candidate shared implementation), G-027 (remote infrastructure-pull transport candidate), G-065 (manifest integration), G-066 (artifact payloads and distribution-unit metadata).
• 2026-07-21 (user): binary-bearing zip-based .tm (modpod) are an intended publish payload here - single-file downloadable libraries carrying manifest + binary + script. Consuming-side load extracts the binary to %TEMP%\TCL* with the TIP-741 non-cleanup flaw on windows (characterized - G-066 Notes and G-103, achieved 2026-07-22 - see goals/archive/G-103-runtime-kit-family.md). Single-lowercase- 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 (from archived G-103 - see goals/archive/G-103-runtime-kit-family.md): the family runtime -rN artifacts + toml metadata are PUBLISHED (2026-07-22, user-directed; punkbin b5c258f pushed): tclsh9.0.5-r1/-punk-r1/-punk-bi-r1 .exe+.toml in win32-x86_64/, sha1sums regenerated, defaults.txt flipped to tclsh9.0.5-punk-r1.exe in the same change-set (the recorded release process, exercised for real). r1 is now immutable - republishing those (patchlevel, variant) pairs needs -Dfamilyrev=2. Live-verified: no-name fetch resolves the new default with metadata; list -remote marks the default row and recognizes the materialized active via its toml artifact identity. These runtime artifacts are punkbin's FIRST metadata-carrying class; this goal's library class follows the same per-platform + toml pattern.
• 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, test evidence per G-107, achieved - see goals/archive/G-107-buildsuite-library-tests.md). 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.