punkshell/goals/G-103-runtime-kit-family.md

G-103 runtime kit family from buildsuites: plain / punk / bi kits with attached batteries + artifact metadata

Status: active Scope: src/buildsuites/suite_tcl90/ (kit assembly steps in recipe/driver; pattern for later suites), src/vfs/_config + src/runtime/mapvfs.config (as consumers of the new runtime names), punkbin repo layout + metadata (c:/repo/jn/punkbin; compatible repos), src/scriptapps runtime scriptset (punk-runtime list/use - renamed under G-097, achieved 2026-07-21) Goal: buildsuites produce a defined FAMILY of runnable, self-contained runtime kits - executables whose info library and core batteries live in the initially attached zip, depending on no external filesystem tree: (1) a PLAIN tclsh kit carrying loadable Thread, tclvfs with as many vfs::* packages as we have, and tcllib+tcllibc; (2) a PUNK kit = the plain kit with the TCLSH_PIPEREPL patch applied and ENABLED BY DEFAULT (env opt-out, not opt-in - users wanting stock behaviour take the plain kit); (3) BI (batteries-included) punk kits additionally carrying libraries WE BUILD - Tk first; tcltls (with a zig-built OpenSSL/LibreSSL backend), sqlite3/tdom/twapi as future build targets - all in the attached zip. These are the project's 'runtime' executables: punkbin candidates carrying metadata (variant, component versions, target platform, provenance) that runtime list/use subcommands can surface. Acceptance: suite_tcl90 produces named artifacts for at least plain, punk, and one bi (+Tk) kit; each verified self-contained from a path with no external Tcl visible (info library resolves into the attached zip; package require checks for Thread, vfs + representative vfs::* packages, tcllib module + tcllibc acceleration engaged; bi adds Tk create/destroy) with the checks recorded here; the punk kit demonstrates piperepl active by default and disabled via the documented env opt-out, the plain kit demonstrates stock behaviour (no patch); artifact metadata (variant, versions, target, source provenance) is emitted alongside the binaries in the punkbin layout and surfaced by the runtime scriptset's list/use; the naming scheme for family members is documented, with piperepl-patched runtime executables carrying 'punk' in the name to distinguish them from unpatched (e.g tclsh905punk.exe - the tcl-patchlevel / punk-version / separator questions resolved and the decision recorded here) and mapvfs.config consuming the punk/bi runtimes under the decided names; the 8.6 family variant is explicitly deferred to the G-101 container investigation (static vfs / metakit patching questions).

Context

