feat/one-api

routeMeta() and RouteMeta do not exist yet — W2 deliverable presented in syntax-level positions

.claude/rules/one-api.md

The code snippet uses routeMeta({...}) and the prose describes RouteMeta as a closed typed shape with a builder in packages/api. Neither exists today. The rule acknowledges this is a W2 deliverable but the code sample treats it as callable syntax. Implementors may write contracts using routeMeta() before W2 lands and get TypeScript errors. The sample should be clearly marked as target/aspirational code.

withApiAuth does not exist — actual middleware is withPublicApiAuth (different name)

.claude/rules/one-api.md

The rule prescribes 'withApiAuth → validator → shell → mapper' in both the handler layout and RouteMeta prose. The actual codebase uses withPublicApiAuth exclusively — no withApiAuth symbol exists. The unified withApiAuth is also a W2 deliverable. The rule places withApiAuth in syntax-level positions without marking it as future, which will mislead developers trying to follow the pattern today.

docs-coverage-and-leak test exists and is correctly cited

apps/platform/src/lib/openapi/__tests__/docs-coverage-and-leak.test.ts

The test exists, covers one-doc-page-per-operation and an internal-term denylist. The citation in the rule is accurate.

publicIdRegex(PublicIdPrefix.X, 'i') signature is correct and in active use

packages/api/src/schemas/public/bill.public-schemas.ts

The prescribed form is confirmed in multiple public schema files. The rule's guidance is accurate.

Handler typing pattern typeof contract.x.handler is accurate

apps/platform/src/api/handlers/admin-organizations.handler.ts

This is the actual pattern used throughout the handler layer. Confirmed correct.

Interim period has no type-enforced auth gate — safe-interim pattern not stated

.claude/rules/one-api.md

withApiAuth and routeMeta() don't exist until W2. Any new route written following this rule today has no auth enforcement. The rule should explicitly state the safe interim pattern (use existing withAuth/withPublicApiAuth wrapper) and require that no public-visibility routes are merged without it until W2 lands.

Router-level metadata default { capability } does not supply auth/scopes — absent fields must deny by default

.claude/rules/one-api.md:127

The example router default is { metadata: { capability: 'bills' } } — it sets only capability, not auth/scopes/visibility. The rule should state that missing auth or scopes on a route are a hard gate failure (deny by default, not allow-all). A route that accidentally omits routeMeta() inheriting only capability from the router default would otherwise become an unauthenticated endpoint.

Target layout introduces validators/ directory not present in codebase or canonical-form.md

.claude/rules/one-api.md:88

The canonical layout shows validators/{capability}.validators.ts but the actual codebase uses apps/platform/src/api/utils/ (e.g. public-v1-validation.ts). canonical-form.md's API Surface Pattern section does not include a validators/ directory. As a prescriptive target this is intentional, but the rule should note the current utils/ home and migration path so implementers aren't confused about where existing validators live.

7+ public-v1 handlers use hardcoded prefix literals — rule violation with no enforcement test

apps/platform/src/api/handlers/public-v1/bills.handler.ts:29

The rule says 'ids validate via publicIdRegex(PublicIdPrefix.X, 'i'), never a prefix literal'. At least 7 handlers define hand-written literal regexes (/^bil_.../i, /^bfl_.../i, /^sit_.../i, /^cfj_.../i etc.). The public-id-prefix-registry.test.ts guards the registry but there is no test that fails when a handler defines a literal regex. A grep-based test scanning handlers/ for /^[a-z]{3}_/ string literals would mechanically enforce the rule.

route-inventory.json has no schema validation test — can silently go stale

scripts/one-api/route-inventory.json

The JSON file is the interim registry seed until W2 lands. There is no test that validates its structure (required fields, valid visibility/op/auth enum values, no duplicate routes). Without a schema assertion the file can drift from the shape the rule specifies and the W2 migration will be based on stale data.

'operation grammar table (below)' is actually above the section

.claude/rules/one-api.md:139

The bullet reads 'Per-op mechanics come from the operation grammar table (below)' but the Operation grammar table sits at lines 68–79, which is above the newly inserted section. Change '(below)' to '(above)' or '(see § Operation grammar)'.

Invalid TypeScript in canonical example: responses: { 200: ..., 404: ... }

.claude/rules/one-api.md:122

The spread '...' inside an object value position is not valid TypeScript and cannot be copy-pasted. Either spell out the schema name (200: RecomputeResponseSchema) or use a comment placeholder — but not a bare '...' as a value.

Migration path from utils/public-v1-validation.ts to validators/ is unspecified

.claude/rules/one-api.md:88

The target layout introduces validators/{capability}.validators.ts but provides no guidance on when/how to split the monolithic public-v1-validation.ts. A developer converging a capability may leave the old file in place and end up with two overlapping gates. At minimum, add: 'During convergence, carve the capability's parse* functions from utils/public-v1-validation.ts into validators/{capability}.validators.ts; delete the origin once the twin is removed.'

No guidance on what happens to -internal contract files during convergence

.claude/rules/one-api.md:85

The section opens with 'One capability = ONE contract module, no -internal twin' but doesn't explain how existing -internal files should be treated. The DUAL convergence recipe says 'delete the twin' but doesn't name the file pattern. A developer touching bills finds bills.contract.ts AND bills-internal.contract.ts with no clear instruction on when/how to merge.

ts-rest version claim unverified — not pinned anywhere in the repo

.claude/rules/one-api.md:95

The rule states 'ts-rest ≥3.52 supports metadata per route AND per router' as a load-bearing architectural fact. No package.json peer constraint or comment points developers where to verify. Add a pointer: 'Verify with pnpm ls @ts-rest/core — must be ≥3.52 for router-level metadata merge.'