Control Plane Baseline Resolution

The control plane is the sole online authority for stable and exact baseline selection. Request intent determines whether a typed remote-access failure may use the independently verified bundled baseline.

Trigger

An operator runs a CLI command that needs a scaffold baseline.

Actors

• Harness operator
• apps/cli
• packages/contract
• apps/api
• Verified bundled baseline

Steps

1. Resolve --baseline bundled and DP_BASELINE=bundled immediately from verified bundled bytes.
2. Resolve an explicit DP_BASELINE_URL=file:///absolute/path before remote authority and validate its identity and compatibility.
3. Resolve implicit default-stable, explicit stable, and exact versions once through the typed control-plane authority. hi check converts a missing selector to explicit stable.
4. Download, verify, extract, and cache only the selected immutable archive. Stable and exact hi check requests always refresh metadata and archive bytes; other commands may reuse a verified cached artifact.
5. Treat inventory and selected-manifest network failures and HTTP 408, 429, 500, 502, 503, or 504 as typed availability. Inventory 401, 403, or 404, a missing selected manifest 404, and every other non-transient status are typed integrity failures. Selected-manifest initial and redirect URLs must be absolute HTTP(S). Every hop is followed manually with a 20-redirect bound; relative, malformed, or unsupported URL evidence is integrity.
6. On fallback-eligible availability failure, return verified bundled bytes only for implicit default-stable. Eligibility is derived from preserved transport, timeout, selected archive transport, the archive endpoint's declared unavailable HTTP 503, or a positively typed authority-unconfigured, network, or unavailable-status cause rather than a public reason or failure message. The CLI control-plane boundary owns Effect HTTP recognition and records a typed transport discriminator on ControlPlaneRequestFailure; baseline resolution consumes that fact without translating unstable HTTP errors.
7. Keep explicit stable and exact versions fail-closed on remote-access failure. The read-only check boundary maps classified authority availability and published-inventory 404 to availability.status: "unavailable" with no drift; integrity failures remain fatal.
8. Keep every request fail-closed on integrity or authority failure, including malformed successful responses, malformed JSON or pagination, untyped unavailable responses, relative, invalid, or unsupported initial or redirected archive URLs, stale or incomplete inventory, pagination cycles, cross-origin traversal, safety-limit exhaustion, disagreement, substitution, compatibility failure, manifest, archive, cache, or content digest failure, and typed archive integrity 422, authority 409, or not-found 404.
9. Treat an absent cache target as a miss and existing material without baseline.json as an integrity failure. If corrupt or incomplete cache state is observed and its repair download is unavailable, return the preserved cache-integrity failure instead of bundled bytes.
10. Preserve { channel: "stable" } and report retrieval: "fallback" in implicit fallback summaries while retaining bundled source/provenance and verified bytes. Explicit bundled remains { channel: "bundled" } with retrieval: "available".

Outcome

The CLI preserves one online baseline authority while retaining a narrow, verified availability fallback for commands that did not explicitly select stable or an exact version. Ordinary hi check always uses fresh remote stable authority and never consumes that fallback.

Closeout Signal

The implementation is healthy when tests prove the full request/failure matrix: implicit default-stable falls back only on preserved transport or availability causes; plain hi check requests explicit stable and downloads fresh bytes on repeated runs; explicit stable and exact versions fail closed; explicit bundled avoids authority I/O; malformed or incomplete authority evidence, including invalid archive URLs, fails closed; and cache-integrity evidence survives a failed repair.