# 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 and mapvfs.config consumes the punk/bi runtimes; 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/<suite>/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.

## Notes

(none yet)