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