G-119 proposed: punk-runtime active-vs-default freshness verdict (ahead/behind/current)

Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai

GOALS.md

@@ -397,3 +397,7 @@ Detail: goals/G-117-self-describing-runtimes.md
 ### G-118 [proposed] tclsh subcommand review: stock-parity gaps, piperepl residue, docs and console-path tests
 Scope: src/vfs/_config/punk_main.tcl (tclsh dispatch), src/vfs/_config/project_main.tcl (parity), src/buildsuites/suite_tcl90/patches/ (tclMain piperepl rev items), src/tests/shell/testsuites/punkexe/tclshcmd.test (coverage additions)
 Detail: goals/G-118-tclsh-subcommand-review.md
+
+### G-119 [proposed] punk-runtime active-vs-default freshness verdict (ahead/behind/current)
+Scope: src/scriptapps/bin/punk-runtime.ps1 + punk-runtime.bash (+ rewrapped bin/punk-runtime.cmd), bin/AGENTS.md (runtime-manager contract), src/tests/modules/punk/mix/testsuites/scriptwrap/ (roundtrip pin; behavioural fixture surface settled in the work)
+Detail: goals/G-119-runtime-active-freshness.md

goals/G-119-runtime-active-freshness.md

@@ -0,0 +1,30 @@
+# G-119 punk-runtime active-vs-default freshness verdict (ahead/behind/current)
+
+Status: proposed
+Scope: src/scriptapps/bin/punk-runtime.ps1 + punk-runtime.bash (+ rewrapped bin/punk-runtime.cmd), bin/AGENTS.md (runtime-manager contract), src/tests/modules/punk/mix/testsuites/scriptwrap/ (roundtrip pin; behavioural fixture surface settled in the work)
+Goal: punk-runtime states the relationship between the ACTIVE runtime and the SERVER DEFAULT whenever both are known - current / ahead / behind / incomparable - so an operator is never silently ahead of or behind the curated recommendation. Today use/list record and display each fact separately (the active's revision only via its beside-toml summary, the default only as a row annotation), and a no-name fetch reports on the default artifact alone ("No download required"), leaving active r2 with default r1 and active r1 with default r3 equally invisible. The comparison uses revision fields where both sides carry them (active: beside-toml revision/name for materialized working copies, -rN parsed from the name for artifact-named actives; default: -rN parsed from its defaults.txt name), with sha1 VALUE-matching of local runtimes against the server sha1sums as the identity fallback for runtimes with no revision basis (pre-family).
+Acceptance: against a fixture server (PUNKBIN_URL override): (1) active materialized from r2 with server default r1 -> list -remote prints an explicit ahead verdict naming both revisions; (2) active r1 with default r2 -> behind verdict plus update guidance (fetch + use); (3) active == default -> the existing (= server default) annotation or an equivalent current verdict; (4) a pre-family active (no toml, no -rN name) yields a stated no-revision-basis note - or its hash-identity when its sha1 matches a server artifact - rather than silence or a crash; (5) a no-name fetch prints a one-line active-vs-default note when the two diverge. Both payloads deliver identical verdicts (ps1/bash parity), the runtimecmd roundtrip pin stays green, and bin/AGENTS.md's runtime-manager contract records the new surface.
+
+## Context
+
+Gap reported by the user 2026-07-24: 'use tclsh9.0.5-punk-r2.exe' + no-name
+fetch against a server default of r1 produces "No download required" with no
+indication the active working copy is a revision ahead of (or, mirrored,
+behind) the curated default. Verified against both payloads and the goals
+tree: no existing goal covers freshness comparison - G-117 (identity/schema)
+deliberately rejects lifecycle fields ("repo-level curation (defaults.txt and
+successors), not artifact facts"), so this verdict is computed at display time
+from repo data + local state and requires no artifact-record change. The sha1
+substrate already exists (list -remote hashes local runtimes but compares
+name-keyed only; a working copy's sha1 equals its source artifact's, so
+value-matching identifies it against the server listing).
+
+## Alternatives considered
+
+- Compare against the NEWEST -rN on the server in the active's
+  (patchlevel, variant) series instead of the curated default - deferred:
+  newest-on-server can legitimately coexist with an older default by
+  deliberate curation, making the verdict ambiguous; the default is the
+  actionable recommendation. Possible later secondary signal.
+- Artifact-record lifecycle fields (superseded_by) - rejected per G-117's
+  recorded rationale (repo-level curation, not artifact facts).