punkshell/goals/G-122-host-target-platform-split.md

G-122 make.tcl host/target platform split: bake by target, not host personality

Status: proposed Scope: src/make.tcl (target-platform derivation; store folder, exe suffixing, kit naming, presence checks and process-sweep tooling keyed by target; platform-canon inline copy; zipfs-less zip-type assembly fallback); src/modules/punk/platform-999999.0a1.0.tm (stable canon tags for cygwin-family hosts, help platforms doc); src/runtime/mapvfs.config (per-entry target platform via minimal compatible extension - format ownership coordinated with G-024); bin/runtime// store tiers (as consumed; fixture tier for tests); src/tests/shell/testsuites/punkexe/ (characterization) Goal: make.tcl's kit surfaces (bake/bakelist/bin) operate on an explicit target platform rather than the driving tclsh's personality: any capable host (native windows tclsh, msys/cygwin-runtime tclsh, a FreeBSD host running linux binaries) addresses the same per-target runtime store, artifact naming and process handling for the kits it reports/bakes; non-native-personality runtime tiers (e.g third-party mingw64 builds served from punkbin or an alternative artifact server) are representable as first-class mapping entries with their own store tier; and zip-type kit assembly no longer requires zipfs in the driving tcl. Acceptance: an msys/cygwin-runtime tclsh driving bakelist/bake on windows reports - and for a changed kit, bakes and deploys - the same win32-x86_64 kit set with identical names and store addressing as a native tclsh, with the pre-deploy process sweep using windows tooling for win32 targets regardless of host personality; punk::platform and the make.tcl inline canon map MSYS_NT/MINGW64_NT/CYGWIN_NT/UCRT64-class hosts to stable documented tags (MSYSTEM-variance documented, no windows build number in the tag) and 'help platforms' lists them; a mapvfs entry declaring a non-default target platform lists in bakelist with its own tier's store presence and bakes to a correctly suffixed artifact, verified against a fixture store tier (a real third-party runtime is not required); a zipfs-less driving tcl (8.6) assembles a zip-type kit via runtime split + punk::zip::mkzip + concatenation (archive-start-relative offsets) and the artifact boots on a zipfs-capable runtime; the linuxulator expectation (a linux-personality tclsh on FreeBSD 14/15 addresses the linux-x86_64 store unchanged) is recorded here with verification deferred to the planned linux-kit-on-FreeBSD trial; native-windows behaviour stays characterization-stable (existing punkexe maketcl tests pass unchanged).

Context

Field session 2026-07-26: the scoop msys2 tclsh8.6 driving src/make.tcl bakelist on windows showed every configured kit as runtime=missing (and deployed absent) from two compounding causes: the store folder derives from the HOST's platform canon (observed mingw64-x86_64 under a MINGW64_NT os string - note the tag follows the MSYSTEM environment, so the same binary can canonize as msys/ucrt64/mingw64 in different shells), and the platform=unix branch probes suffixless filenames - an assumption that is false for the entire cygwin family, whose executables are .exe files (the msys tclsh itself is tclsh8.6.exe). The interim self-diagnosis shipped in punkshell 0.24.1 (bakelist store-folder WARNING with the canon derivation + (FOLDER MISSING) header mark; bake's no-runtimes exit note) tells the user what happened; this goal makes the tooling actually cater for it.

The underlying defect is a conflation: make.tcl's scattered $::tcl_platform(platform) eq "windows" tests mix three separable concerns - host process semantics (cp vs cmd /c copy, ps/kill vs tasklist/taskkill, path personality), target artifact naming (.exe suffixing, kit/output names), and store addressing (bin/runtime/<canon>). An msys host pulls them apart. The process sweep is the sharpest edge: msys ps sees only msys-descendant processes, so a natively-launched kit exe is invisible to the pre-deploy sweep (taskkill remains exec-able from msys).

Direction (user, 2026-07-26): even if msys never becomes a zig buildsuite target, third-party-built runtime tiers (e.g an msys2-packaged tclsh) served from punkbin or an alternative artifact server must be supportable as kit runtimes - REPRESENTATION (mapping entry + store tier) belongs here; publication/fetch is the flagged follow-on goal.

FreeBSD linuxulator parallel (user): a linux-personality tclsh running on FreeBSD via the linux compat layer is expected to self-identify as linux and address bin/runtime/linux-x86_64 correctly - the planned linux-kit-on-FreeBSD-14/15 trial doubles as verification that target-keyed stores follow runtime personality, not host OS identity.

Zip offsets (user correction, 2026-07-26): tcl zipfs kits mount with archive-start-relative offsets - cat-style construction (split the original runtime first, then append a freshly written zip) is valid; zipfs mkimg's file-relative offset adjustment is one convention, not a mounting requirement. The existing zipcat kit type is the in-repo proof, and its machinery already has zipfs-less fallbacks.

Approach

• One target_platform derivation: default from the host canon, with cygwin-family hosts on windows defaulting to target win32-x86_64; per-entry mapping override for non-default tiers (a minimal compatible extension of the current vfsconfig entry - e.g a fourth element - whose schema home is G-024's toml conversion; the parsed-model seam (G-121, achieved - see goals/archive/G-121-bakelist-selective-bake.md) keeps every consumer format-agnostic while the format moves).
• Key store folder, suffixing, kit/artifact naming, presence checks and the process-sweep tool selection by TARGET; keep copy commands, path handling and prompt behaviour host-driven.
• punk::platform canon: explicit MSYS_NT/MINGW64_NT/CYGWIN_NT/UCRT64 mapping to stable documented tags with the MSYSTEM-variance caveat; the make.tcl inline canon copy stays in sync per its existing comment contract.
• zip-type fallback for zipfs-less driving tcls: reuse the zipcat machinery (extract_preamble split + punk::zip::mkzip + concatenation).
• Characterization against a fixture store tier so no real third-party runtime is required; the msys-hosted acceptance run uses the dev machine's msys tclsh where present (else recorded env-gated, per punkexe suite conventions).

Alternatives considered

• Per-site host patches (special-case each windows test) - rejected: the three-concern conflation just re-accumulates with each new host class.
• Full self-hosted msys platform lineage (msys-personality kits, accelerator builds, own test baselines) - out of scope: the third-party tier direction covers the need without a new first-party build lineage.
• Status quo (require a native tclsh to drive make.tcl) - rejected: field friction (the all-missing bakelist), and upcoming linux/FreeBSD hosts make host-personality assumptions untenable regardless of msys.

Notes

• Related: G-024 - owns the mapping format; the per-entry target platform is drafted as a minimal compatible extension and its schema home is that goal's toml conversion (make.tcl's own comments already pair the platform column with the toml change).
• Related: G-105 - cross-target zig builds populate first-party non-native store tiers; this goal is the consuming/addressing side.
• Related: G-114 - same punk::platform canon vocabulary, applied to per-platform tm module roots.
• Related: G-101 - 8.6 kit containers ride the same mapping/store surfaces; lister/bake stay kit-type-agnostic (per the archived G-121 decision).
• Related: G-057 - per-entry mapping extension precedent (per-vfs icon override rides the same entry shape).
• Related: G-023 - kit naming schemes; target-keyed naming must not collide with its version-named binaries direction.
• Follow-on candidate (flagged, drafted separately for approval): third-party runtime tier publication/fetch via punkbin or alternative servers (punk-runtime payloads, server platform manifests, consent gating per G-006, artifact-channel kinship with G-067).
• Out of scope: msys pty raw-mode console/repl behaviour - the cursor-row-1 field finding of 2026-07-26 is recorded in G-013's Notes.