server: uniform error handling — domain errors → HTTP with stable codes and detail (part of the contract)

[JArmandoAnaya]

Context

Error responses are part of the public contract third parties program against.

Deliverables

• Exception-handler layer mapping kernel domain errors → HTTP status + stable machine
  code + human detail: NotFound→404, conflicts/invalid transitions→409, validation→422,
  confirmation-required→409 with explicit code, auth→401.
• Error body schema ({code, message, detail?}) declared in OpenAPI components and used
  everywhere.
• Unknown exceptions → 500 with an opaque id, never a stack trace.

Acceptance criteria

• Every domain error type has a mapped test
• Error schema present in openapi.json

[JArmandoAnaya]

Done — PR #96, squash-merged as 4217ce1. M3 is 2/14.

Shipped

• src/visionset/server/errors.py — ErrorBody {code, message, detail?}, ErrorRule, the complete 49-entry ERROR_RULES, rule_for, error_response, ERROR_RESPONSES / UNIVERSAL_ERROR_RESPONSES, install_error_handlers.
• create_app() in server/main.py, with app = create_app() kept module-level for scripts/export_openapi.py; /health moved onto an APIRouter.
• docs/api.md — the first delivery-surface doc, plus its row in docs/README.md.
• openapi.json regenerated: components.schemas is exactly ["ErrorBody"].

Both acceptance criteria are met, and by structural tests rather than by hand: set(ERROR_RULES) is asserted exactly equal to the error classes declared in kernel/errors.py, and ErrorBody is in the committed spec.

The decisions worth not re-litigating

Each is commented in the table with the docstring sentence that decides it.

• Clients branch on code, never on the status. DESTRUCTIVE_SCHEMA_CHANGE and SCHEMA_CHANGE_WOULD_ORPHAN are both 409 and only the first is retryable with a flag — branching on the status reproduces the exact loop SchemaChangeWouldOrphan's docstring warns about.
• Three rules place an error, not fifty. 404 = named something not there. 409 = well-formed request, the resource's state refuses it. 422 = the payload itself is wrong.
• ConstraintViolated → 500, opaque (its message is str(exc.orig), raw SQLite naming our own tables; services pre-check, so anything reaching the boundary is a guard nobody wrote). NoSplitRecipe → 404 (a release is immutable, so "resolve and resubmit" is a promise that cannot be kept). UnserializableManifest → 409 (valid body, defect in stored state). MediaToolUnavailable → 500, not 503 (no retry installs ffmpeg). UnsupportedMedia → 422, not 415 (415 is about the request's own Content-Type).
• WorkspaceBusy → 503 with Retry-After: 5 — kernel: SQLite concurrency posture — WAL, busy_timeout, OperationalError → domain error (closes the "database is locked" gap before background ingest) #80's first caller, matched to the store's busy timeout because a shorter hint aims a retry storm at the contention being reported.
• Opacity is by provenance, not by status. 5xx is opaque by default with an incident_id; three errors opt out because their message is the remedy (WORKSPACE_BUSY, WORKSPACE_FORMAT_TOO_NEW, MEDIA_TOOL_UNAVAILABLE). A mapped 5xx keeps its own code; an unmapped exception gets INTERNAL_ERROR.

The hole a test caught mid-implementation: MediaError.__str__ is f"{name}: {reason}", so keeping the file's path out of detail while message carried it hid nothing. A media error's message is now exc.reason alone. Anything publishing a structured kernel error has to check __str__, not just the fields it chose.

Traps for #25–#30

• Register on starlette.exceptions.HTTPException, not fastapi's. The router raises the Starlette class for unknown-path 404 and 405 and FastAPI's is a subclass — keying on the subclass would leave those two answering {"detail": ...} while everything else answered ErrorBody. There is a test.
• Handlers are (Request, Exception) -> Response and narrow inside — Starlette's ExceptionHandler takes Exception, and a narrower annotation fails mypy src/visionset, which CI runs. No # type: ignore.
• App-level responses={422,500,503} displaces FastAPI's HTTPValidationError entirely. That is what makes "one error body, used everywhere" true by construction instead of by every route remembering. A test asserts it never comes back — if it reappears, some route is documenting a second shape.
• Do not commit a unit of work in a Depends(...) teardown — an exception there after the response started produces RuntimeError: Caught handled exception, but response already started rather than an ErrorBody, which is precisely when WorkspaceBusy fires. Yield the service. Written into docs/api.md.
• Per-route status overrides go through error_response(exc, status=...), not a bare HTTPException — AssetNotInJob is a 404 in a path and a 422 in a body, and a future upload route needs 415.

What did NOT change

FORMAT_VERSION stays 10 — no migration; M3's only one is #25's, and a second appearing here would be the signal that logic is leaking upward. VERSION stays 0.0.1.dev0. No new dependency, no new kernel error, no new service, port or event. _auth_provider, require_token and EnvTokenAuthProvider are untouched; the existing 401 simply speaks ErrorBody now, WWW-Authenticate intact.

919 tests, up from 896.

Next: #25 — the real AuthProvider: a persisted adapter in kernel/adapters/, issuance as a TokenService (one door, confirm= on revoke), and M3's only migration, taking FORMAT_VERSION to 11. Its "401 with a stable error body" is now an instance of this contract rather than a second invention.