From 852d684ae63504a63a56f53e5ef833c55f946f59 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Fri, 31 Jul 2026 18:31:51 +1000 Subject: [PATCH] G-101/G-127/G-131/G-141 Scope rewording (user-approved): stale mapvfs.config / vendorlib_vfs.toml references updated to the achieved G-024/G-115 surfaces Scope lines are the index's discovery mechanism (path-grep + goals_xref path overlap): after the G-024/G-115 migration the old filenames matched nothing on disk, so agents editing src/runtime/mapvfs.toml or src/vfs/*.vfs.toml would silently miss these goals. Minimal swaps, index + detail-file mirrors in step: - G-101/G-131: mapvfs.config -> mapvfs.toml (annotations unchanged) - G-127: vendorlib_vfs.toml -> src/vfs/*.vfs.toml (the achieved G-115 surface this goal adds the platform axis to); mapvfs.config -> mapvfs.toml - G-141: vendorlib_vfs.toml -> src/vfs/*.vfs.toml (the achieved G-115 successor surface; format coordinated with G-127) Archived G-024/G-115 records deliberately untouched (accurate history). goals_lint clean; xref path discovery verified resolving to the reworded goals. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 8 ++++---- goals/G-101-tcl86-kit-container-strategy.md | 2 +- goals/G-127-crosstarget-vfs-bake.md | 2 +- goals/G-131-boot-payload-autodetection.md | 2 +- goals/G-141-libfetch-target-selection.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/GOALS.md b/GOALS.md index b80ef8bd..d54a0570 100644 --- a/GOALS.md +++ b/GOALS.md @@ -338,7 +338,7 @@ Scope: src/modules/shellfilter-999999.0a1.0.tm (stack placement, insert_transfor Detail: goals/G-090-shellfilter-shellthread-audit.md ### G-101 [proposed] kit container strategy for zig-built Tcl 8.6 runtimes (no zipfs) -Scope: investigation + decision record under src/buildsuites/suite_tcl86/ (or successor mechanism); src/buildsuites/suite_tcl86/patches/ (tracked sdx wrap.tcl provenance capture); TEMP_REFERENCE/{metakit_jnorthrup,KitCreator,kbs,sdx,tcl9} (read-only guidance - inventory in the detail file); src/runtime/mapvfs.config ('kit' type consumers); src/make.tcl kit-wrap path (as consumer); bin/sdx.kit (the tracked wrapping tool - provenance is part of this goal) +Scope: investigation + decision record under src/buildsuites/suite_tcl86/ (or successor mechanism); src/buildsuites/suite_tcl86/patches/ (tracked sdx wrap.tcl provenance capture); TEMP_REFERENCE/{metakit_jnorthrup,KitCreator,kbs,sdx,tcl9} (read-only guidance - inventory in the detail file); src/runtime/mapvfs.toml ('kit' type consumers); src/make.tcl kit-wrap path (as consumer); bin/sdx.kit (the tracked wrapping tool - provenance is part of this goal) Detail: goals/G-101-tcl86-kit-container-strategy.md ### G-105 [proposed] buildsuite cross-target builds (zig -target): linux first, WSL-verified @@ -371,7 +371,7 @@ Detail: goals/G-116-suite-built-tcltls.md ### G-127 [proposed] Cross-target bake of a custom .vfs: per-target payload and per-target output location -Scope: src/make.tcl (target-keyed output location and deploy folder, kit-name disambiguation by target, payload/target mismatch reporting, retirement of the kit-loop cross-platform TODO); src/runtime/vendorlib_vfs.toml (per-target payload declaration - format coordinated with G-115 and G-024); src/runtime/mapvfs.config (one vfs definition paired with several targets); src/vfs/ (per-target payload convention with punk9linux.vfs as the migration case); bin/kits// (non-native kit output tier, beside the existing bin/runtime// input tier); src/tests/shell/testsuites/punkexe/ (characterization - two-target bake, no-collision, mismatch report); bin/AGENTS.md + src/AGENTS.md (where cross-target kits land) +Scope: src/make.tcl (target-keyed output location and deploy folder, kit-name disambiguation by target, payload/target mismatch reporting, retirement of the kit-loop cross-platform TODO); src/vfs/*.vfs.toml (per-target payload declaration - the achieved G-115 surface this goal adds the platform axis to); src/runtime/mapvfs.toml (one vfs definition paired with several targets); src/vfs/ (per-target payload convention with punk9linux.vfs as the migration case); bin/kits// (non-native kit output tier, beside the existing bin/runtime// input tier); src/tests/shell/testsuites/punkexe/ (characterization - two-target bake, no-collision, mismatch report); bin/AGENTS.md + src/AGENTS.md (where cross-target kits land) Detail: goals/G-127-crosstarget-vfs-bake.md ### G-130 [proposed] 32-bit windows runtimes from the buildsuites, both Tcl generations @@ -379,7 +379,7 @@ Scope: src/buildsuites/suite_tcl90/ and src/buildsuites/suite_tcl86/ (the win32- Detail: goals/G-130-32bit-windows-buildsuites.md ### G-131 [proposed] One runtime, either payload: boot-time container autodetection (metakit or zipfs) -Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (container detection - extends the G-129 zipfs derivation to metakit; both files carry the same code); src/buildsuites/suite_tcl86/ and src/buildsuites/suite_tcl90/ (runtimes carrying both container capabilities, which the detection presupposes); src/make.tcl (the source/target kit-type mismatch check, which today assumes a runtime implies one container); src/runtime/mapvfs.config (kit type as a bake-time choice); bin/runtime/win32-ix86/ (zipfs specimens for the no-regression check); src/tests/shell/testsuites/punkexe/ (characterization); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide) +Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (container detection - extends the G-129 zipfs derivation to metakit; both files carry the same code); src/buildsuites/suite_tcl86/ and src/buildsuites/suite_tcl90/ (runtimes carrying both container capabilities, which the detection presupposes); src/make.tcl (the source/target kit-type mismatch check, which today assumes a runtime implies one container); src/runtime/mapvfs.toml (kit type as a bake-time choice); bin/runtime/win32-ix86/ (zipfs specimens for the no-regression check); src/tests/shell/testsuites/punkexe/ (characterization); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide) Detail: goals/G-131-boot-payload-autodetection.md ### G-132 [proposed] Draft the Tcl-on-windows errno catch-all report for manual submission @@ -395,7 +395,7 @@ Scope: src/tools/punkres/ (VS_VERSIONINFO construction, set-version + field-leve Detail: goals/G-137-kit-version-resources.md ### G-141 [proposed] libfetch consumption-derived target selection with explicit overrides -Scope: src/make.tcl (libfetch target-set derivation + narrow/widen options; VFSLIBS missing-source hint; PACKAGES phase as the host-need input); src/runtime/libpackages.toml (declaration surface as consumed); src/runtime/vendorlib_vfs.toml (source_root="packages" entries as the kit-consumption input - format coordinated with G-115/G-127); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization: derivation, narrowing, widening); bin/AGENTS.md + src/runtime/AGENTS.md (derivation rule documentation) +Scope: src/make.tcl (libfetch target-set derivation + narrow/widen options; VFSLIBS missing-source hint; PACKAGES phase as the host-need input); src/runtime/libpackages.toml (declaration surface as consumed); src/vfs/*.vfs.toml (source_root="packages" entries as the kit-consumption input - the achieved G-115 successor surface; format coordinated with G-127); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization: derivation, narrowing, widening); bin/AGENTS.md + src/runtime/AGENTS.md (derivation rule documentation) Detail: goals/G-141-libfetch-target-selection.md ### G-142 [proposed] Punkbin curated listing manifests: per-tier artifact grouping with named groups diff --git a/goals/G-101-tcl86-kit-container-strategy.md b/goals/G-101-tcl86-kit-container-strategy.md index 3c616108..0a43eb42 100644 --- a/goals/G-101-tcl86-kit-container-strategy.md +++ b/goals/G-101-tcl86-kit-container-strategy.md @@ -1,7 +1,7 @@ # G-101 kit container strategy for zig-built Tcl 8.6 runtimes (no zipfs) Status: proposed -Scope: investigation + decision record under src/buildsuites/suite_tcl86/ (or successor mechanism); src/buildsuites/suite_tcl86/patches/ (tracked sdx wrap.tcl provenance capture); TEMP_REFERENCE/{metakit_jnorthrup,KitCreator,kbs,sdx,tcl9} (read-only guidance - inventory in the detail file); src/runtime/mapvfs.config ('kit' type consumers); src/make.tcl kit-wrap path (as consumer); bin/sdx.kit (the tracked wrapping tool - provenance is part of this goal) +Scope: investigation + decision record under src/buildsuites/suite_tcl86/ (or successor mechanism); src/buildsuites/suite_tcl86/patches/ (tracked sdx wrap.tcl provenance capture); TEMP_REFERENCE/{metakit_jnorthrup,KitCreator,kbs,sdx,tcl9} (read-only guidance - inventory in the detail file); src/runtime/mapvfs.toml ('kit' type consumers); src/make.tcl kit-wrap path (as consumer); bin/sdx.kit (the tracked wrapping tool - provenance is part of this goal) Goal: a decided, demonstrated strategy for wrapping zig-built 8.6 runtimes into self-contained punk86-class kit executables in the absence of zipfs - candidate containers: the metakit/mk4vfs tclkit lineage, cookfs, and zipvfs-over-tclvfs boot - so the prebuilt third-party kit runtimes (tclkit86bi.exe, tclkit-win64-dyn.exe) can eventually be replaced by suite-built, provenance-carrying ones. Acceptance: the candidate containers are assessed and recorded here against punkshell's kit expectations (compatibility with make.tcl's 'kit' wrap path or a documented replacement path; boot-time vfs mount without an installed Tcl; loading binary dlls from or via the container; buildable from source under the zig-only policy); one strategy is demonstrated end-to-end - a kit wrapped from the suite-built 8.6 runtime boots on a path without any Tcl installation and runs a script from inside its vfs; the decision, rationale, and the follow-on work needed to reach punk86-kit parity are recorded in this file. diff --git a/goals/G-127-crosstarget-vfs-bake.md b/goals/G-127-crosstarget-vfs-bake.md index f2eed621..7a6ab97d 100644 --- a/goals/G-127-crosstarget-vfs-bake.md +++ b/goals/G-127-crosstarget-vfs-bake.md @@ -1,7 +1,7 @@ # G-127 Cross-target bake of a custom .vfs Status: proposed -Scope: src/make.tcl (target-keyed output location and deploy folder, kit-name disambiguation by target, payload/target mismatch reporting, retirement of the kit-loop cross-platform TODO); src/runtime/vendorlib_vfs.toml (per-target payload declaration - format coordinated with G-115 and G-024); src/runtime/mapvfs.config (one vfs definition paired with several targets); src/vfs/ (per-target payload convention with punk9linux.vfs as the migration case); bin/kits// (non-native kit output tier, beside the existing bin/runtime// input tier); src/tests/shell/testsuites/punkexe/ (characterization - two-target bake, no-collision, mismatch report); bin/AGENTS.md + src/AGENTS.md (where cross-target kits land) +Scope: src/make.tcl (target-keyed output location and deploy folder, kit-name disambiguation by target, payload/target mismatch reporting, retirement of the kit-loop cross-platform TODO); src/vfs/*.vfs.toml (per-target payload declaration - the achieved G-115 surface this goal adds the platform axis to); src/runtime/mapvfs.toml (one vfs definition paired with several targets); src/vfs/ (per-target payload convention with punk9linux.vfs as the migration case); bin/kits// (non-native kit output tier, beside the existing bin/runtime// input tier); src/tests/shell/testsuites/punkexe/ (characterization - two-target bake, no-collision, mismatch report); bin/AGENTS.md + src/AGENTS.md (where cross-target kits land) Goal: one kit definition bakes for several declared target platforms from a single source of truth - each target getting ITS binary payload and an output location that cannot be overwritten by another target's kit of the same name - so building a custom .vfs for this machine and for FreeBSD is a declaration, not a duplicated .vfs folder and a naming convention held in the developer's head. G-122 made the build read the right runtime for a target; this makes it write the right kit for one. Acceptance: two mapvfs entries pairing the SAME vfs definition with two different targets bake in one run to distinct artifacts - a native-target kit stays at bin/ exactly where it lands today, a non-native one at bin/kits// with src/_build separated the same way - and neither is overwritten when the two are baked as separate selective single-kit runs (the current defect: exe_names_seen resets per run, so the second write lands on the first); two NON-NATIVE targets sharing a kit name coexist as distinct artifacts, where today they collide or are disambiguated by runtime name rather than by platform; the binary payload installed into each target's kit is selected for that target from src/vendorlib_tcl/ through one declaration rather than by duplicating a .vfs folder per target, and a kit declared for a single target builds byte-comparably to today; a payload binary that would be LOADED on the kit's target but was built for another platform is reported naming the file and both platforms, while per-platform subdirectory layouts that the loader resolves correctly (e.g tcllib's //) are explicitly not flagged; bakelist shows each row's output location; the existing punk9linux.vfs is either migrated to the declaration or recorded here as deliberately staying hand-curated, and the linux punkshell902 kit's move from bin/ to bin/kits/linux-x86_64/ is recorded as an intended relocation; the G-023 reconciliation is stated (version-named outputs compose with the platform directory rather than competing with it); native win32 kit outputs are unchanged in name and location and the existing punkexe suites pass unchanged; the kit-loop TODO at src/make.tcl "allow building of kits for other platforms" is retired pointing here. diff --git a/goals/G-131-boot-payload-autodetection.md b/goals/G-131-boot-payload-autodetection.md index 9bb981c4..0f2521a5 100644 --- a/goals/G-131-boot-payload-autodetection.md +++ b/goals/G-131-boot-payload-autodetection.md @@ -1,7 +1,7 @@ # G-131 One runtime, either payload: boot-time container autodetection Status: proposed -Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (container detection - extends the G-129 zipfs derivation to metakit; both files carry the same code); src/buildsuites/suite_tcl86/ and src/buildsuites/suite_tcl90/ (runtimes carrying both container capabilities, which the detection presupposes); src/make.tcl (the source/target kit-type mismatch check, which today assumes a runtime implies one container); src/runtime/mapvfs.config (kit type as a bake-time choice); bin/runtime/win32-ix86/ (zipfs specimens for the no-regression check); src/tests/shell/testsuites/punkexe/ (characterization); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide) +Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (container detection - extends the G-129 zipfs derivation to metakit; both files carry the same code); src/buildsuites/suite_tcl86/ and src/buildsuites/suite_tcl90/ (runtimes carrying both container capabilities, which the detection presupposes); src/make.tcl (the source/target kit-type mismatch check, which today assumes a runtime implies one container); src/runtime/mapvfs.toml (kit type as a bake-time choice); bin/runtime/win32-ix86/ (zipfs specimens for the no-regression check); src/tests/shell/testsuites/punkexe/ (characterization); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide) Goal: one punk runtime per platform and Tcl generation boots from whichever payload container is attached to it - metakit or zipfs - so the container becomes a bake-time choice rather than a property fixed when the runtime is acquired, and the number of runtime deliverables is set by platform and generation alone. Acceptance: ONE runtime binary, byte-identical between the two runs, boots and resolves its own payload from a metakit-wrapped kit AND from a zipfs-attached kit built from the same .vfs - internal modules/ and lib/ trees on tcl::tm::list and auto_path, and a package existing only inside the kit resolving, in both cases; container selection reads what is actually attached, with no compile-time or bake-time constant naming it, verified by wrapping that one runtime both ways from the same source tree; the zipfs arm is inherited from G-129 rather than re-specified - this goal's zipfs obligation is only that G-129's derivation still holds when reached through container detection, checked against the existing bin/runtime/win32-ix86 specimens; a runtime carrying a payload the boot cannot identify says so on stderr rather than continuing silently with no internal paths; punkshell's existing kits are unaffected, verified by comparing internal tcl::tm::list and auto_path before and after across at least one zipfs kit and one starkit-family kit; make.tcl's source/target kit-type mismatch check is reconciled with runtimes that legitimately support more than one container, rather than warning or skipping on them; cookfs and other exotics are explicitly out of scope with their existing branches untouched; and the deliverable reduction is recorded concretely - which runtimes collapse into which, and what the per-platform-per-generation count becomes. diff --git a/goals/G-141-libfetch-target-selection.md b/goals/G-141-libfetch-target-selection.md index 8d79ec16..d026c28c 100644 --- a/goals/G-141-libfetch-target-selection.md +++ b/goals/G-141-libfetch-target-selection.md @@ -1,7 +1,7 @@ # G-141 libfetch consumption-derived target selection Status: proposed -Scope: src/make.tcl (libfetch target-set derivation + narrow/widen options; VFSLIBS missing-source hint; PACKAGES phase as the host-need input); src/runtime/libpackages.toml (declaration surface as consumed); src/runtime/vendorlib_vfs.toml (source_root="packages" entries as the kit-consumption input - format coordinated with G-115/G-127); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization: derivation, narrowing, widening); bin/AGENTS.md + src/runtime/AGENTS.md (derivation rule documentation) +Scope: src/make.tcl (libfetch target-set derivation + narrow/widen options; VFSLIBS missing-source hint; PACKAGES phase as the host-need input); src/runtime/libpackages.toml (declaration surface as consumed); src/vfs/*.vfs.toml (source_root="packages" entries as the kit-consumption input - the achieved G-115 successor surface; format coordinated with G-127); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization: derivation, narrowing, widening); bin/AGENTS.md + src/runtime/AGENTS.md (derivation rule documentation) Goal: 'make.tcl libfetch' fetches what the checkout will consume rather than everything declared - the default target set is derived from the consumption declarations already in the tree (the host's lib_tcl deploy needs plus the lib-tier targets consumed by the kit set in play), with explicit options to narrow (a selective bake's kit set) and widen (the full declared set) - so libpackages.toml can grow across platforms, architectures and libraries without every host downloading every artifact. Acceptance: a linux host preparing the linux kit set obtains exactly its consumed set - allplatforms + linux-x86_64 fetched, win32-x86_64 NOT fetched, observable in the libfetch action report - via the default derivation or a single derived invocation libfetch/the bake names; the canonical win32 host's default stays bake-sufficient (linux-x86_64 derived for the punk9linux.vfs cross-target need; a default fetch then a full bake hits no missing-packages-source error); an explicit widening option fetches the full declared set (mirror priming / prepopulation); libfetch reports the derived targets and which declaration pulled each in; the VFSLIBS missing-source message names an invocation that fetches what the failing bake actually needs; maketcllibfetch.test characterizes derivation, narrowing and widening through the existing PUNK_LIBFETCH_CONFIG / PUNK_LIBFETCH_PACKAGES seams; the derivation rule is documented in the tier docs.