csv-lens

name	csv-lens
description	Activate for any ticket that touches a Supabase RPC, edge function, or TypeScript client function in src/lib/. Ensures both caller and callee are verified before state:ready-for-qa.
argument-hint	RPC name, edge function name, client function, or contract surface

CSV — Client-Service Contract Lens

Activate this lens when a ticket changes a Supabase database function (RPC), edge function, or the TypeScript client layer. Contract breaks at the boundary between SQL and TypeScript are the most common source of bugs that pass unit tests but fail in Tester's end-to-end verification.

When to Activate

Load this lens when the ticket changes any of the following:

• A Supabase SQL function in a migration (CREATE OR REPLACE FUNCTION)
• A Supabase edge function (supabase/functions/)
• A TypeScript client wrapper (src/lib/supabase.ts, src/lib/adminApi.ts, src/lib/stripe.ts, or any src/lib/*.ts)
• A data-fetching hook that calls supabase.rpc() or a Supabase edge function directly
• A type definition that represents a Supabase response shape (src/types/database.ts or equivalent)

The Contract Checklist

For each changed contract surface, verify both sides before claiming done. Cross-layer claims require cross-layer proof — confirming one side only is not sufficient.

SQL side

Check	What to verify
Parameter names and types	SQL function parameter names and types match exactly what the TypeScript caller passes to supabase.rpc() or the edge function fetch
Return shape	SQL RETURNS type, RETURNS TABLE columns, or JSON response shape matches the TypeScript type that consumes the result
Error contract	SQL raises an exception (RAISE EXCEPTION) on known failure conditions in a way TypeScript can classify — not returning null silently
Nullable fields	SQL columns that can be NULL correspond to optional (?) fields in the TypeScript type — no silent null becoming undefined mismatch
RLS	Row-level security policies on affected tables still permit the calling role's operations after the change

TypeScript caller side

Check	What to verify
No any shortcuts	The RPC response or edge function response is typed with a concrete type, not widened to any or unknown without explicit narrowing at the callsite
Error path handled	The .error branch from supabase.rpc() or the edge function fetch is handled — surfaced to the UI, thrown, or logged — not silently swallowed
Caller is reachable	The updated client function is actually called from the correct component or hook; no dead code path where the old contract remains in use
Types compile	If a shared type in src/types/ was updated, all consumers compile without @ts-ignore or as any suppressions
Auth header	If the edge function requires the user's JWT, the caller passes Authorization: Bearer <token> correctly

Naming the Contract Surface

Before implementation, name the specific contract surface this ticket touches:

Contract surface: [supabase.rpc('function_name') | supabase/functions/name | src/lib/file.ts:functionName]
Direction of change: [SQL only | TypeScript only | both sides]

A ticket that only touches the TypeScript side (no SQL change) still needs the TypeScript checklist — it may introduce a type mismatch against an unchanged SQL contract.

Pre-Handoff Gate

Before moving the ticket to state:ready-for-qa, post the following confirmation on the GitHub issue:

CSV verified:
- Contract surface: [name]
- SQL side:         [parameter shape ✓ | return shape ✓ | error contract ✓ | n/a]
- TypeScript side:  [typed correctly ✓ | error handled ✓ | caller reachable ✓ | types compile ✓]

If the ticket only touches one side, note which side was verified and why the other is unaffected. Tester will attempt to exercise the contract end-to-end; a contract that looks correct in isolation can still fail when both sides interact.