Add generated control API schema

[almogdepaz]

Summary

• add control API schema source/generator/docs
• add generated schema artifact and snapshot/unit coverage

Source plan: .plans/c-generated-control-api-schema.md

Verification

• cherry-picked Ralph task commit onto fresh branch from main

[almogdepaz]

ran review passes against main...pr/herdr-c-generated-control-api-schema:

• edc-review security/adversarial
• edc-delivery-review goal + architecture fit
• edc-audit quality/maintainability
• antipattern-scan changed-region smell pass

verdict

• security: no direct trust-boundary regression found; the docs correctly say schemas do not replace route validation.
• delivery/architecture: not ready; the schema introduces a parallel hand-written contract that already diverges from runtime behavior.
• quality/antipatterns: high drift risk from a large manual contract blob plus sample-only validator tests.

findings

blocker — schema is a second source of truth, not the API contract source

• where: src/control-api/schema.ts:97-583, docs claim at docs/control-api-schema.md:3
• axis: delivery/architecture + quality
• problem: the public schema is hand-authored separately from the actual route validators/handlers in src/server/routes.ts and websocket code. the plan explicitly called out choosing schema ownership so runtime validators and docs do not drift; this implementation makes schema.ts the claimed owner while runtime behavior remains owned elsewhere.
• evidence: src/control-api/schema.ts manually restates every request/response shape. no server boundary consumes these schemas, and the tests only validate generated output/samples, not the real route contracts.
• why it matters: clients will treat docs/generated/control-api.schema.json as authoritative. once route behavior changes without schema edits, the generated artifact becomes confidently wrong.
• recommendation: either generate from/import shared runtime contract definitions used by routes, or downgrade this artifact to “best-effort documentation” and add drift checks against real handlers/integration responses.

important — create-session request schema allows payloads the server rejects

• where: src/control-api/schema.ts:245-254
• axis: delivery/architecture
• problem: POST /api/create defines project, newProject, cmd, and sessionName with no required fields and no anyOf requiring project or newProject. the runtime requires a valid folder name from newProject?.trim() || project?.trim() before doing anything.
• why it matters: generated clients can build schema-valid create requests that always get 400 invalid project.
• recommendation: encode project | newProject explicitly, or represent this route as an operation-specific schema with the actual runtime requirement.

important — compatibility tests do not exercise real API payloads

• where: tests/unit/control-api-schema.test.ts:127-198
• axis: delivery/quality
• problem: the compatibility tests validate hand-written samples with a partial in-test JSON schema validator. they do not call actual routes or validate real integration responses, despite the plan requiring representative API payloads to satisfy schemas.
• why it matters: the tests will stay green when runtime response shapes drift.
• recommendation: add integration coverage that captures actual route responses and validates them with a real JSON-schema validator or shared validation function.

recommendation

request changes before merge.

[almogdepaz]

addressed the schema review findings in 8f4e533.\n\nwhat changed:\n- docs no longer claim src/control-api/schema.ts owns runtime behavior; runtime routes remain authoritative\n- POST /api/create request schema now requires project or newProject\n- regenerated docs/generated/control-api.schema.json and snapshot\n- added a real-server integration contract test for representative runtime responses\n\nverification:\n- bun test tests/unit/control-api-schema.test.ts tests/integration/control-api-schema-contract.test.ts\n- bun test\n- bun run typecheck\n\nreview status: findings were valid enough to fix; no rebuttal needed.