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.

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 defaults to a typed actionable failure.
• 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