punkshell/goals/G-140-linux-lib-tier-emission.md

G-140 Linux lib-tier emission: cross-built tcllibc (zig cc -target) for the punk9linux payload

Status: proposed Scope: src/buildsuites/suite_tcl90/ (critcl_zig.config linux target section; build905.zig cross-target library-artifacts lane; tools as touched); src/runtime/libpackages.toml + src/runtime/vendorlib_vfs.toml (linux-x86_64 artifact + kit-vfs declarations); src/vfs/punk9linux.vfs/lib_tcl9 (hand-dropped tcllibc + stray tcllibc2.0 - retirement targets); punkbin artifact repo (external, c:/repo/jn/punkbin - new lib/linux-x86_64 target folder); bin/packages/linux-x86_64/ (tier target as materialized); WSL verification (testsupport/wslprobe.tcl patterns + a punkbin linux-x86_64 Tcl 9 runtime as the smoke interpreter) Goal: the punkbin lib tier serves a linux-x86_64 tcllibc built by the existing windows suite - critcl driving zig cc with an explicit linux target (stubs linkage: no cross-built Tcl runtime and no linux build host required) - emitted through the established G-138 machinery (generation-tagged immutable zip, embedded class=library record whose target is linux-x86_64 and whose build_host_platform records the actual build host), verified functional under the local WSL with an existing linux Tcl 9 runtime, and consumed by punk9linux.vfs through the established G-139 declaration path - retiring the last provenance-less accelerator hand-drops (tcllibc + the stray-named tcllibc2.0) so every accelerator in every kit payload is artifact-fed and self-describing. Acceptance: a documented suite_tcl90 invocation produces lib/linux-x86_64/tcllibc-tcl9-r.zip from a critcl build driving zig cc via an explicit linux target section in critcl_zig.config (the win32-x86_64-zig pin pattern; no linux host in the build path), with the embedded record carrying target = linux-x86_64, build_host_platform = the actual build host, and the G-138 provenance set (checkout uuids, critcl version, zig version, optimize mode, driving-shell patchlevel); the contained shared library classifies as ELF x86-64 by a host-side structural check (the G-133 classifier or equivalent, recorded here); re-emission over an unchanged build is byte-identical; the libc/triple decision (dynamic glibc with a pinned version floor vs musl-dynamic - the .so must dlopen into existing glibc-dynamic linux tclsh builds without mixing libcs) is made and recorded here with rationale, explicitly feeding the G-105 decision item rather than re-deciding it later; a WSL (or native linux) smoke on the MATERIALIZED artifact tree under a linux-x86_64 Tcl 9 runtime (e.g. the punkbin tclkit-902 artifact) proves package require md5 engages the critcl accelerator from the tree (evidence recorded here); consumption lands via libpackages.toml (target linux-x86_64) and a vendorlib_vfs.toml entry switching punk9linux.vfs/lib_tcl9 with supersedes/replace retiring the hand-dropped tcllibc and tcllibc2.0; a punkshell902 bake ships the artifact-fed tree with its embedded record present in the kit payload, and a WSL run of the baked kit loading md5 with the accelerator engaged is recorded; publication to the real punkbin repo remains a deliberate user step (build_sha1sums.tcl already handles arbitrary lib/ folders); the tcl8-generation question is dispositioned (no linux tcl8 kit exists - recorded as out of the committed set, with the mechanism staying package-generic and generation-generic by construction).

Context

Flagged at the G-139 achieved flip (2026-07-30): punk9linux.vfs kept its linux-built tcllibc + tcllibc2.0 sibling folders through the switchover because the win32-x86_64 artifacts cannot serve a linux kit - they are now the last accelerator hand-drops in any kit payload, carrying the same no-provenance profile the retired win32 trees had (and a stray versioned folder name besides). The pure-Tcl side is already artifact-fed: punk9linux.vfs receives the allplatforms tcllib2.0 artifact like every other declared kit.

