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, hardened and verified on this family's runtimes under G-106 (achieved 2026-07-22 - see goals/archive/G-106-powershell-consolemode-fallback.md); if zig-built twapi proves impractical, that fallback is the primary raw path on family runtimes.

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.
• 2026-07-21: G-023 (version-named punk binaries) reconciled to this goal's NAMING DECISION (user-approved): it adopts the kit-artifact tier punk-.exe verbatim and layers its -dev / release-gated-plain-name policy on the working-name tier.
• G-106 (archived) recorded the no-twapi raw-mode contingency this goal's twapi investigation weighs against: the powershell console-mode fallback is verified working on the family runtimes (tclsh90spr + the zipfs kit shape, make.tcl shell and bare repl launches) - lazy singleton pwsh server, quiet, parent-pid self-reaping, script embedded in punk::console so kits need no scriptlib on disk; env PUNK_PS_CONSOLEMODE_DEBUG=1 for diagnostics. If zig-built twapi proves impractical, bi kits can ship without twapi and rely on this path for raw mode - see goals/archive/G-106-powershell-consolemode-fallback.md (recipe in its Notes).

Progress

2026-07-22 increment: kit-family + kit-family-artifacts steps landed, all three members verified

ATTACHED-IMAGE LAYOUT DECISION (resolves the Context "open at activation" items - staging-tree convention and payload layout): the image mirrors the installed prefix, with two boot-anchored placements and one punkshell-authored hook file:

