punkshell/goals/G-037-vendorlib-vfs-propagation.md

G-037 Propagate platform vendor libraries into kit vfs lib_tcl trees via make.tcl

Status: proposed Scope: src/make.tcl (new or extended step), src/vendorlib_tcl8 + src/vendorlib_tcl9 (sources), src/vfs/.vfs/lib_tcl8 + lib_tcl9 (targets), punkcheck tracking Acceptance: with a newer package version placed under src/vendorlib_tcl9/, one documented make.tcl invocation updates the participating src/vfs/*/lib_tcl9 trees - installing the new package and removing or explicitly retiring the superseded version (no silent mixed-version provision, per the G-035 concerns) - with punkcheck-tracked provenance; which vfs folders participate is explicitly declared per kit rather than blanket-copied (kit vfs package sets may intentionally differ), with the declaration mechanism recorded (candidate home: the G-024 mapvfs toml); a subsequent make.tcl project yields kits loading the new version (provable via the tcludp case: built punk902z reports package require udp == 1.0.13 with no udp1.0.12 folder remaining in its vfs); the lib_tcl8 tree gets the same treatment or an explicit exclusion rationale in the goal record.

Context

Motivating case (2026-07-08, the G-036 wedge remedy): tcludp 1.0.13 was placed in src/vendorlib_tcl9/win32-x86_64 and make.tcl libs, make.tcl vfscommonupdate, and make.tcl project were all run - yet the rebuilt punk902z still loaded udp 1.0.12, because every kit vfs still carried lib_tcl9/udp1.0.12. The upgrade had to be hand-copied into each kit vfs folder (done for punk9win.vfs and punk9win_for_tkruntime.vfs in commit a1b232dc).

What the existing targets actually cover (verified in make.tcl at the time of writing):

• libs/project (VENDORLIB steps, make.tcl ~lines 2420-2475): copy src/vendorlib -> <projectroot>/lib, and src/vendorlib_tcl<N>/{allplatforms,<platform>} -> <projectroot>/lib_tcl<N>/{allplatforms,<platform>} (punkcheck-tracked). These feed tclsh-based use of the project tree - never the kit vfs folders.
• vfscommonupdate (~lines 1934-1963): wholesale-replaces src/vfs/_vfscommon.vfs/modules and .../lib from <projectroot>/modules and <projectroot>/lib. _vfscommon.vfs carries no lib_tcl<N> platform tree at all.
• Kit vfs lib_tcl<N> folders (punk9win.vfs, punk9win_for_tkruntime.vfs, punk8win.vfs, etc.) are hand-maintained; project merges _vfscommon.vfs over each kit vfs but nothing sources the platform-lib payloads from vendorlib.

Approach (design points to settle)

• Per-kit participation must be declarative, not blanket. Kit vfs package sets intentionally differ (e.g. punk9win vs punk9win_for_tkruntime vs slim kits), and a vendorlib drop must not force a package into every kit. Candidate home for the declaration: the mapvfs config, especially once G-024 moves it to toml (a per-kit package/include list or a vendorlib participation flag).
• Supersession semantics: installing foo<newver> alongside foo<oldver> creates mixed-version provision (G-035 territory) - the step should remove or explicitly retire the superseded folder, or refuse with a clear message. Folder-name conventions currently differ (udp1.0.12 in vfs vs tcludp1.0.13 in vendorlib) - the sync should make the target name match the source, and tolerate legacy names when detecting supersession (pkgIndex-declared package name/version, not folder name, is the truth).
• Platform axis: vendorlib platform folders are per-<platform_generic> (win32-x86_64 today); kit vfs folders are platform-specific by kit. The step should map vendorlib platform -> the kits built for that platform (mapvfs already knows runtime -> vfs -> output mappings).
• punkcheck provenance as with the other install steps (skip unchanged, record source).
• lib_tcl8: same mechanism should serve the tcl8 kits (punk8win.vfs still bundles udp 1.0.12 as of 0.4.3 - see G-036 loose ends), or the exclusion is recorded here.

Alternatives considered

• Extending vfscommonupdate to also sync platform libs into _vfscommon.vfs - rejected as-is: _vfscommon.vfs is deliberately platform-neutral common payload; platform libs are per-kit and per-platform, so the declaration belongs at the kit/mapvfs level.
• Documented manual copy as the permanent process - rejected: silent staleness (the motivating case shipped kits with a known-buggy tcludp through three make invocations with no warning).

Notes

• Related goals: G-024 (mapvfs toml - natural home for per-kit declarations), G-026 (vendor provenance policy), G-035 (mixed-version provision characterisation), G-004/G-005 (the no-committed-binaries endgame would reshape where these payloads come from), G-036 (the motivating tcludp upgrade).
• Interim state: tcl9 kits carry tcludp1.0.13 (hand-copied, commit a1b232dc); punk8win.vfs still carries udp1.0.12.