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) Acceptance: as in root GOALS.md index (canonical).

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-<major>-<minor>-<patch>.exe / punk9-<major>-<minor>-<patch>.exe - produced as the version advances; a rebuild at an unchanged version refreshes that version's binaries in place.
• 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.

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).