punkshell/goals/G-139-punkbin-library-consumption.md

G-139 Consume punkbin library artifacts: fetch/materialize tier replacing vendored tcllib/tcllibc

Status: active Scope: src/make.tcl (consent-gated library fetch entrypoint; libs step consuming the packages tier; vfslibs as touched); bin/packages// (new untracked materialization tier mirroring bin/runtime//); src/runtime/vendorlib_vfs.toml (tcllib/tcllibc kit-vfs declarations with supersedes removal of the legacy versions); src/vendorlib_tcl8/win32-x86_64/tcllib1.21 + src/vendorlib_tcl9/win32-x86_64/tcllib2.0 (retirement targets); src/vfs/*.vfs lib_tcl trees (kit payload switchover incl. the punk86-family tcllib 2.0 upgrade); lib_tcl8/ + lib_tcl9/ (deployed-tree materialization targets); user-config consent (server-trust pattern shared with G-123/G-006) Goal: punkshell obtains tcllib and tcllibc from the punkbin library tier (G-138) instead of committed vendored copies - a consent-gated fetch materializes verified library zips into an untracked bin/packages/ input tier from which make.tcl installs the deployed lib_tcl trees and the declared kit vfs payloads - retiring the hand-dropped src/vendorlib tcllib trees in the G-004 direction, with every materialized package self-describing via its embedded artifact record, and the derived-project story recorded (fetch as the default path; in-project suite build as the alternative). Acceptance: a make.tcl entrypoint fetches declared library artifacts from the punkbin lib tier into bin/packages// with sha1 verification and beside-toml metadata (consent keyed to server trust per the G-123 posture - fetches from the canonical origin prompt nothing new); the libs step materializes lib_tcl/allplatforms and lib_tcl/ from that tier with punkcheck-tracked provenance; tcllib and tcllibc enter src/runtime/vendorlib_vfs.toml (or its G-115/G-024 successor) declarations so the declared kit vfs trees receive them, with supersedes removing tcllib1.21 (including its nested tcllibc 0.4 and md5c) from the 8.6-family kits; the punk86-family upgrade to tcllib 2.0 + a current tcllibc is validated by kit-hosted runtests against a same-day baseline with every difference dispositioned; the vendored src/vendorlib_tcl8/win32-x86_64/tcllib1.21 and src/vendorlib_tcl9/win32-x86_64/tcllib2.0 trees are removed from the tracked tree once a bake fed from the artifact path reproduces working kits; a bake on a checkout without those trees (fetch consented or bin/packages pre-populated) ships kits whose tcllib/tcllibc provenance is verifiable from the embedded records; the derived-project decision is recorded in this file (fetch via the same entrypoint as the default - the copy-and-tweak in-project suite build per G-104's self-description contract remains the documented alternative).

Context

The publish half is G-138 (achieved 2026-07-30 - see goals/archive/G-138-punkbin-library-artifact-tier.md, including the original provenance investigation that motivated both). This goal owns the consuming side and the repo-changing consequences: what src/vendorlib_tcl means afterwards (it shrinks to genuinely hand-managed exceptions), how kit vfs trees stop drifting independently, and how derived projects get the same packages.

State at drafting worth recording:

• The deployed lib_tcl8|9 trees are pure punkcheck mirrors of src/vendorlib_tcl8|9 (make.tcl VENDORLIB_tcl step); src/lib_tcl8|9 are empty. So switching the vendorlib source of truth switches the deployed trees with no second mechanism.
• Kit vfs copies of tcllib (punk86/punk8win/punk8min/punk86bawt/ punk8_statictwapi lib_tcl8/tcllib1.21; mkzipfix/punk9cook-family lib_tcl9/tcllib2.0) are INDEPENDENT hand-drops from the same 2024 import - vendorlib_vfs.toml declares only tcludp today. Bringing tcllib/tcllibc under the G-037 declaration mechanism is part of this goal, not an aside.
• The 8.6 side is a version upgrade, not a swap: vendored is tcllib 1.21 + tcllibc 0.4 (2023, critcl 3.2); the suite builds tcllib 2.0 + tcllibc (critcl 3.3.1, zig cc). G-100 (achieved 2026-07-26) already ran punkshell runtests on the suite-built 8.6 runtime - this goal's validation burden is the KIT payload upgrade, using the established kit-hosted runtests method (vfscommonupdate-current kits, per the recorded traps).
• Orphaned stray copies were cleared 2026-07-30 ahead of this work: lib_tcl8/test_old + lib_tcl9/test_old moved (untracked, never on auto_path) to TEMP_REFERENCE/retired_lib_tcl_test_old/. Remaining known strays to sweep during the switchover: bin/test2/lib_tcl9/tcllib2.0, scratch/tclkit86bi.vfs/lib/tcllibc.

