punkshell/goals/G-025-exe-selfreport.md

G-025 Punk executables self-report project version and build provenance

Status: proposed Scope: src/vfs/_config/punk_main.tcl (subcommand dispatch), src/make.tcl (stamping build info into the vfs), src/vfs/ (stamp payload location), src/modules/punk/ (in-shell command - the single implementation) Goal: a punk executable reports its identity from embedded data rather than its filename - a documented subcommand prints the punkproject.toml project version it was built from plus the input runtime binary name and vfs folder name used to assemble it - with the same-named command available in the punk module so scripts running in any punk shell (including tclsh-hosted ones like tclsh src/make.tcl shell) get the same report in-process without exec, stamp fields reported as absent rather than fabricated when there is no stamp. Acceptance: the build stamps project version, runtime binary name, and vfs folder name into the kit; the built executable invoked with the version-report subcommand prints those fields machine-parseably on stdout and exits 0 with no other output (G-015-compatible; no repl fallthrough); a same-named command in the punk module returns the same fields in-process (subcommand implemented as a wrapper over it - one implementation) and works from the code interp; the report distinguishes stamped provenance from live facts: a stamped kit reports its stamp, a src-mode or source-tree session additionally reports the live punkproject.toml version as a distinct field when it differs, and unstamped contexts (tclsh src/make.tcl shell, plain tclsh with punk modules) report stamp fields explicitly absent with live runtime facts (actual info nameofexecutable) still provided; the report is correct when the executable file has been renamed or copied; executables built before stamping existed fail gracefully with a clear message rather than fabricating values.

Context

With G-023 producing version-named binaries, an executable's name encodes its version - but names are mutable (copies, renames, the -dev and release-gated plain names) and say nothing about the runtime binary or vfs folder the build consumed. The executable should answer for itself from embedded data: a version-report subcommand at the launch layer, and the same-named command in the punk module for scripts already running inside a punk shell.

The in-shell command is not merely an optimization over exec'ing out. In a tclsh-hosted punk shell (tclsh src/make.tcl shell loads punk::repl directly into the host tclsh - make.tcl ~1913) there is no punk executable to exec: info nameofexecutable is the external tclsh, and invoking it with the subcommand would be meaningless. The in-process command is the only correct path there - hence the module command is the single implementation and the exe subcommand is a thin dispatch wrapper over it (which is also what guarantees the two surfaces report identically).

Report semantics: three distinct notions

Only in a plainly-launched stamped kit do these coincide; the report must keep them distinct and never fabricate:

1. Build stamp - project version, runtime binary name, vfs folder name, fixed at kit assembly by make.tcl. Absent in unstamped contexts.
2. Live runtime facts - actual info nameofexecutable, patchlevel. Always available.
3. Source-tree project version - punkproject.toml, available when running from a source tree regardless of stamping.

Edge cases driving the acceptance clauses:

• tclsh src/make.tcl shell: no stamp. Stamp fields reported explicitly absent; live facts show the real host tclsh; the source-tree version may be reported but flagged as live-from-punkproject.toml, not as a stamp.
• Kit launched in src mode (punk902z src): a stamp exists, but the running code is working-tree dev modules whose punkproject.toml may be ahead of the stamped version. Reporting only the stamp misstates what is running; only the live version misstates provenance - report both, distinctly labelled, when they differ.
• Plain tclsh with installed punk modules and no source tree: no stamp, no punkproject.toml - live facts only.
• Renamed/copied executables: the report comes from the stamp, so it stays correct whatever the file is called.
• Pre-stamping kits: the subcommand/command fails gracefully with a clear message.

Approach notes

• The command must work from the code interp (where scripts run), not just the repl thread - trivial for static stamp data, but stated so the G-007 location-transparency expectation is met.
• The subcommand output must be machine-parseable, exit 0, and emit nothing else on stdout/stderr - usable through G-015 piped calls and by exec-style callers.
• Naming (e.g. buildinfo) is an implementation decision: the in-shell command name must match the subcommand name and not collide with existing repl commands.
• Stamp location within the vfs payload is an implementation decision to record here (candidates: a dedicated stamp file under the vfs _config, or fields merged into an existing boot config file).

Alternatives considered

• In-shell command exec'ing its own executable with the subcommand - rejected: wrong in tclsh-hosted shells (no punk executable to call), needless process spawn elsewhere, and two code paths that can drift.
• Reporting only the stamped version and ignoring live/source-tree context - rejected: actively misleading in src-mode sessions, which are the primary working-tree verification workflow (bin/AGENTS.md).

Notes

• Related: G-023 (version-named binaries this complements), G-024 (build mapping that will drive stamping inputs), G-015 (piped invocation of the subcommand), G-014 (punkproject.toml reading may share tomlish plumbing).
• Archived-goal references in this file: G-007 achieved 2026-07-05 (goals/archive/G-007-console-location-transparency.md);G-015 achieved 2026-07-07 (goals/archive/G-015-script-subcommand-piped-stdin.md).