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
### 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)
### 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/<platform>/ (non-native kit output tier, beside the existing bin/runtime/<platform>/ 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/<platform>/ (non-native kit output tier, beside the existing bin/runtime/<platform>/ 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
# 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.
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/<platform>/ (non-native kit output tier, beside the existing bin/runtime/<platform>/ 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/<platform>/ (non-native kit output tier, beside the existing bin/runtime/<platform>/ 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/<name> exactly where it lands today, a non-native one at bin/kits/<platform>/<name> 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<N>/<platform> 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 <pkg>/<platform>/<lib>) 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.
# 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.
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<N> 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.
