feat/one-api

Session actor principal is the internal Supabase auth UUID, not a public id

apps/platform/src/api/utils/public-v1-meta-gate.ts:147

For `actorType === 'user'`, `auth.userId` is the Supabase auth UUID — an internal identifier, not a customer-visible `prf_…` or `usr_…` prefixed public id. The `ApiRequestRecord.principal` JSDoc and the schema comment both say `principal` is 'a PUBLIC id, the same identifier the customer sees'. This is correct for machine actors; for session actors it is wrong. Access review queries built on this table will see internal UUIDs for session traffic that cannot be correlated to customer identities without an additional join through `profiles`. The code comment acknowledges this and defers the fix to W3, but W3 is when session traffic scales onto this surface — the table is live now. Using `auth.profilePublicId` (already on `AuthContext`, populated from the JWT) would fix this without other changes.

insufficient_scope 403 reveals the required scope name to the caller

apps/platform/src/api/utils/public-v1-meta-gate.ts:66

The `insufficientScope` response body includes the required scope names verbatim: `'This API key is missing a required scope (${required.join(', ')}).'` A caller with a valid but under-scoped credential learns the internal scope vocabulary by probing endpoints. Whether scope names are intended to be public is a product decision; they are not currently documented externally. A more conservative response would be `'This API key does not have the required permissions for this route.'` If scope names are meant to be discoverable, this is fine — but the decision should be explicit.

RLS policy grants DELETE on an append-only telemetry table

packages/database/src/schema/api-request-events.ts:76

`for: 'all'` grants SELECT, INSERT, UPDATE, and DELETE to `service_role` on a table documented as append-only. No client-role policy exists, so user-facing code can't delete rows — but any service-role shell or script can. This matches the project pattern (`idempotency_keys` etc.) and is low-risk at current scale. A `for: 'insert'` + separate `for: 'select'` policy pair would enforce the append-only invariant structurally.

batu_org_id claim collision has no automated guard against accidental hook emission

.claude/rules/rls-checklist.md

The documentation correctly warns that `batu_org_id` must never be emitted by `custom_access_token_hook` (it would become a cross-tenant read path for browser sessions via PostgREST/Realtime). The warning is documentation-only. There is no CI assertion that verifies the hook's claim set does not contain this key. A future developer adding a claim to the hook could inadvertently add `batu_org_id`. A test that parses the hook SQL and asserts `batu_org_id` is absent from the claim set would make this load-bearing.

No retention policy enforced — acknowledged, purge SQL ready but unscheduled

packages/database/src/schema/api-request-events.ts

The schema comment explicitly says to add a retention policy before this surface carries real volume. `scripts/db/api-usage.sql` contains a ready purge statement. The gap is that it is a manual script, not a scheduled pg_cron job. Should be converted before W3 multiplies traffic.

durationMs is a 32-bit integer — overflows at ~24 days

packages/database/src/schema/api-request-events.ts:63

Postgres `integer` is signed 32-bit (max ~2.1B ms ≈ 24.8 days). Vercel's function timeout is 60s, so no real request can exceed it. A `bigint` column would be safer for a time measurement, but not urgent at current scale.

Auth stashed on mutable request via Record<string, unknown> cast — untyped coupling

apps/platform/src/api/utils/public-v1-meta-gate.ts:181

`ctx.request.auth = auth` writes through a `Record<string, unknown>` cast. Nothing enforces that `withPublicApiAuth`'s read site uses the same property name, and `GateContext` does not declare `auth`. The rationale (one JWT verification per request) is sound and documented. The risk is in serverless-only safety: in a long-lived process the pattern would allow stale auth to leak across requests. Currently safe (Vercel serverless), but the coupling is invisible to the type checker.

waitForRow comment is stale — inverts the actual write semantics

apps/platform/src/__tests__/integration/api-telemetry-persistence.test.ts:34

The JSDoc says 'The write is intentionally off the response path, so poll rather than await.' The commit's entire point is the opposite: the write is now explicitly awaited IN the response path (`await write()` in public-v1-telemetry.ts). The poll still works (it finds the row immediately), but the comment inverts the contract — a future engineer reading it will think polling is load-bearing when it is not. Worse, if `write()` ever reverts to fire-and-forget, the poll still succeeds and the test stays green, silently repeating the defect this commit fixed. The correct pattern is `await recordApiRequest(...)` + immediate `db.select()` check, with the 30s timeout and polling loop removed.

