0004: Browser-safe contracts drive the API and SDK
One shared schema boundary for stored values and HTTP resources
- Status: Accepted
- Date: 2026-09-09
- Decision maker: Trevor Gerhardt
Context
The API and SDK need the same resource shapes and validation rules. Browser code must not import database clients or Node modules to use them.
Decision
@concourse/contracts is the browser-safe leaf for shared schemas, stored values, and the HTTP declaration. It imports no other workspace package, and dependency-cruiser enforces this rule. RSDB imports the Rackspace verification schemas from it. Persistence derives stored column values from these schemas. API implements the declared resources. SDK derives its Effect client and Promise facade from the same declaration, without repeating endpoint definitions or response decoders.
Each shared subject has one public entry point. The Contracts guide owns those paths. The API guide and SDK guide own resource and client details.
The HTTP boundary keeps typed, safe refusals separate from transport and response-decoding failures. Request-scoped credentials do not leak between clients. Internal causes and submitted secrets never enter responses.
Consequences
- API and SDK changes must agree with one declaration.
- Contract entry points must load under the browser condition. The root contract test enforces this boundary.
- Domain packages lose local ownership of schemas that cross package boundaries.
History
Shared contracts once lived beside domain implementations. The HTTP contract later added one declaration for API handlers and both SDK clients.