User requirements 2026-07-20. Formalizes and extends what suite_tcl90 half-delivers: tclsh90szip.exe already attaches the tcl library (self-contained info library ✓) but thread/tclvfs/tcllib ride outside (out/lib or the punk .vfs payload) - the note from G-098 (achieved 2026-07-20), "future: attach at least tclvfs & thread to the runtime's own zip", becomes a requirement here, extended to tcllib+tcllibc for all family members (user lean, agreed: tcllib is widely used and tcllibc's speedup makes bootstrapping and other usecases far more practical; zip compression keeps the cost modest - a leaner variant remains possible later via configuration rather than a separate philosophy).

piperepl gating REVIEW (user 2026-07-20): the patch's original env gating (TCLSH_PIPEREPL=1 opt-in) fit a single-binary world. With a kit FAMILY the punk kits are FOR punk use - default ON, env opt-OUT (e.g TCLSH_PIPEREPL=0) for debugging; the plain kit exists for those who want stock semantics. The G-096 (achieved 2026-07-20) behaviour-matrix item still characterizes the patch itself; its kit-default policy is restated there pointing here.

Family boundary: bi kits carry libraries WE BUILD (zig-only policy) - not vendored third-party binaries. Tk is built today; sqlite3 is a straightforward future build (amalgamation compiles cleanly under zig cc); tdom moderate; twapi historically MSVC-leaning - its buildability under the zig-only policy needs investigation before it can join a bi kit (until then twapi remains a kit-vfs vendored payload as in punk9wintk903.vfs, outside this family's attached-zip guarantee). The no-twapi mitigation for raw-mode console control is the powershell console-mode fallback - maintenance tracked as G-106, whose priority rises if zig-built twapi proves impractical.

Metadata format note: toml is acceptable HERE (runtime list/use run in punkshell contexts where vendored tomlish exists) - the 2026-07-20 toml drop applies to BUILDSUITE BOOTSTRAP configs which must parse dependency-free, a distinct concern. punkbin currently carries sha1sums.txt (+ minisign) - metadata extends, not replaces, that. Compatible repos (punkbin mirrors) carry the same records.

Plain-niche boundary (user 2026-07-20): 'completely plain' tclsh executables are already available from other build systems/distributions - punkshell does not compete for that niche, and G-018 is SUPERSEDED accordingly. This family's 'plain' member is plain-for-punk-purposes: no piperepl patch, but batteries attached. The truly bare tclsh built during bootstrap (the tclsh90szip-class intermediate) stays READILY ACCESSIBLE as an ordinary suite build product (_build//out/bin) but is not showcased or published as a family member.

Relationships: G-018 (superseded 2026-07-20 - see its closing note). G-102 (achieved 2026-07-21 - zig-driver hybrid landed): the family members become named build-graph products of the settled step shape. G-105 (cross-target): family x target is the punkbin artifact matrix - metadata carries the target dimension. G-101: the 8.6 family variant depends on the container strategy. G-006: punkbin download consent. G-097 (achieved 2026-07-21): the runtime.cmd -> punk-runtime rename landed ahead of this goal's list/use work.

RUNTIME NAMING (user 2026-07-21): piperepl-patched runtime executables must carry 'punk' in the name so patched and unpatched are never confusable. The suite's tclsh90spr/tclsh90sprzip stay recipe-INTERNAL working names - this goal's kit-assembly steps emit the public names below at the boundary.

NAMING DECISION (user-approved 2026-07-21; resolves the acceptance's tcl-patchlevel / punk-version / separator questions). Principle: two naming tiers, mapped by tooling - punkbin stores immutable fully-qualified ARTIFACT names; projects and fingers consume short stable WORKING names; 'runtime use' (punk-runtime after G-097) and mapvfs are the mapping.

• RUNTIME ARTIFACT names (punkbin tier; rarely typed, verbosity fine): tclsh[-punk[-bi]]-r(.exe) - e.g tclsh9.0.5-r1.exe (plain member), tclsh9.0.5-punk-r1.exe, tclsh9.0.5-punk-bi-r1.exe. Dotted patchlevels are REQUIRED (tclsh1005 is unreadable/ambiguous once Tcl 10 and 9.0.10-class patchlevels exist). -r is an ASSEMBLY REVISION per (patchlevel, variant), ALWAYS present for uniform parsing, incremented on any republish of the same patchlevel (battery bump, patch fix, toolchain bump) - artifacts are immutable and coexist for rollback. NO punkshell version and NO patch revision in runtime names: runtimes carry no punkshell modules, and the metadata record is authoritative for patch revision, component versions, source pins and toolchain.
• RUNTIME WORKING names (what mapvfs references; bin/runtime//): the artifact name minus -r - e.g tclsh9.0.5-punk.exe; 'runtime use' materializes a chosen -rN artifact into it, so republishing never churns consumers.
• KIT names flip the release axis to the PUNKSHELL version (the kit's payload): typable WORKING names are major-only - punk9, punk8, variant punk9bi - precision stamped in-file/metadata; published/archived KIT ARTIFACTS are punk-(.exe) - e.g punk9-0.5.0.exe, prerelease punk9-0.5.0b2.exe. Two punk9 releases may differ in tcl patchlevel - that is metadata's job. The dev-matrix style (punk905, punk902z - tcl patchlevel encoded, owner-chosen via mapvfs, typed constantly while comparing runtimes) remains a recognized third style; kit conventions here are documented DEFAULTS, not mandates - kit exe naming stays under project-owner control.
• Separators: hyphens throughout (safe here - these names neither start with punk- nor live on PATH, so the bin-utility prefix convention is not in play); '+' banned (hostile in raw punkbin URLs); '_' reserved as fallback. Filenames IDENTIFY; ORDERING comes from runtime list parsing metadata (lexicographic sort misorders tclsh10.* before tclsh9.* regardless of dots) - per-series punkbin subdirs remain a later option.

(The acceptance's 'e.g tclsh905punk.exe' example predates this decision; the decided punk-marked shape is tclsh-punk....)

VFS-SYSTEM RELATIONSHIP (user observation 2026-07-21, assessment recorded): the bi family is structurally what the existing .vfs kit system would generate with the main.tcl fauxlink (-> _config/punk_main.tcl) left out - and make.tcl half-proves the isomorphism: its zip-kit path extracts the runtime's attached image, merge_overs it with the .vfs content and re-images the union onto the raw exe via tcl::zipfs::mkimg (mkimg REPLACES the whole attached image - one archive out), so runtime-zip and vfs-folder payloads are already treated as the same species, and punk9wintk905.vfs's bin/ + lib_tcl9/ batteries are essentially this family's payload list. Where the equivalence breaks is this goal's real design content:

• tcl_library provenance: the kit flow inherits the core lib by EXTRACTION from the runtime underneath; a family runtime must guarantee it directly (the suite's make-zipfs step already does).
• path setup: kit batteries are visible only because punk_main.tcl (punk::boot) wires lib_tcl9/bin into auto_path/loading; with no main.tcl the stock zipfs app hook falls through to plain interactive tclsh and nothing wires them - family payload must sit where the STOCK boot searches, i.e. the installed lib-tree layout, which the suite's out/lib already is (post-tclsh steps install thread/tclvfs/tcllib/tcllibc/tklib there; build_tk delivers Tk lib + dll).
• open at activation: staging-tree convention, payload layout inside the zip (stock lib tree vs lib_tcl9-style + boot hook), and dll-load-from-zipfs for Thread/Tk (core's copy-to-temp fallback; AV/cleanup caveats) - these, not the zip mechanics, are the design work.

SEPARATION vs SHARING: the generators stay separate - bootstrap position (family runtimes must be produced hermetically with no punkshell available; make.tcl needs a working shell, and the family runtime IS the bootstrap product) and release axis (tcl-patchlevel + -rN vs punkshell version) both force it; Scope accordingly casts src/vfs/_config + mapvfs.config as name CONSUMERS. Sharing happens at the primitive (both generators bottom out in zipfs mkimg over a staged tree) and at the CONTRACT: a family runtime's attached image is exactly what make.tcl extracts and merges under every future kit. Consequence: once family runtimes exist, punk9wintk905-class vfs folders shrink toward pure punkshell payload (modules + main.tcl + twapi-class vendored bits) - and this attached-image contract is the concrete payload contract the sequencing note promises G-101.

Notes

• 2026-07-21 (user): SEQUENCING CONFIRMED - G-097 (bin naming sweep, achieved 2026-07-21) first, then this goal, then the 8.6 arc (G-099/G-100/G-101). The 8.6 suite forks suite_tcl90's scaffolding AFTER the kit-family assembly steps land here (same fork-timing logic as G-102-before-G-099, which proved out), and G-101's container investigation gets this family's payload contract as its concrete target. punkbin publication unblocks with this goal's artifacts.
• 2026-07-21 (user): punkbin pushes of the suite runtimes are DEFERRED until family members carry Thread etc in the attached zip and the pr (punk-named) variants exist - i.e. punkbin publication follows this goal's artifacts, not the current interim tclsh905/punk905 shapes.
• G-107 (achieved - see goals/archive/G-107-buildsuite-library-tests.md) fixed the suite's thread version stamping: the dll/install-dir/pkgIndex now derive from the checkout (tcl9thread.dll, thread, both Thread+thread provided) instead of a hardcoded 3.0.1. The existing punk905 kit payload (src/vfs/punk9wintk905.vfs/lib_tcl9/thread3.0.1/) still carries the OLD 3.0.1-named copy - refresh it to the derived naming when this goal rebuilds kit payloads from suite artifacts.
• G-107 (achieved) also defines the per-component test-evidence summaries this goal's artifact metadata consumes: out/testreports/.summary line-records (result/totals/failednames/baseline/... ), shape documented in goals/archive/G-107-buildsuite-library-tests.md ("Evidence summary shape").
• 2026-07-21 (user): bi kits should include tcltls (https://core.tcl-lang.org/tcltls - fossil, same fetch pattern as thread/tclvfs/tk) as a suite-BUILT battery. Current state: TLS is shipped today ONLY as VENDORED PREBUILT binaries in kit .vfs payloads (tcltls1.7.22/ 1.7.23 + tls2.0b2 dlls; punk9linux tcltls.so) - committed binaries G-004 wants gone - and it is a real consumer dependency already (punk::imap4, punk::netbox both 'package require tls'). Building it as a family battery replaces those prebuilts AND advances G-004. FEASIBILITY (the crux - parallel to the twapi buildability question in Context): tcltls itself is a thin C extension (tls.c/tlsIO.c compile under zig cc like thread/tclvfs/tk), but it LINKS a crypto backend - upstream is OpenSSL, with LibreSSL also supported. No OpenSSL/LibreSSL is in the tree today, so the real work is building the crypto lib under the zig-only policy: pragmatic paths are LibreSSL-portable (autoconf/cmake, no perl Configure) or a no-asm OpenSSL, compiled with zig cc, then tcltls linked static against it (mirrors the tcllibc/tk build shape). This is the LARGEST new build dependency the family would take on - large enough it may warrant its own sub-goal once scoped. TEST (G-107): a suite-built tcltls gets a record-mode step (tcltls carries its own tests/ suite) - the highest-value case here being zig-built OpenSSL/LibreSSL + tcltls against a static tclsh, a combination nobody upstream tests. DECISION (user 2026-07-21): tcltls added to the Goal:'s bi-battery enumeration (approved). Kept as a G-103 battery line - NOT a separate goal and NOT gating any progress; a dedicated goal remains an option if the crypto build proves large, but not now. The crypto-backend build lands when convenient. In the interim tcltls STAYS a vendored binary (the existing tcltls1.7.23 / tls2.0b2 kit payloads remain - consistent with G-004's tolerance of existing vendored binaries pending their build story). Rationale: the aim across this arc is to validate the general build/test/kit PROCESSES as far as practical, not to rush a publicly releasable product - so a battery whose backend build is heavy must not block the family scaffolding.
• 2026-07-21: the copy-to-temp dll loading these kits rely on (Thread/Tk et al loaded out of the attached zip - the "open at activation" bullet in Context) has a known cleanup wart: extracted temp DLLs/dirs are not removed on exit and accumulate per run. Tcl core TIP 741 (Ashok P. Nadkarni, DRAFT - "Cleanup of temporary Windows DLL's loaded from zipfs archives") proposes a TclpFinalizeLoad finalizer that on windows spawns cmd.exe/timeout.exe to delete the dir after a delay (no-op elsewhere); it PRESERVES the extract-to-temp model (vs TIP 709's alternative of loading without temp extraction) and 9.0 tracks the dir in a dllDirectoryName global. TIP 741 frames it windows-specific, but REQUIREMENT (user 2026-07-21): test on ALL our target platforms (windows native; linux/WSL per G-105; the G-060 guests) that temp-dll/dir accumulation either does not happen or is characterized as a known flaw - the family runtimes are the direct consumers (they load batteries this way). Applies equally to G-101's Metakit 8.6 kits (same copy-to-temp). Ref: https://core.tcl-lang.org/tips/doc/trunk/tip/741.md
• 2026-07-21 WINDOWS CHARACTERIZED (suite tclsh90szip.exe 9.0.5): the flaw is REAL and reproduced on the suite's own runtime. Loading a dll out of a zipfs mount ('load //zipfs:/mnt/libbin/tcl9thread307.dll Thread') extracts it to a fresh %TEMP%\TCL<8-hex><dll> directory; a NEW directory is created on every such load (observed TCL00011038, TCL0001743c, TCL6185c1b4 across three runs) and NONE is removed on process exit. Notes: (a) 'info loaded' reports the //zipfs:/ path, NOT the temp path - the temp copy is invisible to script-level introspection, only the filesystem reveals it; (b) unbounded accumulation confirmed in the wild - this machine's %TEMP% held 15,609 such TCL* dirs spanning 2026-03-02..2026-07-21 (~5 months), each holding extracted battery dlls from past kit runs (tcl9thread/twapi/tk/tls/sqlite/vfs/tcllibc, incl 8.6-era thread2812/twapi511). So Windows = the known TIP-741 flaw, no in-runtime cleanup in 9.0.5. STILL TO CHARACTERIZE: linux/WSL (G-105) and the G-060 guests - on unix the extracted temp file can be unlink()'d while still mapped, so the expectation there is NO accumulation; verify rather than assume. (Method: mount a zip containing a built dll, load from it, diff %TEMP%/tmpdir before+after and after exit; scratch scripts under the session scratchpad.)
• 2026-07-21: the modpod path was ALSO characterized on windows 9.0.5 - a binary inside a zip-based .tm (self-mounting modpod, including one nested in a kit's zipfs) extracts to %TEMP%\TCL* with the SAME non-cleanup flaw (details in G-066 Notes). So windows = flaw confirmed for BOTH direct-kit and modpod-.tm binary loads. Linux/WSL leg is blocked on a linux tcl9 runtime - see G-105 Notes.