Vertragsartefakte

SupaCloud leitet pro Konsumentenfläche genau ein eingechecktes, drift-geschütztes Vertragsartefakt ab; nichts im Vertrag eines Konsumenten wird von Hand gepflegt. Jedes Artefakt wird aus der Rust-Quelle der Wahrheit generiert, und ein CI-Gate lässt den Build scheitern, sobald die eingecheckte Kopie von dem abweicht, was der Code generiert (ADR 0047).

Browser-API — docs/openapi/public.json

Der Vertrag, den die Web-App konsumiert. Generiert aus den #[utoipa::path]- Handler-Annotationen und den #[derive(ToSchema)]-DTOs, gesammelt in server/src/interfaces/web_openapi.rs.

• Neu generieren: cargo run -p supacloud-server --bin export_openapi -- --out docs/openapi
• Frontend-Bindung: npm run typegen regeneriert web/src/lib/generated/zod/ (kubb) sowie api-types.public.ts und den api-operations.ts-Index; die Web-CI führt npm run typegen und danach git diff --exit-code web/src/lib/generated/ aus.
• Gates: server/tests/openapi_spec.rs (eingecheckt gleich generiert, keine verwaisten Schemata), server/tests/openapi_routes_drift.rs (Spec ist Teilmenge des Routers), server/tests/openapi_router_coverage.rs (der Router ist Teilmenge der Spec — jede gemountete Browser-Route ist annotiert oder auf der geprüften Allow-List), und die Frontend-contract-completeness-Vitest (jeder fetchApiSchema-Validator ist ein generiertes Schema, gebunden an die Komponente seines Pfads).
• Fehler-Body: jede Fehler-Antwort trägt die typisierte ApiErrorBody-Komponente (error, das ErrorCode-Enum, optionale Quota-details).

Management-API — docs/openapi/management.json

Der Maschine-zu-Maschine-Vertrag. Gleicher Generator und Drift-Gate; wird von keinem Frontend konsumiert und trägt daher keine Frontend-zod-Bindung. Referenz: management-api.mdx.

Agent-MCP-Tool-Katalog — docs/mcp/tools.json

Der Vertrag, den Agenten über MCP konsumieren: Name, Allowlist-Stufe, read_only-Flag, input_schema und output_schema jedes Tools.

• Quelle: die Registry in server/src/services/mcp/ (ToolSpec).
• Neu generieren: cargo run -p supacloud-server --bin export_mcp_catalog -- --out docs/mcp
• Gate: server/tests/mcp_catalog.rs (eingecheckt gleich generiert).
• Referenz: mcp-tool-surface.mdx.

Eingehende Webhooks — der webhooks-Schlüssel in public.json

Zustellungen, die SupaCloud empfängt (Git-Forge- und Tracker-Hooks, generische Trigger), werden unter dem OpenAPI-3.1-Top-Level-Schlüssel webhooks deklariert, mit typisierten Payload-DTOs für die Trigger-Hüllen und den Auth-Schemata aus Pfad-Token und HMAC. Generiert und drift-geschützt zusammen mit der Browser-Spec.

Deployte-App-zu-API-Callback (scwa_)

Die Endpunkte, die eine deployte App zurückruft (POST /apps/{id}/runs und der Upload-Download), sind mit #[utoipa::path] und ihrem Bearer-scwa_-Security-Schema annotiert und erscheinen so in public.json für App-Autoren.

Workflow- und Workspace-Manifest-JSON-Schemata

docs/schemas/workflow.json (generiert aus zod via web/scripts/gen-workflow-schema.mjs) und das Workspace-Manifest-Schema sind zusammen mit dem Obigen eingecheckt und drift-geschützt. Referenz: workflow-yaml.mdx.