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.

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.

CLI Retrieval

apps/cli/src/baseline/resolve.ts treats the control plane as the sole online authority. stable and exact versions resolve there once; authority failure does not trigger another source. 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 only for an explicit bundled request. update, check, tools, and scaffold accept stable, bundled, or an exact version and preserve the normalized request through resolution.

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.