From b887a613495204b5a265d0ccf81a4a8a4ba9a060 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 26 Jul 2026 03:14:58 +1000 Subject: [PATCH] G-123 drafted (user-approved): third-party runtime tiers via artifact servers Index entry + detail file with the two user-directed amendments over the presented draft: consent keyed to SERVER TRUST (trusted set defaults to the canonical punkbin origin - no new prompts in existing flows incl. the unattended tclsfe-x64 constraint fetch; untrusted/alternative servers gate with a G-006-pattern acknowledgement surfacing the provenance class), and retroactive schema-v2 provenance sidecars for the existing punkbin third-party artifacts (additive only - bytes, bare pre-family names, sha1sums.txt authority unchanged). Signing deliberately deferred per user ("down the track") with the minisign anticipation noted. Depends on G-122; Related G-006/G-067/G-105/G-101; extends archived G-103/G-119 machinery under a G-117 schema-v1 -> v2 bump. G-122's follow-on note now cites G-123 by id. Claude-Session: https://claude.ai/code/session_01Jz7wkUsknJzyuJ3tgMaL2t Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 4 ++ goals/G-122-host-target-platform-split.md | 7 +- goals/G-123-thirdparty-runtime-tiers.md | 88 +++++++++++++++++++++++ 3 files changed, 95 insertions(+), 4 deletions(-) create mode 100644 goals/G-123-thirdparty-runtime-tiers.md diff --git a/GOALS.md b/GOALS.md index de376545..d20d5d23 100644 --- a/GOALS.md +++ b/GOALS.md @@ -397,3 +397,7 @@ Detail: goals/G-116-suite-built-tcltls.md Scope: src/make.tcl (target-platform derivation; store folder, exe suffixing, kit naming, presence checks and process-sweep tooling keyed by target; platform-canon inline copy; zipfs-less zip-type assembly fallback); src/modules/punk/platform-999999.0a1.0.tm (stable canon tags for cygwin-family hosts, help platforms doc); src/runtime/mapvfs.config (per-entry target platform via minimal compatible extension - format ownership coordinated with G-024); bin/runtime// store tiers (as consumed; fixture tier for tests); src/tests/shell/testsuites/punkexe/ (characterization) Detail: goals/G-122-host-target-platform-split.md +### G-123 [proposed] Third-party runtime tiers via artifact servers: per-target publish, list, fetch, materialize +Scope: src/scriptapps/punk-runtime.ps1 + src/scriptapps/bin/punk-runtime.bash + punk-runtime_wrap.toml (named-tier operations in both payloads; bin/punk-runtime.cmd via the established re-wrap channel); punkbin artifact repo (external, c:/repo/jn/punkbin - per-tier layout, defaults, sha1sums, schema-v2 provenance sidecars incl. retroactive backfill, layout docs); src/buildsuites/suite_tcl90/ (family_artifacts.tcl schema-v2 emission for suite-built artifacts); alternative-server override + trusted-server set (PUNKBIN_URL pattern; consent surface coordinated with G-006); src/tests/shell/testsuites/binscripts/ (fixture-server characterization); bin/runtime// stores (as materialization targets) +Detail: goals/G-123-thirdparty-runtime-tiers.md + diff --git a/goals/G-122-host-target-platform-split.md b/goals/G-122-host-target-platform-split.md index 6f782e89..1d958cde 100644 --- a/goals/G-122-host-target-platform-split.md +++ b/goals/G-122-host-target-platform-split.md @@ -97,9 +97,8 @@ machinery already has zipfs-less fallbacks. override rides the same entry shape). - Related: G-023 - kit naming schemes; target-keyed naming must not collide with its version-named binaries direction. -- Follow-on candidate (flagged, drafted separately for approval): third-party - runtime tier publication/fetch via punkbin or alternative servers - (punk-runtime payloads, server platform manifests, consent gating per - G-006, artifact-channel kinship with G-067). +- Follow-on: G-123 (drafted 2026-07-26, user-approved) - third-party runtime + tier publication/fetch via punkbin or alternative servers, with schema-v2 + provenance labeling and server-trust-keyed consent. - Out of scope: msys pty raw-mode console/repl behaviour - the cursor-row-1 field finding of 2026-07-26 is recorded in G-013's Notes. diff --git a/goals/G-123-thirdparty-runtime-tiers.md b/goals/G-123-thirdparty-runtime-tiers.md new file mode 100644 index 00000000..493b4823 --- /dev/null +++ b/goals/G-123-thirdparty-runtime-tiers.md @@ -0,0 +1,88 @@ +# G-123 Third-party runtime tiers via artifact servers: per-target publish, list, fetch, materialize + +Status: proposed +Scope: src/scriptapps/punk-runtime.ps1 + src/scriptapps/bin/punk-runtime.bash + punk-runtime_wrap.toml (named-tier operations in both payloads; bin/punk-runtime.cmd via the established re-wrap channel); punkbin artifact repo (external, c:/repo/jn/punkbin - per-tier layout, defaults, sha1sums, schema-v2 provenance sidecars incl. retroactive backfill, layout docs); src/buildsuites/suite_tcl90/ (family_artifacts.tcl schema-v2 emission for suite-built artifacts); alternative-server override + trusted-server set (PUNKBIN_URL pattern; consent surface coordinated with G-006); src/tests/shell/testsuites/binscripts/ (fixture-server characterization); bin/runtime// stores (as materialization targets) +Goal: runtime artifacts for tiers beyond the host-native platform - third-party-built personalities (e.g an msys2-packaged mingw64-x86_64 tclsh) and cross-personality consumers (a linux tier used from FreeBSD) - are first-class on punkbin or an alternative artifact server: punk-runtime lists/fetches/uses artifacts for an explicitly named target tier from both payloads, materializing sha1-verified -r artifacts + toml metadata into bin/runtime//, with build-origin provenance (suite-built vs third-party) labeled on every artifact, consent keyed to server trust rather than artifact origin, and the G-122 chain completed from server artifact to a bakeable mapping entry. +Acceptance: against a fixture artifact server (httpfixture precedent) carrying a non-native tier, punk-runtime supports an explicit target-tier argument on list/use (and the fetch path) in BOTH payloads - ps1 driven as the committed bin/punk-runtime.cmd under cmd.exe, bash driven under msys bash - with row/verdict parity and the established single-line row vocabulary scoped to the named tier; 'use' materializes the tier's working copy under bin/runtime// with sha1 verification and beside-toml metadata, and freshness verdicts compare against that tier's server default; artifact-toml schema v2 provenance distinguishes suite-built from third-party (class/builder/source_url/upstream_ref/retrieved), with third-party rows carrying a compact origin tag in list -remote's sparse notes column and full fields in the per-name detail view while suite-built rows are unchanged; existing punkbin third-party artifacts (e.g win32-x86_64/tclsfe-x64.exe, tclkit86bi.exe) gain retroactive schema-v2 sidecars additively (artifact bytes, bare pre-family names and sha1sums.txt authority unchanged; toml-less entries continue to degrade as no-basis rows); consent is keyed to SERVER TRUST - fetches from the trusted set (default: the canonical punkbin origin) prompt nothing, leaving existing unattended flows unchanged, while the first fetch from an untrusted/alternative server gates on an explicit acknowledgement (G-006's mechanism when landed, else an interim documented flag) that surfaces the artifact's provenance class; an end-to-end fixture demonstration wires a fetched fixture-tier runtime through a G-122 non-default-target mapping entry to a bakelist row showing the runtime present; the punkbin layout docs record the per-tier + schema-v2 extension and existing native-tier clients are unaffected (existing binscripts tests pass unchanged). + +## Context + +Direction (user, 2026-07-26, recorded at G-122's drafting): runtime tiers may be +third-party built - e.g an msys2-packaged tclsh - and served from punkbin or a +punkbin-alternative artifact server, even if such platforms are never zig +buildsuite targets. G-122 owns REPRESENTATION (stable canon tag, store tier, +non-default-target mapping entry); this goal owns SOURCING (publish, list, +fetch, materialize). + +Current punkbin state (surveyed 2026-07-26): the suite-built family artifacts +carry rich G-117 schema-v1 sidecars ([artifact] facts including packager - with +minisign sidecars already anticipated in its comment - plus [provenance] +suite/toolchain/checkout hashes and [tests] gate results), while the +third-party binaries beside them (win32-x86_64: tclsfe-x64.exe = +apnadkarni/tcl-sfe release, tclkit86bi.exe, tclkit902.exe, tclsh901k/t.exe, +tclsh902z*.exe - the last looking locally built pre-suite) have NO sidecars at +all, only sha1sums.txt coverage. Nothing machine-readable distinguishes build +origin; this goal fills that gap with the same schema rather than a parallel +mechanism. + +Consent decision (user, 2026-07-26): keyed to SERVER TRUST, not artifact +origin - curating an artifact onto one's own punkbin is the consent act, so +labels are transparency and prompts appear only for servers outside the +trusted set. No new prompts may appear in existing flows, e.g the unattended +constraint fetch of tclsfe-x64 for the static-runtime suite (G-058, achieved - +see goals/archive/G-058-static-runtime-packages.md). + +## Approach + +- Extend, don't fork, the archived machinery: the -r immutable artifact + tier + working-copy materialization + platforms/defaults server manifests + (G-103, achieved - see goals/archive/G-103-runtime-kit-family.md) and the + freshness verdict, httpfixture test harness and row vocabulary (G-119, + achieved - see goals/archive/G-119-runtime-active-freshness.md). +- Explicit target-tier argument on list/use/fetch in both payloads; ps1+bash + single-line row parity and restrained width per the established listing + conventions; third-party rows get a compact origin tag in the sparse notes + column of list -remote, full provenance in per-name detail; suite-built + rows stay quiet (expected state). +- Artifact-toml schema v2 (successor to the G-117 schema v1, achieved - see + goals/archive/G-117-self-describing-runtimes.md; the schema field exists + for this): [provenance] class = suite-built|third-party|local, builder, + source_url, upstream_ref, retrieved. The builder-vs-packager split is + deliberate: builder compiled the binary, packager (existing field) curated + it onto the server. Emission: family_artifacts.tcl for suite artifacts; + authored sidecars for third-party ingests; retroactive backfill for the + existing third-party items is ADDITIVE ONLY (artifact bytes, bare + pre-family names and the sha1sums.txt integrity authority untouched). +- Trusted-server set: the canonical punkbin origin trusted by default; the + configuration surface (list membership, acknowledgement recording) is + settled in the work, coordinated with G-006's consent pattern. + +## Alternatives considered + +- Artifact-origin-keyed consent - rejected (user decision 2026-07-26): it + adds prompts to already-curated flows; server-set membership is the real + trust boundary today. +- Signing/attestation in this goal - deferred deliberately (user: "signing + for down the track"): minisign sidecars are already anticipated by the + schema's packager comment and become the natural successor goal when + third-party tiers or alternative servers are routine. Until then sha1sums + remain transport-integrity only, and the docs say so plainly. +- A separate server namespace for third-party artifacts - rejected: + provenance belongs on the artifact record, not the URL layout; mirrors + would lose it. + +## Notes + +- Depends on: G-122 (canon tags, target-keyed stores, non-default-target + mapping entries - the end-to-end acceptance item consumes its fixture-tier + support). +- Related: G-006 - consent-gated binary downloads; the untrusted-server gate + here is a concrete consumer (interim documented flag if this lands first). +- Related: G-067 - artifact-channel kinship (module tier vs runtime tier); + G-116 already points punkbin publication at the G-067 library class. +- Related: G-105 - first-party cross-target tiers arrive via zig -target and + ride the same server surfaces this goal extends. +- Related: G-101 - a served 8.6-container tier would ride this mechanism. +- Signing deferred by user decision 2026-07-26 ("server trust ... with + signing for down the track") - flag a dedicated signing/attestation goal + when the first genuinely external tier or server appears.