punkshell/goals/G-058-static-runtime-packages.md

G-058 Boot honours statically-linked runtime packages (static baseline seeding + packagepreference static-awareness)

Status: proposed Scope: src/vfs/_config/punk_main.tcl (boot auto_path/tm path filtering), src/modules/punk/packagepreference-999999.0a1.0.tm, src/modules/punk/repl-999999.0a1.0.tm + src/modules/punk/repl/codethread-999999.0a1.0.tm (code interp / codethread bootstrap), src/modules/shellthread-999999.0a1.0.tm (punkshell-created worker threads) as applicable, src/tests/ (un-gated unit tests + constraint-gated shell/kit integration tests), punkbin artifact repo (separate git repo, local checkout c:/repo/jn/punkbin - pinned runtime additions) Acceptance: see GOALS.md index entry (canonical).

Context

Discovered 2026-07-10 wrapping punk9win.vfs onto the tclsfe-x64.exe runtime (punk91, part of the tk-loading experiment). tclsfe (by twapi author and Tcl core member Ashok P. Nadkarni; TEMP_REFERENCE/tcl-sfe) statically links Thread, twapi, sqlite3 and tdbc::odbc into a Tcl 9.1b0 stub. The punk91 kit's main interp works, but the repl's code interp fails at boot:

repl code interp FAILED to load vfs,vfs::zip
failed to load punk::console - can't find package Thread

Probe evidence (2026-07-10)

• Plain tclsfe-x64 stub: static registrations visible as empty-filename entries in info loaded ({} Thread, {} Twapi, {} Tdbcodbc, {} Tdbc, {} Sqlite3, {} Dde); package require Thread resolves 3.0.5 via a chained ifneeded (package require -exact thread 3.0.5); a fresh thread::create WORKER resolves Thread 3.0.5 fine and tsv round-trips. The stub seeds its own thread interps correctly (its _sfeinit.tcl mechanism initializes primary/secondary/thread interps) - the runtime is not the problem.
• punk91 (same stub + punk9win.vfs): main interp shows the static baseline, but the code interp cannot package require Thread. punkshell's boot replaces auto_path/module paths wholesale (punk_main.tcl filtering) and overloads package (punk::packagepreference), discarding the runtime's seeding; the interps/threads punkshell fabricates get punkshell-controlled paths only, so nothing maps Thread -> load {} Thread even though that load is available.
• punk902z never hits this: its vfs bundles lib_tcl9/thread3.0.4/tcl9thread304.dll so punkshell's own paths satisfy the require.
• Shadowing variant: punk91's main interp showed BOTH {} Twapi (static, newer) and //zipfs:/app/lib_tcl9/twapi5.0.2/...dll Twapi loaded - the bundled OLDER twapi loaded over the newer static one. Suspected pre-existing instance: the punkbin runtime README declares builtin Thread/tcllibc/vfs/vlerq, yet punk902z loads thread3.0.4 from the punk vfs (//zipfs:/app/...) - the bundled-over- provided pattern likely occurs quietly on the recommended runtime too.

Precedent (same bug class)

src/tests/runtests.tcl testinterp previously replaced auto_path wholesale and lost kit-internal package trees; fixed by re-adding the running kit's internal lib/lib_tcl dirs (see src/tests/AGENTS.md). Static packages are the flavour with NO directory to re-add - ifneeded seeding is required instead.

Approach

1. Capture-before-replace: at boot, before punk_main.tcl filters package search paths, record the static baseline - [info loaded] entries with empty filename plus their provided versions (package present in the pristine interp). Keep it introspectable at the repl (diagnostics for future static runtimes).
2. Seed fabricated interps/threads: codethread bootstrap, shellthread workers and any punkshell-created child interps get package ifneeded $pkg $ver [list load {} $pkg] for each baseline entry. Generic by construction - driven by the captured baseline, no runtime-specific package naming (zig-built static runtimes, G-005, inherit it).
3. packagepreference static-awareness: static-vs-bundled resolved by a documented version-aware policy (e.g latest-version-wins, static preferred on ties - exact rule recorded here when settled) instead of loading whatever the vfs paths find over an already-provided static package.
4. Re-diagnose the punk91 code-interp vfs/vfs::zip load failure after the Thread fix (may be cascade, may be an independent 9.1b0/dll issue) - resolve or record as a distinct issue/candidate goal.

Testing and artifacts

• Un-gated unit tests: the seeding generator and preference policy tested against SIMULATED baselines ({{} Thread} {{} Twapi} + versions; static/bundled version pairs) under plain tclsh in the normal suite - the logic has coverage on every machine.
• Constraint-gated integration tests: boot the real static kit and probe the code interp + a worker thread. The tcltest constraint is CAPABILITY-probed (a built kit whose baseline shows static entries including Thread), not filename-hardcoded - skips cleanly when absent, extends automatically to zig-era static runtimes.
• Artifact pinning: bin/runtime/ binaries are not git-tracked and tclsfe-x64.exe is a moving upstream beta (github.com/apnadkarni/tcl-sfe releases). Add the verification runtimes (tclsfe-x64.exe at minimum) to the punkbin artifact repo (local checkout c:/repo/jn/punkbin, per-platform dirs, sha1sums.txt checksums) under win32-x86_64 so the integration constraint is satisfiable on other machines via the existing runtime-retrieval path (bin/runtime.cmd; G-006 direction). The .vfs side needs no preservation work - src/vfs/*.vfs is git-tracked.

Notes

• tclsfe's _sfeinit.tcl hook is a runtime-specific customization channel; it is deliberately NOT the fix - it cannot help interps punkshell fabricates with its own paths, and the punkshell-side mechanism must stay runtime-agnostic.
• Related: G-005 (zig static runtimes make this foundational), G-006 (artifact retrieval), the tk-loading experiment that surfaced it (punk91 = tclsfe-x64 + punk9win.vfs per src/runtime/mapvfs.config).