From b9179c6a7783aae59f8432ed6984309798d8ca8b Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 8 Jul 2026 03:57:19 +1000 Subject: [PATCH] G-037 detail file: current make.tcl coverage, design points, interim state Records what libs/vfscommonupdate/project actually cover today (verified: vendorlib -> projectroot lib trees only; _vfscommon.vfs modules+lib only; kit vfs lib_tcl hand-maintained), the design points to settle (per-kit declarative participation - candidate home G-024 mapvfs toml; supersession semantics per G-035; vendorlib/vfs folder-name mismatch; lib_tcl8 coverage), rejected alternatives, and the interim hand-copied tcludp state. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 1 + goals/G-037-vendorlib-vfs-propagation.md | 66 ++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 goals/G-037-vendorlib-vfs-propagation.md diff --git a/GOALS.md b/GOALS.md index c99a5844..37e871eb 100644 --- a/GOALS.md +++ b/GOALS.md @@ -266,5 +266,6 @@ Acceptance: a repro reduced to the smallest ingredient set demonstrates the wedg ### G-037 [proposed] Propagate platform vendor libraries into kit vfs lib_tcl trees via make.tcl 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 +Detail: goals/G-037-vendorlib-vfs-propagation.md Goal: platform-specific vendored binary packages under src/vendorlib_tcl/ reach the kit vfs lib_tcl trees through a make.tcl step instead of hand-copying - updating a vendored package becomes a vendorlib drop plus standard build invocations (motivating case 2026-07-08: tcludp 1.0.12 -> 1.0.13 for the G-036 wedge fix - `libs`, `vfscommonupdate` and `project` all completed while every kit vfs still bundled udp 1.0.12, requiring a manual copy into each vfs lib_tcl9 folder). 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. diff --git a/goals/G-037-vendorlib-vfs-propagation.md b/goals/G-037-vendorlib-vfs-propagation.md new file mode 100644 index 00000000..a23bf1ae --- /dev/null +++ b/goals/G-037-vendorlib-vfs-propagation.md @@ -0,0 +1,66 @@ +# 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` -> + `/lib`, and `src/vendorlib_tcl/{allplatforms,}` -> + `/lib_tcl/{allplatforms,}` (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 `/modules` and `/lib`. `_vfscommon.vfs` + carries no `lib_tcl` platform tree at all. +- Kit vfs `lib_tcl` 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` alongside `foo` 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-`` + (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.