punkshell/goals/G-148-vendor-upstream-discovery.md

G-148 Vendor upstream discovery: read-only ref/tag listing and pin-drift report for declared packages

Status: proposed Scope: src/modules/punk/mix/ (vendor-sync command surface - discovery beside the G-065 sync); punkproject.toml or sibling vendor manifest (G-065 declaration schema as consumed); src/tests/modules/punk/mix/ (discovery testsuite with local fixture upstreams) Goal: for packages declared in the G-065 vendor manifest, a read-only discovery command answers "what refs/tags exist upstream?" and reports pin drift (declared pin vs newest matching upstream ref) - so pin selection at declaration time and pin-bump decisions later are informed by the upstream's actual version surface, without retrieving payloads or changing any state. Acceptance: the discovery command (home settled in the work, beside the G-065 sync surface) lists upstream tags/refs for a named declared package or all declared packages without materializing anything; a pin-drift report classifies each declared package as up-to-date / behind (naming the newest matching ref) / unpinned-resolves-to (what an unpinned declaration would resolve to today); git upstreams are supported via ls-remote, with fossil and http-archive upstream kinds supported or recorded as deferred with rationale; the command is strictly read-only - no materialization, no manifest edits, no provenance records written; tests run against local fixture repositories with no network access; the relationship to G-065 (adjunct surface landing after its manifest schema) is recorded.

Context

Drafted 2026-08-01 from the Tin package-manager comparison: Tin's tin autoadd discovers versions by querying git tags (git ls-remote --tags) and auto-registers every match. The punkshell-shaped adoption keeps declarations hand-authored (the G-065 manifest is a deliberate declaration, not an auto-populated database) and uses discovery only to INFORM pins: what to pin at declaration time, and when a declared pin has drifted behind upstream. Discovery of a newer upstream ref never triggers a sync - the bump is a manifest edit followed by the G-065 sync, preserving the declaration-driven model.

Notes

• Related: G-065 - the parent surface; this goal is its read-only adjunct and lands after the manifest schema exists (dependency direction: this goal consumes G-065's declarations).
• Related: G-063 - a pin bump informed by this report is the natural re-trigger point for license-verification provenance on the new version.
• Related: G-047 - punkproject.toml schema co-tenant if the G-065 manifest lives there (no new fields expected; recorded to keep the schemas collision-free).
• Related: G-026 - local-pull provenance sibling; discovery here covers EXTERNAL upstreams, which G-026 deliberately does not.
• Related: G-147 - the libfetch revision-check sibling drafted from the same Tin comparison; both are read-only reports that inform a deliberate declaration edit (the G-065 vendor manifest here, libpackages.toml there) rather than acting on what they find.
• Overlap survey 2026-08-01 (drafting): goals_xref paths over punkproject.toml, src/modules/punk/mix/, src/vendorlib/, src/vendormodules/ - surfaced G-065 (parent, carried as Related), G-063/G-067/G-004 (vendor-area co-tenants, domain-distinct), G-047/G-137 (punkproject.toml co-tenants), G-026 (include_modules.config adjacency); no contract-level conflicts found.