From cd13f5679b452196fcc56f49249c8ac7006612f0 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 21 Jul 2026 03:51:06 +1000 Subject: [PATCH] G-103: runtime/kit naming decision recorded (user-approved 2026-07-21) Two naming tiers mapped by tooling: immutable fully-qualified ARTIFACT names in punkbin vs short stable WORKING names consumed by mapvfs and typed by users, with 'runtime use' and mapvfs as the mapping. Runtime artifacts: tclsh[-punk[-bi]]-r (dotted patchlevels required, always-present assembly-revision tail, no punkshell version or patch revision in the name - metadata is authoritative); working names drop the -rN. Kits flip the release axis to the punkshell version: major-only typable working names (punk9/punk8/punk9bi), artifact names punk-; the dev-matrix style (punk905 etc) remains a recognized owner-controlled third style. Hyphen separators (no punk- prefix or PATH collision in these namespaces), '+' banned for punkbin URLs, ordering by metadata not filename sort. Resolves the acceptance's tcl-patchlevel/punk-version/separator questions; the acceptance's pre-decision tclsh905punk.exe example is noted as superseded by the dotted -punk shape. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- goals/G-103-runtime-kit-family.md | 55 ++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/goals/G-103-runtime-kit-family.md b/goals/G-103-runtime-kit-family.md index f376e306..500a9379 100644 --- a/goals/G-103-runtime-kit-family.md +++ b/goals/G-103-runtime-kit-family.md @@ -57,18 +57,49 @@ strategy. G-006: punkbin download consent. G-097: runtime.cmd -> punk-runtime rename interplay. RUNTIME NAMING (user 2026-07-21): piperepl-patched runtime executables must carry -'punk' in the name so patched and unpatched are never confusable - e.g -tclsh905punk.exe. The suite's current tclsh90spr/tclsh90sprzip are INTERNAL WORKING -NAMES pending this goal's scheme. Open design questions the user flagged, to -resolve here: how to encode BOTH the tcl patchlevel and a punk version (which punk -version - the patch revision? the punkshell release the kit family ships with?), -and which separators are appropriate. Existing-namespace considerations for that -decision: kit exes use bare punk+patchlevel (punk905.exe), runtimes historically -tclsh+nodotversion+flags (tclsh90s) or tclsh+patchlevel (tclsh905.exe), and bin -UTILITIES use the punk- hyphen prefix (bin/AGENTS.md policy) - three deliberate -sub-namespaces; windows-filename-safe separators only; and the G-103 metadata -records can carry the AUTHORITATIVE versions, letting filenames stay -human-distinguishing rather than fully version-encoded. +'punk' in the name so patched and unpatched are never confusable. The suite's +tclsh90spr/tclsh90sprzip stay recipe-INTERNAL working names - this goal's +kit-assembly steps emit the public names below at the boundary. + +NAMING DECISION (user-approved 2026-07-21; resolves the acceptance's +tcl-patchlevel / punk-version / separator questions). Principle: two naming +tiers, mapped by tooling - punkbin stores immutable fully-qualified ARTIFACT +names; projects and fingers consume short stable WORKING names; 'runtime use' +(punk-runtime after G-097) and mapvfs are the mapping. + +- RUNTIME ARTIFACT names (punkbin tier; rarely typed, verbosity fine): + tclsh[-punk[-bi]]-r(.exe) - e.g tclsh9.0.5-r1.exe + (plain member), tclsh9.0.5-punk-r1.exe, tclsh9.0.5-punk-bi-r1.exe. Dotted + patchlevels are REQUIRED (tclsh1005 is unreadable/ambiguous once Tcl 10 and + 9.0.10-class patchlevels exist). -r is an ASSEMBLY REVISION per + (patchlevel, variant), ALWAYS present for uniform parsing, incremented on any + republish of the same patchlevel (battery bump, patch fix, toolchain bump) - + artifacts are immutable and coexist for rollback. NO punkshell version and NO + patch revision in runtime names: runtimes carry no punkshell modules, and the + metadata record is authoritative for patch revision, component versions, + source pins and toolchain. +- RUNTIME WORKING names (what mapvfs references; bin/runtime//): the + artifact name minus -r - e.g tclsh9.0.5-punk.exe; 'runtime use' + materializes a chosen -rN artifact into it, so republishing never churns + consumers. +- KIT names flip the release axis to the PUNKSHELL version (the kit's payload): + typable WORKING names are major-only - punk9, punk8, variant punk9bi - + precision stamped in-file/metadata; published/archived KIT ARTIFACTS are + punk-(.exe) - e.g punk9-0.5.0.exe, prerelease + punk9-0.5.0b2.exe. Two punk9 releases may differ in tcl patchlevel - that is + metadata's job. The dev-matrix style (punk905, punk902z - tcl patchlevel + encoded, owner-chosen via mapvfs, typed constantly while comparing runtimes) + remains a recognized third style; kit conventions here are documented + DEFAULTS, not mandates - kit exe naming stays under project-owner control. +- Separators: hyphens throughout (safe here - these names neither start with + punk- nor live on PATH, so the bin-utility prefix convention is not in play); + '+' banned (hostile in raw punkbin URLs); '_' reserved as fallback. Filenames + IDENTIFY; ORDERING comes from runtime list parsing metadata (lexicographic + sort misorders tclsh10.* before tclsh9.* regardless of dots) - per-series + punkbin subdirs remain a later option. + +(The acceptance's 'e.g tclsh905punk.exe' example predates this decision; the +decided punk-marked shape is tclsh-punk....) ## Notes