Spec: Verified Baseline Authority

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

Context

Baseline resolution currently spans an authoritative control plane and multiple possible retrieval sources. Operators, consumers, and maintainers need every request to resolve to one immutable verified artifact identity without allowing availability, stale metadata, or storage-specific behavior to redefine the requested version. This epic unifies IP-343 and IP-344 into one authority and identity contract: the API selects moving channels, while retrieval sources only fetch and verify the selected artifact.

Story Coverage

• IP-343: return one neutral record containing requested identity, exact resolved version, digest, provenance, compatibility, and retrieval status across all supported sources.
• IP-344: make the control-plane API the only online moving-channel authority, enforce newest-published-is-stable, and fail truthfully on unavailability or authority disagreement.

2026-07-27 Authority-Audit Amendment

This amendment supersedes earlier IP-323 wording where it conflicts with the accepted fallback matrix. The control plane remains the sole online authority for stable; verified bundled bytes are an availability fallback only for an implicit default-stable request after a typed remote-access failure.

Fallback-eligible availability is derived from a positive typed cause, not from a presentation reason or message blacklist. It includes authority transport failure, timeout, a typed authority-unconfigured, network, or unavailable-status response, archive transport failure, and the archive endpoint's declared unavailable HTTP 503. Typed archive BaselineIntegrityFailure (422), BaselineAuthorityFailure (409), and BaselineNotFound (404) remain fail-closed. Inventory and selected-manifest network failures and transient HTTP 408, 429, 500, 502, 503, or 504 are typed availability; inventory 401, 403, or 404, missing manifest 404, and every other non-transient status are typed integrity. Selected-manifest initial and redirect URLs must be absolute HTTP(S); every redirect hop is manual and bounded to 20, and relative, malformed, or unsupported URL evidence is integrity. Malformed JSON, malformed pagination, malformed successful responses, pagination cycles, cross-origin inventory traversal, inventory safety-limit exhaustion, stale or incomplete inventory, relative, invalid, or unsupported initial or redirected archive URLs, authority disagreement, version substitution, compatibility failure, and manifest, archive, cache, or content digest failure never authorize fallback. Existing incomplete cache material is an integrity failure. Once cache corruption or incompleteness is observed, a failed repair download preserves that integrity failure and remains fail-closed. A fallback summary preserves the implicit stable request and reports retrieval: fallback while retaining bundled source, provenance, and verified bytes; explicit bundled remains distinct.

Non-Goals

• Letting a storage or retrieval adapter choose a close-enough artifact or substitute a different version.
• Allowing GitHub, cache state, bundled state, or retrieval availability to define stable.
• Building a new offline cache or bundled fallback.
• Silently downgrading when authority or retrieval fails.
• Creating source-specific result models that hide the requested or resolved identity.
• Inventing exact protocol symbols, storage mechanisms, or implementation file boundaries in this spec.

Acceptance Criteria

Verified artifact record

• Every baseline resolution returns the requested channel or version, exact immutable resolved version, digest, source and provenance, compatibility, and retrieval, cache, or fallback status in one neutral record.
• Authority, version selection, and fallback policy belong to the baseline capability.
• API, published-release, cache, and bundled adapters only fetch and verify resolved bytes and metadata.
• A retrieval adapter cannot select, substitute, or silently downgrade to another version.
• An explicit immutable version request remains exact.

Moving-channel authority

• The control-plane API is the sole online authority for moving baseline channels.
• stable resolves to the newest published baseline, and no newer non-stable baseline exists ahead of it.
• The authoritative response includes the exact version, digest, and compatibility.
• Every retrieval source must match the authoritative identity before its artifact is accepted.
• Authority disagreement or stale control-plane metadata produces a typed authority or integrity failure.
• Control-plane API unavailability is classified as a typed actionable remote-access failure before the request policy either returns it or applies the implicit default-stable bundled fallback.
• No new offline fallback is required.
• If an existing cache, bundled path, or explicit bundled request is retained, it accepts only the exact artifact after verifying identity, provenance, digest, and compatibility.
• Neither GitHub nor fallback behavior can redefine stable or authorize a silent downgrade.

Constraints

• IP-343 precedes IP-344: the common verified identity contract must exist before moving-channel authority can be enforced consistently across retrieval sources.
• IP-330 characterization evidence must exist before baseline public behavior changes.
• Protocol-visible identity and failures must stay neutral across API and CLI consumers.
• Retrieval status may describe how authoritative bytes were obtained; it cannot alter the selected identity.
• Delivery participates in the coordinated Effect v4 cutover on one unmerged and undeployed branch. No per-epic merge to main, dual authority, compatibility shim, or staged deployment may ship.

Dependency Readiness

• Status: No Stack Required
• Dependency: IP-330
• Evidence: Draft PR #76 and apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record accepted IP-330 characterization evidence and IP-330 is Done.
• Reason: IP-330 readiness is proven on the coordinated delivery PR. IP-343 still precedes IP-344 as internal execution order, not PR stack topology.

Review Status

• Spec status: Implemented and ingested; IP-343 and IP-344 are complete on the Effect v4 convergence branch.
• Implementation and review: Passed against the accepted Q52-Q54 decisions, complete contract/API/CLI verification, and private/internal docs evidence with no remaining IP-323 finding.
• Human approval state: delivery complete; the coordinated branch remains unmerged and undeployed under the IP-324 cutover gate.
• Open questions: none within IP-323; IP-324 owns the remaining repository and consumer closeout.

Decision Log