IP-323 Verified Baseline Authority Implementation Notes

Implemented Contract

packages/contract/src/baseline.ts now exposes one source-neutral identity for resolution and artifact responses: requested { channel, version? }, exact resolved version, digest, authority source, provenance, CLI compatibility, and retrieval status. Exact-version and archive-digest consistency are schema constraints. Typed baseline failures map authority disagreement to 409, integrity failure to 422, and unavailability to 503.

The accepted public OpenAPI semantics include the optional exact-version query and all three failures on both baseline endpoints. IP-320's deliberate generator-normalization and protocol-only package boundaries remain intact.

API Authority

apps/api/src/baseline-release-inventory.ts reads the complete GitHub-compatible release inventory with same-origin pagination and redirects, cycle detection, and a 100-page ceiling. Independent immutable ID and version maps reject the same ID mapped to another version and the same version mapped to another ID, digest, or publication time. Stable selection sorts the canonical ID map by publication time, with opaque identity as the deterministic tie-breaker. Conflicting immutable metadata, an incomplete inventory, or a newer non-stable baseline fails typed. Network and transient HTTP 408, 429, 500, 502, 503, or 504 remain availability; 401, 403, 404, and every other non-transient status are integrity.

apps/api/src/baseline-registry.ts validates configured version, digest, release provenance, compatibility, published identity, and an API-owned public origin before returning resolution or artifact metadata. API-owned artifact URLs carry the immutable selected version. Downloads re-resolve that exact version, buffer the configured source, and verify its SHA-256 digest before returning bytes. Mismatch is typed 422; retrieval failure is typed 503. The API no longer exposes a mutable source URL or falls back to a private GitHub asset.

Selected published manifest retrieval classifies network failures and transient HTTP 408, 429, 500, 502, 503, or 504 as typed availability. A missing selected manifest 404 and every other non-transient status are invalid authority evidence and become typed integrity failure. Initial and redirect targets are parsed as absolute HTTP(S) URLs before fetch. Every hop uses manual redirect handling with a 20-redirect bound; relative, malformed, or unsupported URL evidence is integrity.

CLI Retrieval

apps/cli/src/baseline/resolve.ts treats the control plane as the sole online authority. stable and exact versions resolve there once. A verified cache entry must match both the stored archive digest and materialized content digest. A mismatch deletes the bad cache entry and downloads the selected version-bound artifact again.

Bundled content has a generated identity and runtime content-digest check. It is available for an explicit bundled request and as the narrow availability fallback for implicit default-stable. update, check, tools, and scaffold accept stable, bundled, or an exact version and preserve the normalized request through resolution.

2026-07-27 Authority-Audit Resolution

The later accepted operator contract supersedes earlier notes that described all authority failures as fail-closed. The resolver applies this exact matrix:

• implicit default-stable falls back to verified bundled bytes only for typed remote-access, including authority request failure, timeout, archive transport failure, and the archive endpoint's declared unavailable HTTP 503;
• explicit stable and exact versions preserve their typed failure;
• explicit bundled verifies and returns bundled bytes without authority I/O;
• integrity and authority failures never fall back, including stale or incomplete inventory, disagreement, substitution, compatibility failure, and manifest, archive, cache, or content digest failure.

Fallback policy no longer trusts the lossy public reason or an unavailable-message blacklist. The shared BaselineUnavailable contract requires a positive authority-unconfigured, network, or unavailable-status discriminator. The API maps malformed inventory JSON, malformed pagination, cycles, both inventory cross-origin conditions, and the 100-page safety limit to typed integrity failure. Untyped unavailable responses therefore fail schema decoding and remain fail-closed. True HTTP transport errors, timeouts, typed unavailable responses, archive transport failures, and the archive endpoint's declared unavailable 503 remain eligible only for implicit stable. Archive responses decode the declared baseline failure contract: typed integrity 422, authority 409, and not-found 404 fail closed. Other statuses and relative, invalid, or unsupported initial or redirected archive URLs remain fail-closed. Archive redirects are followed manually through validated absolute HTTP or HTTPS targets with a 20-redirect bound.

Implicit fallback now overlays the original { channel: "stable" } request and retrieval: "fallback" onto the verified bundled summary while preserving bundled source, provenance, digest, and bytes. Explicit bundled retains { channel: "bundled" } and retrieval: "available".

The control-plane client owns Effect HTTP recognition and records ControlPlaneRequestFailure.transport; baseline resolution consumes that discriminator without importing or interpreting unstable HTTP errors.

Cache lookup now returns observed integrity failure alongside a cache miss. A repair download may replace the corrupt entry only after full verification; if that download is unavailable, the original cache integrity failure wins and suppresses bundled fallback. An absent target directory is a cache miss; an existing target without baseline.json is incomplete cache material and preserves the same fail-closed integrity behavior.

Authority-audit verification passed the resolver suite 33/33, the serial full CLI suite 852/852, CLI typecheck, scoped lint and format, the routed wiki contract 5/5, byte-identical spec mirrors, and git diff --check.

The cause-classification and cache-repair follow-up passed the resolver suite 39/39, the serial full CLI suite 858/858, CLI typecheck, scoped lint and format, the routed wiki contract, byte-identical spec mirrors, and git diff --check.

