# 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<N> 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).