Contract Artifacts

SupaCloud derives one committed, drift-gated contract artifact per consumer surface; nothing in a consumer’s contract is hand-maintained. Each artifact is generated from the Rust source of truth, and a CI gate fails the build if the committed copy drifts from what the code generates (ADR 0047).

Browser API — docs/openapi/public.json

The contract the web app consumes. Generated from the #[utoipa::path] handler annotations plus #[derive(ToSchema)] DTOs aggregated in server/src/interfaces/web_openapi.rs.

• Regenerate: cargo run -p supacloud-server --bin export_openapi -- --out docs/openapi
• Frontend binding: npm run typegen regenerates web/src/lib/generated/zod/ (kubb) plus api-types.public.ts and the api-operations.ts index; the web CI runs npm run typegen then git diff --exit-code web/src/lib/generated/.
• Gates: server/tests/openapi_spec.rs (committed equals generated, no orphan schema), server/tests/openapi_routes_drift.rs (spec is a subset of the router), server/tests/openapi_router_coverage.rs (the router is a subset of the spec — every mounted browser route is annotated or on the reviewed allow-list), and the frontend contract-completeness vitest (every fetchApiSchema validator is a generated schema bound to its path’s component).
• Error body: every error response carries the typed ApiErrorBody component (error, the ErrorCode enum, optional quota details).

Management API — docs/openapi/management.json

The machine-to-machine contract. Same generator and drift gate; consumed by no frontend, so it carries no frontend zod binding. Reference: management-api.mdx.

Agent MCP tool catalog — docs/mcp/tools.json

The contract agents consume over MCP: each tool’s name, allowlist tier, read_only flag, input_schema and output_schema.

• Source: the registry in server/src/services/mcp/ (ToolSpec).
• Regenerate: cargo run -p supacloud-server --bin export_mcp_catalog -- --out docs/mcp
• Gate: server/tests/mcp_catalog.rs (committed equals generated).
• Reference: mcp-tool-surface.mdx.

Inbound webhooks — the webhooks key in public.json

Deliveries SupaCloud receives (git-forge and tracker hooks, generic triggers) are declared under the OpenAPI 3.1 top-level webhooks key, with typed payload DTOs for the trigger envelopes and the path-token plus HMAC auth schemes. Generated and drift-gated with the browser spec.

Deployed-App to API callback (scwa_)

The endpoints a deployed App calls back (POST /apps/{id}/runs and the upload download) are #[utoipa::path]-annotated with their Bearer scwa_ security scheme, so they appear in public.json for App authors.

Workflow and workspace-manifest JSON Schemas

docs/schemas/workflow.json (generated from zod via web/scripts/gen-workflow-schema.mjs) and the workspace-manifest schema are committed and drift-gated alongside the above. Reference: workflow-yaml.mdx.