diff --git a/GOALS.md b/GOALS.md index 0b21b882..2e14c5c7 100644 --- a/GOALS.md +++ b/GOALS.md @@ -381,3 +381,7 @@ Detail: goals/G-112-maketcl-subcommand-rename.md ### G-113 [proposed] make.tcl colour output is terminal-aware: SGR only on interactive tty, off when piped Scope: src/make.tcl (startup colour policy, define_global_ansi), src/AGENTS.md (invocation guidance), src/tests/shell/testsuites/punkexe/ (piped-output characterization if a suite proves feasible); layout make.tcl copies via established sync channels Detail: goals/G-113-maketcl-tty-aware-colour.md + +### G-114 [proposed] Per-platform tm module roots: platform-segregated binary .tm via tcl::tm::path +Scope: src/vfs/_config/punk_main.tcl + src/vfs/_config/project_main.tcl + src/make.tcl (boot tm-path wiring), src/modules/punk/platform-999999.0a1.0.tm (canon names, as consumer), new per-platform tm root trees (layout/naming decision - sibling roots beside src/vendormodules_tclX / src/modules_tclX), src/project_layouts (layout seeding), modpod demonstration artifact, tree READMEs; coordinates with G-109 (manifest target-platform field stays that goal's item) +Detail: goals/G-114-per-platform-tm-roots.md diff --git a/goals/G-114-per-platform-tm-roots.md b/goals/G-114-per-platform-tm-roots.md new file mode 100644 index 00000000..d67d35cf --- /dev/null +++ b/goals/G-114-per-platform-tm-roots.md @@ -0,0 +1,44 @@ +# G-114 Per-platform tm module roots: platform-segregated binary .tm via tcl::tm::path + +Status: proposed +Scope: src/vfs/_config/punk_main.tcl + src/vfs/_config/project_main.tcl + src/make.tcl (boot tm-path wiring), src/modules/punk/platform-999999.0a1.0.tm (canon names, as consumer), new per-platform tm root trees (layout/naming decision - sibling roots beside src/vendormodules_tclX / src/modules_tclX), src/project_layouts (layout seeding), modpod demonstration artifact, tree READMEs; coordinates with G-109 (manifest target-platform field stays that goal's item) +Goal: binary-bearing .tm modules (modpods) are distributed ONE PLATFORM PER FILE and installed under per-platform TM ROOTS that the boot registers only for the running platform (canonical punk::platform names) - so no consumer downloads other platforms' binaries, a user can drop in their platform's copy of a same-name-version module without same-version shadowing, and wrong-platform .tm files present on a shared or synced tree are never registered or loaded. +Acceptance: the root layout + naming decision is recorded in this file (including the structural constraint that platform dirs cannot nest inside an existing tm root - tm subdirectories are namespace components - so per-platform roots are sibling trees); the boot (punk_main.tcl, project_main.tcl, make.tcl) registers exactly the running platform's root(s), verified on the tcl9 kit and an 8.6 shell (or the 8.6 limitation recorded); a demonstration binary modpod .tm placed in the win32-x86_64 root loads via package require on windows while a same-name-version copy placed in a foreign platform's root is demonstrably not registered; the same-version drop-in-replacement scenario (the fat-tm objection) is demonstrated working across platform roots; generated-project layouts seed the structure; tree READMEs and punk::platform docs updated. + +## Context + +Drafted 2026-07-22 from the platform-canon survey discussion (user-approved +wording). Motivating evidence is the user's prior fat-tm experience, recorded +in G-109 Notes the same day: a multi-platform thread .tm proved unworkable - +(a) downloads far larger than any one consumer needs, and (b) same-version +shadowing: tm handling resolves one name-version to ONE file with no arch +awareness, so a user cannot drop in a replacement .tm carrying their platform +when a same-version copy is already on the path. Platform segregation for +binary .tm therefore has to ride tcl::tm::path - per-platform tm roots +selected by the boot for the running platform. + +Structural constraint driving the layout decision: platform directories +canNOT nest inside an existing tm root, because a subdirectory of a tm path +is a NAMESPACE component (foo/bar-1.0.tm = package foo::bar - see +src/vendormodules_tcl8/tdbc/sqlite3-1.1.5.tm = tdbc::sqlite3 for the +legitimate use of subdirs). Per-platform roots must therefore be SIBLING +trees registered separately (candidate shapes: vendormodules_tcl-/ +siblings, or a byplatform// parent) - the naming decision is this +goal's first item. + +Division of labour with G-109 (libunknown manifest-declared multi-name +discovery): this goal owns the roots, the boot wiring and the demonstration; +G-109 owns the manifest format, where a declared target-platform field would +additionally let libunknown skip wrong-platform binary .tm even when someone +shares a path (defensive extra recorded in G-109 Notes 2026-07-22). + +Related: G-066 (modpod generation - the demonstration artifact's tooling; +self-mounting binary modpods characterized working there), G-110 (the binary +inside a .tm loads via the extraction path investigated there), G-034 (8.6 +modpod mount path - bears on the 8.6 leg of acceptance), punk::platform +(canonical platform names; 'help platforms'). + +Nothing needs this until binary-bearing .tm distribution starts in earnest - +creating empty tm-root siblings ahead of that machinery would be speculative +structure (2026-07-22 assessment). The goal exists so the layout and boot +work land deliberately when G-109-era binary tms arrive, not ad hoc.