Why this does not wait for G-105: tcllibc is a stubs-linked extension - critcl bundles its own Tcl headers and links nothing from a Tcl runtime, so cross-compiling the .so needs only zig cc -target plus a critcl config section; the installer/critcl DRIVER runs under the existing suite-built windows shell. G-105's committed content (cross-built tclsh, WSL core-testsuite baseline, per-target out prefixes, the general triple<->canon mapping) is not on this goal's path; the smoke interpreter is an EXISTING linux runtime punkbin already hosts.

Approach

• Extend, don't fork: the emission tool is already package-generic and records tier separately from build_host_platform (the G-138 record shape anticipated cross-emission); the new work is the critcl_zig.config linux section, a build905.zig lane invoking critcl with the linux -target and emitting via the same tools/library_artifacts.tcl, and the WSL smoke.
• Triple direction (decided in the work, recorded here): dynamic glibc with a conservative version floor (e.g. x86_64-linux-gnu.2.17-class) - the .so must dlopen into existing glibc-dynamic linux tclsh builds (tclkit-902 is the concrete consumer); a musl-libc .so inside a glibc process mixes libcs. This mirrors and feeds G-105's recorded dynamic-libc analysis.
• Verification split: structural host-side (ELF class check, determinism) vs functional WSL-side (materialized-tree accel smoke; baked-kit smoke) - the wslprobe staging patterns apply (native-FS staging, never operate on the checkout from inside WSL).
• Consumption is pure G-139 idiom: declare, fetch (the tier gains its first linux-x86_64 target folder), vfslibs supersedes/replace, cross-target bake per G-122 (punkshell902 already bakes target-keyed from windows).

Alternatives considered

• Wait for G-105 and build tcllibc natively on the cross-built linux tclsh - rejected as a dependency: stubs linkage makes the cross .so independently buildable now; G-105 remains the runtime arc and gains this goal's libc decision as prior art.
• Adopt the existing hand-dropped linux tcllibc as a third-party-class artifact (G-123 ingest posture) - rejected: the copies are provenance-less local builds of unknown vintage; the suite path exists and gives the same provenance story as every other lib-tier artifact.
• Ship the win32 tcllibc record shape with a linux dll only (single-file swap) - rejected: the zip carries the whole installed-shape folder; a fresh critcl build against the pinned tcllib checkout is the honest unit.

Notes

• Related: G-105 - the cross-target runtime arc; shares the zig -target axis and the dynamic-libc analysis. This goal deliberately lands first on a narrower lane and records the triple/floor decision as input to G-105's mapping and baseline work (not a dependency in either direction).
• Related: G-116 - the tcltls battery would ride this same cross lane for any future linux emission of its packages.
• Related: G-130 - target-family sibling (32-bit windows) on the same package-generic emission mechanism.
• Related: G-060 - verification environments beyond WSL (qemu matrix) if the smoke ever needs a non-WSL linux.
• Related: G-123 - punkbin server surfaces; the lib/linux-x86_64 folder is a new target row in the documented layout.
• Related: G-004 / G-065 - posture: the retirement extends the no-committed-binaries payoff to the linux kit payload.
• Anchors (archived): G-138 (the emission machinery and record schema - goals/archive/G-138-punkbin-library-artifact-tier.md), G-139 (the consumption idiom and the flip note that flagged this goal - goals/archive/G-139-punkbin-library-consumption.md), G-122 (target-keyed bake), G-102 (critcl -target pin finding).
• punk::platform survey item: linux-x86_64's record axes (tiers/buildsuite) reviewed at landing - a library cross-build does not flip the runtime buildsuite axis ('planned' per G-105); whether the lib tier axis needs a value update is settled in the work.
• Overlap survey 2026-07-30 (drafting): goals_xref paths src/buildsuites/suite_tcl90, src/vfs/punk9linux.vfs, src/runtime/libpackages.toml, src/runtime/vendorlib_vfs.toml, bin/packages, src/runtime/mapvfs.config - strongest live intersections G-105 (cross-target axis - carried above), G-123/G-116/G-130 (carried), G-108/G-110/G-131 (suite-tree co-location only, no contract relationship), G-004/G-065/G-025 (posture, carried or not applicable); no live goal owns the punk9linux tcllibc hand-drops.