3.7 KiB
G-147 libfetch revision check: read-only report of newer server revisions for declared artifacts
Status: proposed Scope: src/make.tcl (libfetch check/report surface); src/runtime/libpackages.toml (declared revisions as input); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization); bin/AGENTS.md + src/runtime/AGENTS.md (report documentation) Goal: 'make.tcl libfetch' answers "is there a newer revision of what I have declared?" as a first-class read-only report - comparing each declared artifact's pinned revision against the server's per-tier sha1sums.txt (and the current-group listing where a G-142 manifest exists) - so revision adoption stays a deliberate libpackages.toml edit informed by the report, never a client-side auto-upgrade. Acceptance: a libfetch check mode (flag or subcommand settled in the work) reports per declared artifact: declared revision, newest revision present on the server, and status vocabulary covering at least up-to-date / newer-available / absent-from-listing (the G-142 drift case) / carved-out (a newer revision exists but sits in a hidden G-142 group such as vulnerable or archive - reported distinctly, never silently recommended); the mode is read-only - it fetches only the server ledger/listing files, writes nothing to bin/packages, and edits no declaration; output has a machine-parsable form (the G-064 direction); behaviour is characterized in maketcllibfetch.test through the existing PUNK_LIBFETCH_CONFIG / fixture seams; vocabulary coordination with G-141 and G-142 is recorded (whichever of the three lands second adopts the landed one's terms).
Context
Drafted 2026-08-01 from the Tin package-manager comparison (Tin's tin check /
tin upgrade make "is there a newer one?" a first-class client question).
The punkbin-shaped answer is report-only: punkbin artifacts are immutable
-r revisions and adoption is a deliberate declaration bump (the
deliberate-publish/deliberate-adopt discipline of G-138, archived), so Tin's
auto-upgrade flow has no punkbin analogue - the check informs the edit, the
edit stays manual. Consent keying is inherited unchanged from the fetch path
(canonical origin queries gate nothing; other origins need -trust-server).
Notes
- Related: G-141 - libfetch target selection; the check consumes the same declared set and derivation reporting (whichever lands second adopts the other's vocabulary).
- Related: G-142 - listing manifests; the current/vulnerable/archive group semantics are what the check's carved-out status reads. Its libfetch-side "declared artifact absent from the server's current listing" warning is this report's absent-from-listing case, absorbed into the wider report.
- Related: G-006 - absorbs the consent surface when it lands; the check must survive that absorption.
- Related: G-067 - the future .tm module artifact channel inherits this check idiom for module artifacts.
- Related: G-139 (archived - goals/archive/G-139-punkbin-library-consumption.md) - created libfetch; this goal adds the revision-freshness dimension.
- Related: G-148 - the vendor-upstream sibling drafted from the same Tin comparison; both are read-only reports that inform a deliberate declaration edit (libpackages.toml here, the G-065 vendor manifest there) rather than acting on what they find.
- Overlap survey 2026-08-01 (drafting): goals_xref paths over src/make.tcl, src/runtime/libpackages.toml, bin/packages/, src/tests/shell/testsuites/punkexe/maketcllibfetch.test - strongest live intersections G-141 (direct sibling), G-005/G-006/G-023/G-101/G-131 (sibling-path adjacency only); G-142 relation from the libfetch coordination clause in its contract; no contract-level conflicts found.