The archive-URL and incomplete-cache follow-up passed the resolver suite 44/44, the serial full CLI suite 863/863, CLI typecheck, scoped lint and format, the routed wiki contract, byte-identical spec mirrors, and git diff --check.

The inventory-message and archive-redirect follow-up passed the resolver suite 46/46, the serial full CLI suite 865/865, CLI typecheck, scoped lint and format, the routed wiki contract, byte-identical spec mirrors, and git diff --check.

The typed-availability and fallback-summary follow-up passed the resolver suite 47/47, the serial full CLI suite 866/866, the API suite 197/197, the contract suite 27/27, all three typechecks and scoped checks, the routed wiki contract, byte-identical spec mirrors, and git diff --check.

The archive-status follow-up passed the resolver suite 51/51, the serial full CLI suite 870/870, the API suite 197/197, the contract suite 27/27, and the wiki suite 11/11. CLI, API, contract, and wiki typechecks and checks passed; canonical/routed mirrors and git diff --check remained clean.

The selected-manifest status follow-up passed the registry suite 14/14, the full API suite 199/199, the serial full CLI suite 870/870, the contract suite 27/27, and the wiki suite 11/11. All workspace typechecks and checks, canonical/routed mirrors, formatting, and git diff --check passed.

The inventory-status and manifest-URL follow-up passed the inventory suite 27/27, registry suite 18/18, full API suite 212/212, serial CLI suite 870/870, contract suite 27/27, and wiki suite 11/11. All workspace typechecks and checks, canonical/routed mirrors, formatting, and git diff --check passed.

The redirect-chain follow-up passed the registry suite 21/21, resolver suite 54/54, full API suite 215/215, serial CLI suite 873/873, contract suite 27/27, and wiki suite 11/11. All workspace typechecks and checks, canonical/routed mirrors, formatting, and git diff --check passed.

The transport-boundary follow-up passed the exact Effect v4 validator 96/96, focused control-plane/resolver suites 58/58, full API suite 215/215, serial CLI suite 873/873, contract suite 27/27, and wiki suite 11/11. All workspace typechecks and checks, canonical/routed mirrors, formatting, and git diff --check passed.

Verification Evidence

This follow-up repaired exact historical authority. Inventory retains verified manifest/archive asset URLs and digests; exact requests select their matching stable release, fetch only its manifest, and verify schema version, manifest digest, version, tag, and archive digest. Current stable still validates deployment configuration. A verified schema-v1 release uses deployment compatibility only for the currently configured stable or matching exact version; historical schema-v1 releases fail typed integrity until backfilled. Schema-v2 releases use their own compatibility.

Private release inventory retains GitHub asset API URLs. Manifest retrieval authenticates only strict https://api.github.com/.../releases/assets/... requests, follows redirects manually, and never forwards authorization to the signed asset host. Stable configured retrieval URLs may differ from published locations because URLs are not immutable identity fields.

RED evidence:

• bunx vitest run src/baseline-release-inventory.test.ts: older exact resolved newest; missing exact returned success.
• bunx vitest run src/baseline-registry.test.ts: older v2 and legacy-v1 cases returned configured-authority failures; the compatibility bridge RED then showed current v1 stable and exact requests failing integrity.
• bunx vitest run src/baseline/baseline-release-scripts.test.ts: three failures; emitted schema v1 without compatibility and publication reached dirty-worktree validation without requiring BASELINE_CLI_VERSION_RANGE.

GREEN evidence:

• API focused suites: 57/57 tests passed, including current v1 stable/exact bridging, historical v1 integrity failure, and historical v2 resolution.

• CLI release-script suite: 3/3 passed; both metadata files emit v2 compatibility, local build defaults to the exact package version, and publication requires an explicit range.

• Scaffold suite: 49/49 passed with explicit public schema-v1 and schema-v2 contracts.

• Contract: bun run --filter @punks/contract test — 4 files, 26/26 tests passed; contract typecheck passed.

• API: full API suite — 16 files, 101/101 tests passed; API typecheck passed.

• CLI: full CLI suite — 49 files, 494/494 tests passed; CLI typecheck passed.

• Scaffold: full scaffold suite — 5 files, 48/48 tests passed; scaffold typecheck passed.

• Packaged public output: 9/9 tests passed, including update, check, tools, and scaffold help for stable, bundled, and exact-version requests.

• Effect v4 architecture validators: 91/91 tests and 1,112 expectations passed across the five accepted validators.

• Repository gates: behavior contract valid; check:repo and git diff --check passed.

• Deterministic packaged build: SHA-256 f4a4f0f118803fd0e420ef2d2129896e5022db74baad14b0fa91ebd45a6fb257 matched across two builds.

Docs Ingest

The private/internal docs path updated the existing CLI runbook and control-plane decision instead of creating duplicate concept or flow pages. The spec and delivery handoff now record implemented/ingested truth. PLAN.md and these implementation notes record current Effect v4 ownership; folder meta.json routes them in the existing IP-323 section. Root apps/wiki/index.md and newest-first apps/wiki/log.md provide the required source bookkeeping for this ingest.