punkshell/goals/G-023-version-named-binaries.md

G-023 Version-named punk binaries per Tcl generation (versioned / dev / release-gated plain names)

Status: proposed Scope: src/make.tcl; src/runtime/ (mapping config - see G-024); bin/ (build outputs) Goal: project builds produce version-named punk executables for tcl 8.6 and tcl 9 as the project version advances, adopting the G-103 kit-artifact naming decision - punk8-.exe / punk9-.exe with dotted versions (e.g punk9-0.5.0.exe, prerelease punk9-0.5.0b2.exe) per version - plus the policy layer this goal owns: punk8-dev.exe / punk9-dev.exe tracking the latest build, and plain punk8.exe / punk9.exe created initially then replaced only when an actual release is tagged - tolerating the disk growth for now. Acceptance: a project build at the current punkproject.toml version produces punk8-.exe and punk9-.exe in the G-103-decided dotted form (names derived from the version, not hand-maintained - e.g punk9-0.5.0.exe) plus punk8-dev.exe / punk9-dev.exe updated to that same build; rebuilding at an unchanged version refreshes that version's binaries and -dev without touching other versions' outputs; plain punk8.exe / punk9.exe exist and are replaced only by an explicit release step - a normal build never overwrites them; the scheme is declared succinctly via the G-024 toml mapping (no per-version config edits) and matches the kit-artifact tier of the G-103 naming decision; archival/deletion of accumulated versioned binaries is out of scope with the trigger question recorded in the detail file.

Context

The project version is now tracked and change-driven-bumped in punkproject.toml (root AGENTS.md "Project Versioning"), so builds can be named after it. Today's build outputs are fixed names declared line-by-line in src/runtime/mapvfs.config (punksys, punk902z, ...) that encode the runtime generation informally and say nothing about the project version they contain - which build a given exe represents is unknowable without launching it (G-025 addresses the launching side; this goal addresses the naming side).

Naming scheme:

• punk8-<punkshellversion>.exe / punk9-<punkshellversion>.exe (dotted, e.g punk9-0.5.0.exe; prerelease punk9-0.5.0b2.exe) - produced as the version advances; a rebuild at an unchanged version refreshes that version's binaries in place. The version axis is the PUNKSHELL version (the payload), never the tcl patchlevel - that is metadata's job (G-103 decision).
• punk8-dev.exe / punk9-dev.exe - always the latest build, refreshed every build.
• punk8.exe / punk9.exe - created initially, then replaced only by an explicit release step when an actual release is tagged. A normal build never touches them.

Tier mapping (G-103 naming decision, user-approved 2026-07-21): the versioned names above are that decision's published/archived KIT ARTIFACT form punk-(.exe) verbatim; plain punk8.exe / punk9.exe are its major-only WORKING names, with this goal supplying their materialization policy (the explicit release step); -dev is an additional working-name flavour alongside the decision's recognized dev-matrix style (punk905, punk902z, ...), which stays available via explicit mapvfs entries.

The 8/9 generation split matches the existing dual-generation verification practice (bin/AGENTS.md: a Tcl 8.6 punk shell and a current Tcl 9 punk shell).

Approach

• Names derive from punkproject.toml at build time - no hand-maintained per-version config entries. The scheme is declared once, succinctly, in the G-024 toml mapping; the expansion to concrete output names happens in make.tcl.
• The release step that updates the plain punk8.exe/punk9.exe names should be an explicit make.tcl action tied to release tagging, not a side effect of a normal build. Its precise trigger (fossil/git tag presence, or a manual subcommand) is an implementation decision to record here.
• Existing specifically-named outputs (punksys, punk902z, ...) keep working via their explicit mappings (G-024 preserves them); the versioned scheme is additive.

Space and archival

These binaries are large. Accumulating one pair per project version is accepted for now. Out of scope but recorded for later: a trigger mechanism for archival/deletion (e.g. keep-latest-N per generation, prune non-release versions older than a threshold, or move to an artifact store per G-006's binary-artifacts repository). Revisit when the accumulation actually bites.

Alternatives considered

• Encoding the version only inside the kit (G-025) and keeping fixed exe names
  • rejected as insufficient alone: side-by-side versioned binaries are the point (running/comparing multiple versions without rebuilds).
• Symlinks/hardlinks for -dev and plain names instead of copies - deferred to implementation: Windows link semantics for running executables are fiddly; copies are acceptable at current sizes.

Notes

• Related: G-024 (scheme declared in toml mapping), G-025 (exe self-reports its version/provenance - the complement of name-encoded versioning once files are renamed/copied), G-006 (future artifact-store home for archived versions), G-018/G-019 (other points on the executable-flavour spectrum).
• 2026-07-21: reconciled with the G-103 runtime/kit naming decision (user-approved reconciliation): version encoding flipped from the original hyphenated punk9---.exe draft to the decided dotted punk-.exe form, and the goal is now framed as the make.tcl/bin-side ADOPTION of that decision's kit-artifact tier plus the -dev / release-gated-plain-name policy layer (which the decision deliberately leaves under project-owner control). Naming authority: G-103's NAMING DECISION section (achieved 2026-07-22 - goals/archive/G-103-runtime-kit-family.md; the decision text is stable there flipped).
• G-057 relationship (recorded 2026-07-24; achieved 2026-07-29, archived - see goals/archive/G-057-kit-icon-embedding.md): the icon-embedding step now LIVES in the kit wrap steps this goal hooks - stub-first (a per-kit stamped copy of the raw runtime prefix feeds the assemblers), re-run from a pristine re-split prefix every build, so this goal's every-build rewrite cadence and the stamping converge by construction. Scheme-expanded output names would each get their own .resources.toml sidecar via the same per-targetkit emission.
• G-121 (archived) recorded that scheme-expanded output names should enter the parsed mapping model as expansions (::punkboot::lib::mapvfs_kit_outputs) so generated names join the bakelist / bake-by-name surface automatically when this goal lands - see goals/archive/G-121-bakelist-selective-bake.md