Refusal integration test uses an impossible actor/principal combination

apps/platform/src/__tests__/integration/api-telemetry-persistence.test.ts:102

The test calls `recordApiRequest` with `actor: 'anonymous'` AND a non-null `principal`. In real gate operation, `actor: 'anonymous'` only appears when no token was resolved — by definition `principal: null` — which causes `recordApiRequest` to skip the DB write entirely. A non-null principal means auth was validated; the gate then sets actor to `'machine'`/`'service'`/`'session'`, never `'anonymous'`. The scenario this test exercises (`actor='anonymous' + non-null principal + status=401`) cannot be produced by the gate. It does cover the `outcome: 'refused'` derivation, but it is not evidence that real 403s (scope check, wrong credential class) are written to the durable sink. Use `actor: 'machine'` and `status: 403` to model the real scenario.

Throwing authenticated handler: server_error telemetry path is untested

apps/platform/src/api/utils/__tests__/public-v1-meta-gate.test.ts

The authenticated branch of `withMetaGate` wraps the handler call in try/catch, emits `{status: 500}` to telemetry, then rethrows (source lines ~191–196). No test provides valid credentials, a throwing handler, and asserts that the structured log line appears with `outcome: 'server_error'` before the error propagates. The unauthenticated branch (token-exchange, lines ~118–125) has the same gap. The comments identify a throwing token-exchange as 'the most interesting endpoint on the surface' — a gap a per-handler approach would miss — yet this is the one execution path with no coverage.

Gate tests don't assert the org field in the telemetry log line

apps/platform/src/api/utils/__tests__/public-v1-meta-gate.test.ts:347

The successful-request telemetry test asserts `route`, `status`, `outcome`, `actor`, `principal`, and `durationMs` but not `org`. The `org` field (`auth?.memberships[0]?.orgPublicId`) is the one the integration test was built to protect against the spread-bug regression. A unit-level assertion `expect(line.org).toBe('org_01TESTORGA')` would catch a regression at unit speed rather than waiting for the integration run.

Source-level guard could false-positive on trailing inline comments mentioning after(

apps/platform/src/api/utils/__tests__/public-v1-telemetry.test.ts:161

The comment-stripping regex `.replace(/^\s*\/\/.*$/gm, '')` only removes lines whose first non-space character is `//`. A trailing inline comment — e.g. `doSomething(); // uses after() under the hood` — would not be stripped, and `\bafter\s*\(` would match it, failing CI spuriously. The block-comment stripping is correct. The current file has no such trailing comments (verified), so this is a future brittleness, not a live bug.

Inner write() closure in persist() is a leftover from the race-based design

apps/platform/src/api/utils/public-v1-telemetry.ts:77

`persist()` defines an inner `async function write()` wrapping all logic, then immediately `await write()`. The inner function existed when the call was `Promise.race([write(), timeout])` — abandoning the outer await without cancelling `write()` required it to be a named function. That race is gone; the wrapper now adds a nesting level with no semantic purpose. The try/catch and body can be inlined directly into `persist()`.

emit() structural type should reference AuthContext directly

apps/platform/src/api/utils/public-v1-meta-gate.ts:135

The `emit` helper annotates `auth` with a hand-written structural type `{ actorType: string; userId: string; memberships: { orgPublicId?: string }[] }` instead of `AuthContext`, which is already imported. If `AuthContext` gains a field or one is renamed, the structural type silently drifts. Using `auth?: AuthContext` ties the annotation to the source of truth.

captureOne calls async recordApiRequest without await

apps/platform/src/api/utils/__tests__/public-v1-telemetry.test.ts:46

`captureOne` calls `recordApiRequest(record)` without `await`, then immediately checks the spy. This works because `console.log` is called synchronously before the first `await persist(...)`. But it creates a hidden structural dependency: if the log call is ever moved below an await (e.g. to log the outcome after persistence), the spy assertion runs before the log fires and the test passes vacuously. Making `captureOne` async and awaiting `recordApiRequest` would make the intent explicit.

db-changes grep pattern is approaching unreadable length

.github/workflows/pr-checks.yml:170

The grep `-qE` pattern is now >200 characters. Extracting it into a multi-line shell variable or a `.grep-patterns` file would make additions and code-review diffs readable without changing behavior.