4  What would make this stronger

Each item below is a capability the surface lacks, with what it would cost. They are ordered by the ratio of the two, not by ambition.

4.1 Close the 6 undeclared access rules

Cost: small. Each is a one-line addition to the specification, stating either the scheme the handler enforces or security: [] for a deliberately public endpoint. The value is that “public” becomes a decision on the record rather than an absence someone has to interpret.

4.2 Resolve the 1 service-role operation with no verified caller

Cost: one review each. The outcome for most will be “correct as written, and here is why” — a sign-in entry point has no caller to verify. Recording that reasoning next to the handler converts a standing question into a settled one, and shrinks the review surface for the next person.

4.3 Bound the list operations

16 of 35 list operations declare a limit, offset, page or cursor parameter. The rest return whatever the query returns. At campaign scale that is a response whose size is set by the data rather than by the caller, and the first symptom is a slow screen rather than an error.

Cost: moderate, and it is a contract change. Adding a default ceiling alters what an existing client receives, so it needs a version or an opt-in.

4.4 Give the 51 run-time responses a readable shape

Cost: small per handler, tedious in aggregate. Returning a literal instead of a variable makes the response shape visible to this document, to a type checker, and to whoever changes the handler next. It is the difference between a contract and a convention.

4.5 Bring the 19 cookie-only handlers onto the shared helper

103 route files authenticate through requireUser(request), which takes a bearer token when one is present and falls back to the browser’s cookie session. 19 build a Supabase server client directly, so they have the cookie and nothing else.

The consequence is not theoretical: a caller holding a token rather than a session — an AI engine, kavai api, any integration — cannot reach those 19 whatever the specification says about them. This is the same condition the spec records as blocked: bearer-auth on an operation otherwise eligible to be an agent tool.

Cost: small per handler, since the helper already exists and already does both. The value is that “can an engine call this?” becomes a property of the surface rather than something established by trying it and reading the 401.

4.6 Confirm the 61 inferred intents

Every operation carries a why it exists line, which is a real achievement — the surface went from nothing to near-complete coverage. But 61 of the 196 are marked †: written by someone reading the handler, not by whoever decided the operation should exist.

That distinction is the whole point of the mark. An inference can describe the behaviour accurately and still be wrong about the purpose — it can say what a handler does while attributing a reason nobody held. Only the author can settle it, and until they do, a reader cannot tell a recorded decision from a good guess.

Cost: a read-through, not a writing exercise. Most will be right and need only confirming: drop the @intent-source inferred marker and the † disappears on the next build. The ones that are wrong are the reason to do it at all, and they are not identifiable from the outside.