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: proposed 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; 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....)

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.