Browse Source

G-127 activated (user-approved): status flip both tiers + freshness Related: lines; G-060 VMM survey notes

- GOALS.md index + detail mirror: G-127 proposed -> active
- G-127 Notes: G-060 runnability-split note (acceptance host-verifiable end to end;
  on-target execution of cross-target kits = G-060 territory), plus G-141 and G-137
  back-pointers from the goals_xref score freshness survey
- G-060 Alternatives considered: crosvm rejected (no FreeBSD guests), Firecracker VMM
  review candidate (FreeBSD guests, Apache-2.0; GPL undesirable but not a showstopper),
  QEMU strong lean re-affirmed (widest guest + dev-host support)

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
master
Julian Noble 1 week ago
parent
commit
dca5ea6f40
  1. 2
      GOALS.md
  2. 19
      goals/G-060-qemu-test-matrix.md
  3. 25
      goals/G-127-crosstarget-vfs-bake.md

2
GOALS.md

@ -370,7 +370,7 @@ Scope: src/buildsuites/suite_tcl90/ (build_tcltls module + crypto-backend build,
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
### G-127 [active] 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/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

19
goals/G-060-qemu-test-matrix.md

@ -54,6 +54,25 @@ direction rather than a new ad-hoc location.
- Guest provisioning recipes (image fetch, first-boot setup, ssh keys) documented per
guest in the detail/config - repeatable, not artisanal.
## Alternatives considered
- crosvm (BSD-3-Clause) - considered 2026-07-31 for its more punkshell-aligned
license - rejected: it cannot run FreeBSD guests, and FreeBSD x86_64 is this
matrix's first non-WSL target (Sequencing above) precisely because nothing else
covers it.
- Firecracker VMM (Apache-2.0) - review candidate recorded 2026-07-31, to be weighed
when this goal is next reviewed/activated: unlike crosvm it supports FreeBSD
guests, and its license sits closer to punkshell's BSD posture than QEMU's GPLv2.
Weighing context recorded with the candidate: GPL, while undesirable, is understood
NOT to be a showstopper here - the arm's-length external-process posture above
already contains it. Also note Firecracker (like crosvm) is a KVM/linux-host VMM,
so driving guests from the Windows dev machine (Acceptance) would mean hosting the
VMM itself inside WSL2.
- QEMU (the incumbent in Goal/Acceptance) - strong lean re-affirmed 2026-07-31:
apparently the widest guest support (linux variants, all three BSDs, arm
architectures - the full matrix in Goal) and the widest support for running on the
host development systems themselves.
## Notes
- Related: [[G-005]] (zig builds - the same guests could eventually host build

25
goals/G-127-crosstarget-vfs-bake.md

@ -1,6 +1,6 @@
# G-127 Cross-target bake of a custom .vfs
Status: proposed
Status: active
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.
@ -174,3 +174,26 @@ exists locally (empty but for sha1sums.txt) and punkbin upstream carries
2026-07-31): the PUNK_MAPVFS_CONFIG env var now points bakelist/bake at an alternate
mapping file (used by the G-024 fixture tests in maketclbakelist.test) - this goal's
cross-target characterizations can pin behaviour without editing the real config.
- Related: G-060 (recorded at activation, 2026-07-31) - the runnability split, settled
as part of the activation decision: every Acceptance clause here is host-verifiable
(artifact locations and cross-run coexistence are filesystem facts, payload selection
is verified by inspecting kit contents, the G-125 gate is non-executing by design,
and G-133's smoke probe skips non-runnable targets with a stated reason), so
acceptance does not depend on EXECUTING a non-native kit on its platform - which
this host cannot do for the FreeBSD case. On-target execution of cross-target kits
belongs to G-060's guest matrix (its Alternatives survey, same date, records the VMM
weighing: crosvm rejected, Firecracker review candidate, QEMU lean stands). Beyond
contract, linux-x86_64 kits can get an opportunistic WSL execution smoke (the
punkshell902 pattern from G-140, achieved 2026-07-30 - see
goals/archive/G-140-linux-lib-tier-emission.md).
- Related: G-141 - libfetch consumption-derived target selection: the per-target
payload declarations this goal adds to src/vfs/*.vfs.toml are that goal's derivation
input, and its Acceptance's bake-sufficiency clause leans on them (its Notes record
the pairing - whichever lands second adopts the other's surface). Back-pointer added
at the activation freshness survey 2026-07-31 (goals_xref score: strongest
one-directional pair).
- Related: G-137 - RT_VERSION stamping rides the same kit-icon wrap seam whose outputs
this goal relocates: its stamp + <kit>.resources.toml sidecar emission must follow
non-native artifacts to bin/kits/<platform>/ (the same per-target wrap-seam
composition question the G-057 icon note above records; bridge recorded from its
side 2026-07-31, back-pointer added at the activation freshness survey).

Loading…
Cancel
Save