ClawQL: Skill for Cursor

gdp-ts

A sensitive function (one that reads or changes something only some callers may touch) takes a proof about its exact arguments, so calling it without the check, or with a check about a different value, does not compile.

1. Name values. name(viewer.id, projectId, async (user, project) => ...) gives each value a compile-time-only name, valid inside the callback.
2. Prove facts about names. A small trusted module in proofs/ runs the check and returns a proof such as UserIsProjectAdmin<U, P>, or null. Only that module can mint it.
3. Demand proofs. The sensitive function takes project: Named<P, ProjectId> and _proof: UserIsProjectAdmin<U, P>. The wrong proof, a proof about another value, a raw id or no proof is a compile error.

This is not a theorem prover. Prove the facts whose absence would be an incident, and stop there (where to stop).

Workflow

When adding or changing authorization in a codebase that uses this pattern:

1. Is the id branded? If not, brand it first.
2. Is there a proof for the fact you need in proofs/? If yes, reuse it. If no, add one file: private defineProof, exported interface X<...> extends Proof<"X", [...]> {}, exported async function x(...named): Promise<X<...> | null>. Nothing else.
3. Does the sensitive function take proofs about its named arguments? If it takes raw ids, change the signature; let the compiler list the call sites to fix.
4. Does the request carry other values the operation trusts (a token in a cookie, an id in the body)? Check them in a trusted module against the resource they claim to unlock (TokenUnlocksUrl<H>). This is where cross-resource and cross-tenant bugs live.
5. Are there non-user preconditions (plan, scope, state)? Make them proofs too (PlanIncludesPasswordProtection<P>).
6. In the handler body (not middleware): name(...), call the policy function, turn null into the right HTTP response, do all sensitive work inside the callback. If that block will likely be called from many places, consider moving it into a shared function (recipe step 5).
7. Never write as to satisfy a proof or Named type. If you feel the need, the signature is wrong or you are outside proofs/. If the codebase has no gdp-ts lint preset yet, add it (recipe step 6); if it does, fix lint errors rather than disabling them.
8. Never export a prover, never call defineProof outside proofs/, never return a Named, or a proof that mentions that callback's names, from a name() callback.
9. Add the new mistake you almost made to mistakes.ts (a type-checked file that never runs) as one line under // @ts-expect-error. It is the cheapest regression test you will write (details).
10. Test the proof function you added. It is the only thing that can be wrong at runtime.
11. ClawQL: mint where the check happens. The function that performs redaction / hash verify / two-party gate / session verify returns the proof (or { result, proof }). Do not mint in a separate helper that assumes the check already ran.
12. ClawQL: never store proofs. Do not write proofs into pending records, subscriptions, queues, or Redis. Keep them inside one name() callback / request. Long-lived authority stays with runtime rechecks.
13. ClawQL: keep gdp-mistakes.ts honest. Add @ts-expect-error lines for no proof, wrong proof, proof about another value, and raw id. CI runs npm run test:gdp-mistakes (see ADR 0013).
14. ClawQL: never treat a proof as runtime authority from agent code. The gateway must not accept proof objects from skills/scripts. gdp-ts is a quality / promotion gate for TypeScript; containment is sandbox + ATR + OpenAPPA + server-side mandates. Promotion means reusable under declared scope, not unsandboxed. Details: ADR 0013.