change-server-api

Change a Server API

Trace the Contract

1. Inspect the nearest route, its owning domain service, route tests, generated SDK method, and every first-party consumer.

2. Decide whether the route is global, home-scoped, project-scoped, session-owned, or workspace-owned. Preserve Scope/directory resolution and authorization.

3. Decide whether the behavior is request/response state, a sequenced state event, or a streaming transport. Do not force WebSocket, SSE, WebRTC, file/blob, or external URL behavior into an ordinary SDK call.

4. Check the operationId for a generated-method collision before implementing. The generator keys a method by the id's first two segments with a leading global. stripped, so global.session.status and session.status both resolve to Session.status — the generated method silently retargets one route and the other disappears from the SDK entirely, with no build error. Give the newer route a non-colliding id (global.session.statuses, not global.session.status) and confirm after regeneration that both methods exist and target their own paths.

Implement

1. Validate path, query, form, and body input with precise Zod schemas.
2. Add describeRoute metadata, stable operationId, response schemas, and structured error responses. Add .meta({ ref: "TypeName" }) for reusable API-visible schemas.
3. Keep business logic in the owning domain rather than the route handler. For binary media, document the supported MIME types, preserve structured error reasons and propagate the request abort signal. Test the generated SDK blob path as well as the mounted route; request previews must use saved owner configuration without creating task sessions.
4. For state changes, persist first and publish the established event shape so frontend state can reconcile without per-event refetches.
5. Preserve scoped snapshot watermark headers where middleware supplies them. Do not claim Web snapshot gating that the client does not implement. Optional owner schemas must also project actual HTTP and event payloads. Use Session.publicInfo() at Session response boundaries; internal reads, imports and archive exports retain canonical metadata. Verify owner selection, absence while a different owner remains selected, ordinary mutation, and reinstall against the same stored records. Dynamic schema facades must retain named OpenAPI references on the facade itself so generated SDK body argument names remain stable.
6. Regenerate contracts from the repository root: