Server Guide

Runtime contracts

Use Valibot for all server data that crosses a trust boundary.
This includes HTTP data, Pub/Sub messages, queue jobs, WebSocket events, database JSON, and provider responses.
Define each schema beside the contract owner.
Use parse if the caller converts invalid data into an error.
Use safeParse if the caller branches on valid and invalid data.
Do not use typeof, Record<string, unknown>, or type casts as runtime input validation.
Infer TypeScript types from Valibot schemas. Do not duplicate the contract in an interface.

Put server ADRs directly in server/docs/ai/, relative to the repository root.
Include ADRs in the related commits and pull requests in this repository.
Create or update the ADR before you change a server boundary.
A server boundary includes an HTTP contract, provider contract, persistence model, or cross-module lifecycle.
Add a module dependency graph, an affected-file tree, and a sequence diagram to every implementation ADR.
State the decision, scope, non-goals, and test plan in the ADR.
Keep the ADR status accepted only after the decision is confirmed.
Update the ADR when implementation changes the accepted design.