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