• tcl_library/ at the app root (the C-level zipfs boot looks only for /app/main.tcl and /app/tcl_library; NO main.tcl is included - stock boot falls through to the ordinary interactive shell, per the Context requirement that payload sit where the STOCK boot searches).
• tm modules at tcl9/<ver>/ beside it (tm.tcl Defaults anchors at [file dirname [info library]] = /app).
• batteries under lib/<pkg>/ with their INSTALLED-SHAPE pkgIndexes unchanged ($dir/../../bin dll references resolve to /app/bin), dlls under bin/ - the same shape the suite's out/ prefix and the existing punk .vfs payloads use, so pkgIndex generation stays single-source (build_tclthread/build_tk return their generated pkgIndex + version facts; tclvfs's configured package generation is shared between prefix install and family staging).
• lib/pkgIndex.tcl: a one-line stock hook (lappend ::auto_path $dir) joining lib/ to the package search - auto_path starts as [tcl_library, /app], the /app scan sources /app/*/pkgIndex.tcl, and tclPkgUnknown re-scans auto_path growth mid-scan (the same stock mechanism tcllib's own top-level index uses). No C changes, no boot script.
• Tk script library resolution: tcl_findLibrary iterates auto_path entries joined with tk9.0, so /app/lib/tk9.0 is found once the hook has run (package require Tk goes through the pkgIndex scan first by construction).

Landed (suite_tcl90, all in the default build pipeline):

• kit-family step: two WriteFiles staging trees (core, bi) + three zipfs_mkimg wraps emit the working-name products into out/family/: tclsh9.0.5.exe (prefix exe tclsh90s), tclsh9.0.5-punk.exe (tclsh90spr), tclsh9.0.5-punk-bi.exe (tclsh90spr + Tk/tklib payload).
• tools/family_check.tcl: per-member self-containment verification - the kit is copied ALONE into a scratch dir and probed from there (defeats the <exedir>/../lib tm root and exe-relative tcl_findLibrary entries) with TCL_LIBRARY/TK_LIBRARY/TCLLIBPATH/VFS_LIBRARY/TCL*_TM_PATH scrubbed and TCLSH_PIPEREPL controlled per probe. The piperepl discriminator is [info exists ::tclsh(istty)] in a script-arg run (G-096 matrix: machinery published iff patched AND gate open; script-arg runs never set dorepl, so no console-reopen/hang risk).
• kit-family-artifacts step + tools/family_artifacts.tcl: punkbin-layout emission into out/family/punkbin/win32-x86_64/ - immutable -r artifact copies (-Dfamilyrev=N, default 1), per-artifact toml metadata (variant, working name, revision, target, sha1, size, built, tcl patchlevel, piperepl policy incl the TCLSH_PIPEREPL=0 opt-out, attached battery versions, suite/toolchain/optimize, per-source checkout uuids where materialized - manifest.uuid is a per-repo fossil setting: tcl/tk/thread carry it, tclvfs/tcllib/tklib record "unrecorded" - and G-107 test-evidence result lines from out/testreports/*.summary), plus punkbin-format sha1sums.txt. Deliberately runs UNDER the plain family kit itself (sha1 via its attached tcllib) - each emission re-proves the runtime executes real tooling self-contained. Depends on the checks: only verified kits get records.
• Consumers: working names copied to bin/runtime/win32-x86_64/ (machine-local, gitignored) and mapvfs.config entries added - tclsh9.0.5-punk.exe + punk9wintk905.vfs -> punk9_beta, tclsh9.0.5-punk-bi.exe + punk9win_for_tkruntime.vfs -> punk9bi_beta (*_beta trial convention; kit working names per the naming decision).

VERIFICATION 2026-07-22 (acceptance self-containment checks; suite build on the 9.0.5 checkout 1a9c3b9d96, zig 0.16.0, ReleaseFast; family_check probes run from a scratch dir with scrubbed env - full pipeline suite.tcl build PASS end-to-end including both new steps):

• ALL THREE members: info patchlevel 9.0.5; info library = //zipfs:/app/tcl_library (attached image); tzdata + encodings reachable; package require platform served from the attached tm tree; Thread 3.0.7 loads from the attached zip AND executes (thread::create + cross-thread eval = 42); vfs 1.4.2 + vfs::zip 1.0.4 + vfs::urltype 1.0, with a functional vfs::zip mount round-trip (zipfs mkzip a scratch payload, mount via tclvfs, read back, unmount); tcllib md5 2.0.9 with the tcllibc critcl accelerator ENGAGED (md5::accel(critcl)=1).
• plain tclsh9.0.5.exe: stock behaviour proven - no ::tclsh machinery with env unset AND with TCLSH_PIPEREPL=1 (unpatched binary ignores the enable).
• punk tclsh9.0.5-punk.exe / punk-bi tclsh9.0.5-punk-bi.exe: piperepl ACTIVE BY DEFAULT (::tclsh machinery published with env unset), disabled via the documented TCLSH_PIPEREPL=0 opt-out.
• punk-bi additionally: Tk 9.0.2 loads from the attached zip - button create/destroy + root destroy clean; tklib tooltip 2.0.4.
• Artifacts emitted (current emission 2026-07-22, after a FULL core test-gate refresh replaced a stale partial tclcore.summary - gate PASS: 69552 run, 56039 passed, 13504 skipped, 9 failed all baselined; metadata [tests] now carries the full evidence set): tclsh9.0.5-r1.exe (sha1 969ac1e1..., 6455 KB), tclsh9.0.5-punk-r1.exe (63bc8f57..., 6458 KB), tclsh9.0.5-punk-bi-r1.exe (a6a23f24..., 9165 KB) + per-artifact tomls + sha1sums.txt, generated by the plain family kit itself. Working copies in bin/runtime/win32-x86_64 re-materialized from this emission via 'punk-runtime use' (re-wrapped artifacts get new zip bytes/sha1s - immutable -rN discipline starts at PUBLICATION; pre-publication regeneration of r1 is the dev loop).

2026-07-22 increment: punk-runtime list/use artifact-metadata surfacing (acceptance item landed)

Scriptset extension (both payloads, ps1 + bash, wrapped to bin/punk-runtime.cmd per the bin/AGENTS.md polyglot workflow; layout-shipped copy + .ps1 twin refreshed; roundtrip pin test runtimecmd_roundtrip PASS):

• list surfaces a per-runtime metadata summary parsed from the <rootname>.toml record beside each runtime: variant, tcl patchlevel, revision, piperepl on/off, and - on a materialized working copy - from=<artifact> (which immutable -r artifact it came from).
• use <artifact-r<N>-name> MATERIALIZES the immutable artifact into its WORKING name (name minus -r) with the metadata toml copied alongside, then selects the working name - the naming decision's "runtime use materializes a chosen -rN artifact" mapping, so republishing never churns consumers. use <workingname> selects as before.
• fetch of an -r-named artifact also retrieves its metadata toml from the punkbin layout (absence tolerated - pre-family runtimes have no records).
• Root-name handling strips only .exe (dotted patchlevels break last-dot stripping for extensionless unix names) - the same fix applied to family_artifacts.tcl's artifact/toml naming (exe_split) for the G-105 cross-target future. Candidate listing now excludes directories and .log files in both payloads (parity cleanup).

VERIFIED 2026-07-22 on the real wrapped bin/punk-runtime.cmd (windows powershell 5 branch) and the bash payload directly (git-bash): use tclsh9.0.5-punk-r1.exe materialized tclsh9.0.5-punk.exe + toml and selected it; all three members materialized the same way; list shows the summaries in both payloads identically; punk-runtime run <probe.tcl> launched the active punk family runtime and reported 9.0.5 / piperepl machinery present / tcl_library=//zipfs:/app/tcl_library. Project 0.17.7 (patch bump + changelog: punk-runtime is shipped product surface).

2026-07-22 increment: punk-runtime cross-platform surface + help (user-directed; G-105 groundwork)

User-approved argument surface for future cross-builds (design discussion 2026-07-22): fetch/list/use accept -platform <p> (punkbin platform-DIR names, never zig triples; resolution -platform arg > PUNK_RUNTIME_PLATFORM env > local default; shape-only lowercase validation - the server is the truth). Foreign fetch requires an explicit runtime name (no foreign defaults); use -platform manages that folder's active.toml/materialization (the marker travels with the folder at deploy time - the provisioning story; exec bits restored on the receiving side); list gains a !TARGET-MISMATCH integrity flag when a runtime's metadata target disagrees with its folder; run is local-only (rejects a leading -platform, ignores the env override, later args pass to the runtime untouched). Plus a help action (full operator reference) and a real usage block on no-args. Bash FreeBSD platform dir aligned to punkbin's actual freebsd-x86_64 (was freebsd-amd64 - a G-105 naming-alignment item found during the design pass). Parity bug caught in verification: powershell -notmatch is case-insensitive - validation uses -cnotmatch (URL paths are case-sensitive). Verified on both payloads directly AND through the rewrapped polyglot (noargs/help/list/foreign-use-materialize/mismatch-flag/foreign-fetch-refusal/ run-guard/env-override incl run's immunity to it); roundtrip pin PASS; layout copy + .ps1 twin refreshed; project 0.17.9.

Remaining for acceptance:

• exercise the new mapvfs entries with an actual kit wrap (punk9_beta / punk9bi_beta) - entries landed 2026-07-22, the wrap trial is the next increment (kit builds touch user-facing bin/ kits; beta-trial convention applies).
• record the 8.6-family deferral note against G-101 when closing (the acceptance's explicit deferral - no work item here).
• 2026-07-22: punkbin layout contract gained a root-level platforms.txt discovery manifest (generated by punkbin src/build_sha1sums.tcl; committed locally in punkbin 7b8a244, push = user decision) - raw-file artifact servers have no directory listing, so the manifest is how punk-runtime's new 'platforms -remote' action (and third-party mirrors per the Context "compatible repos" note) enumerate served platforms. Verified end-to-end against a file:// mirror simulation of the local punkbin checkout.