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 ('runtime.cmd' list/use - punk-runtime rename pending G-097) 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 (zig-driver hybrid): the family members become named build-graph products. 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: runtime.cmd -> punk-runtime rename interplay.

RUNTIME NAMING (user 2026-07-21): piperepl-patched runtime executables must carry 'punk' in the name so patched and unpatched are never confusable - e.g tclsh905punk.exe. The suite's current tclsh90spr/tclsh90sprzip are INTERNAL WORKING NAMES pending this goal's scheme. Open design questions the user flagged, to resolve here: how to encode BOTH the tcl patchlevel and a punk version (which punk version - the patch revision? the punkshell release the kit family ships with?), and which separators are appropriate. Existing-namespace considerations for that decision: kit exes use bare punk+patchlevel (punk905.exe), runtimes historically tclsh+nodotversion+flags (tclsh90s) or tclsh+patchlevel (tclsh905.exe), and bin UTILITIES use the punk- hyphen prefix (bin/AGENTS.md policy) - three deliberate sub-namespaces; windows-filename-safe separators only; and the G-103 metadata records can carry the AUTHORITATIVE versions, letting filenames stay human-distinguishing rather than fully version-encoded.

Notes

• 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.