Approach

• bin/packages// mirrors the bin/runtime// input-tier idiom (untracked working copies + beside-toml metadata, sha1-verified on materialization); allplatforms is a target value here exactly as in the punkbin lib tier.
• Unzip via the punk::zip/punkzip machinery already in the tree; installs out of bin/packages into lib_tcl ride the existing punkcheck::install path so provenance/skip-unchanged behaviour matches the current vendorlib step.
• vendorlib_vfs.toml gains install entries for tcllib + tcllibc per generation, source paths pointing at the materialized tier; supersedes handles the legacy-version removal (the explicit no-silent-mixed-version mechanism it was built for). If G-115/G-024 land their toml consolidation first, the declarations ride the successor surface.
• Consent: no new mechanism - the server-trust posture of G-123 (canonical punkbin origin trusted by default; G-006's mechanism when landed, else the interim documented flag). Unattended bakes stay unattended.
• Retirement sequencing: artifact path proven (bake + kit checks green) BEFORE the vendored trees are removed; removal is its own commit so the fallback is a revert.
• Derived projects: default is the fetch path (their make.tcl copy gains the same entrypoint via the layout/G-027 update channels); projects wanting source-level control copy a suite (G-104 self-description contract) and build in-project - a tcllib/tcllibc-only suite needs no Tcl source tree (critcl bundles its own headers; any punk runtime can drive it), which keeps that alternative genuinely light. The stale samplesuite1 download_and_build.config stub in the project-0.1 layout should be replaced or removed as part of recording this story.

Alternatives considered

• Keep vendoring (suite output committed into src/vendorlib) - rejected: G-004 direction; see the archived G-138 Alternatives (goals/archive/G-138-punkbin-library-artifact-tier.md).
• Fetch directly into lib_tcl with no bin/packages tier - rejected: the input-tier split (immutable verified artifact copy vs punkcheck-installed deployment) is what makes re-bakes, freshness checks and multi-kit propagation coherent; it mirrors the proven runtime-tier design.
• Blanket-copy fetched packages into every kit vfs - rejected: per-package per-kit declaration is the settled G-037 design (kit package sets intentionally differ).

Notes

• Related: G-138 - the publish half; this goal consumes its tier. ACHIEVED 2026-07-30 (see goals/archive/G-138-punkbin-library-artifact-tier.md). What it settled that this goal consumes: artifact naming is <installed folder>-<tcl8|tcl9>-r<N>.zip (generation tag is identity - the tcl8/tcl9 builds are different bytes under identical folder names); each zip carries the package folder in installed shape + embedded schema-v2 class=library record at <folder>/punkbin-artifact.toml; md5c is DROPPED (tcllib's md5 prefers tcllibc, which bundles the accelerator) - so the supersedes removal of tcllib1.21's nested md5c needs no replacement package; emitted-but-unpublished artifacts stage under each suite's out/library/punkbin/lib/ (r1, nothing published yet - publication is the user step this goal's fetch consumes afterwards); punkbin build_sha1sums.tcl already handles the lib tier and its AGENTS.md documents the record schema.
• Related: G-123 - shared consent posture and materialization idiom (bin/runtime/ : runtimes :: bin/packages/ : libraries).
• Related: G-004 - the vendored-tree retirement is its first major payoff.
• Related: G-006 - consent surface, as coordinated through G-123.
• Related: G-065 - declarative vendoring generally; this goal implements the artifact-fetch shape for the tcllib case specifically, and G-065 should absorb or reference the resulting pattern rather than duplicate it.
• Related: G-115/G-024 - vendorlib_vfs.toml consolidation surfaces; the declarations here ride whichever surface is current.
• Related: G-027 - how derived projects receive the updated make.tcl entrypoint.
• Anchors (archived): G-037 (vendorlib -> kit vfs propagation mechanism and its supersedes design), G-100 (8.6 suite runtime validation this builds on), G-104 (buildsuite self-description contract the in-project-build alternative leans on - goals/archive/G-104-maketcl-buildsuite-surface.md), G-119 (freshness/row vocabulary if library listing surfaces are added - goals/archive/G-119-runtime-active-freshness.md).
• Overlap survey 2026-07-30 (drafting): shared with G-138 (see its Notes); additionally src/vfs intersects G-115/G-127/G-065 (payload declaration surfaces - carried as Related) and lib_tcl/make.tcl show no live-goal intersections.
• Activation survey 2026-07-30: goals_xref score G-139 re-run at activation (user-directed, same day as drafting - no goals drafted in the interval); no overlaps beyond the drafting survey.