WS-003: Why App API owns published contracts¶
| Status | Accepted |
| Date | 2026-08-05 |
| Sources | 2026-08-05-runtime-publish-metadata-contracts.md (rejected); 2026-08-05-app-api-publish-provider-capability-contracts.md (implemented) |
Context¶
External consumers (and the Runtime itself for inventory/catalog) need stable HTTP contracts: OpenAPI, provider/capability metadata, version stamps.
Problem¶
If the runtime grew a second public HTTP surface for “contracts,” ownership
would split: binary release vs API deploy, two places to break compatibility,
and the principle “external consumers integrate only through api.” would die.
Decision¶
engineering-runtime-app-api owns published contracts on
api.engineeringruntime.com.
- Runtime remains SSOT for provider/capability content
- App-api deploy-cloud-run checks out the runtime, builds
catalog.json, publishes/metadata/catalog|providers|capabilitieswith the runtime commit stamped in - OpenAPI and route inventory are app-api’s surface; the runtime may vendor a copy for checks, but does not become a second publisher
Alternatives considered¶
| Alternative | Why rejected |
|---|---|
Runtime hosts /metadata itself (2026-08-05-runtime-publish-metadata-contracts) |
Second API surface; conflicts with “api. is the contract”; rejected and kept as the ADR alternatives record |
| Hand-copied catalog in app-api | Synchronized copies — drifts |
| Consumers clone private repos for schemas | Breaks private-repo / published-contract stance |
Consequences¶
- Catalog CI dependency in app-api is permanent (it builds the contract)
- Staleness is visible via commit stamps
- Planning-only follow-up: runtime may later fetch inventory from live OpenAPI
instead of a private checkout (
2026-08-05-runtime-reads-api-contract-from-api-host)