Effect API Contract Boundary

The Effect API contract boundary is the shared typed API surface owned by packages/contract.

Ownership

• packages/contract owns schemas, errors, security declarations, HarnessApi, and typed client construction.
• apps/api implements the contract with Effect HTTP router/layer primitives.
• apps/cli consumes the typed client path for control-plane metadata calls.

Invariants

• packages/contract imports no sibling apps.
• Apps share request and response shapes through the contract package.
• Better Auth implementation details do not leak into the contract package.
• Effect RPC remains out of scope until streaming or procedure semantics require it.
• Raw HTTP remains acceptable for artifact downloads and existing GitHub fallback compatibility. New control-plane metadata calls use the typed client.

Current API Shape

IP-97 fixed the first control-plane contract around baseline/channel resolution, artifact metadata, typed authorization failures, and generated client construction. Backoffice session validation now happens in the API implementation through Better Auth cookies rather than contract-level bearer security. The API may return typed unavailable errors until backend artifact storage exists; that storage concern is outside this boundary.

Related Flow

See Control Plane Baseline Resolution for how the CLI consumes this boundary while preserving fallback behavior.