feat/one-api

concept_meaning uses `unit` — shipped schema requires `units` (plural)

.claude/rules/one-api.md

ConceptMeaning interface and its Zod schema both define the field as `units` (plural). An implementor following this example emits the wrong field name — clients silently get undefined for every unit.

Job phase 'created' not in PublicJobPhaseSchema enum

.claude/rules/one-api.md

Shipped enum: queued|collecting|processing|persisting|finalizing|completed|failed. 'created' does not exist. Correct value is 'queued'.

Job phase 'persisted' not in PublicJobPhaseSchema enum

.claude/rules/one-api.md

Completed-job example shows phase: 'persisted'. Shipped enum has 'persisting' (in-progress), not 'persisted'. Terminal completed phase is 'finalizing' or 'completed'.

Failure shapes omit 429 — a status code the API actively emits

.claude/rules/one-api.md

Section titled 'the complete set' enumerates 400/401/404/409/500. ts-rest-auth.ts emits HTTP 429 RATE_LIMIT_EXCEEDED and PublicApiErrorCode includes 'rate_limited'. False completeness claim will mislead SDK authors.

concept_meaning position differs between list and detail endpoints

.claude/rules/one-api.md

On list, concept_meaning is at envelope root. On GET /v1/bills/:id, it lives inside data. Rule shows only the list shape.

`items` as integer count (not array) is consistent with shipped schema

.claude/rules/one-api.md

PublicBillListResponseSchema confirms items: z.number().int().nonnegative(). Array lives under `data`. No bug — unusual naming worth a note in the grammar.

Failure shapes omit 403 (insufficient scope) — completeness claim is false

.claude/rules/one-api.md

403 needed when a valid credential lacks the required scope (W2 scope enforcement). Without a canonical 403 shape, implementors will conflate it with 401.

409 OCC leaks version counters to public callers

.claude/rules/one-api.md

expectedVersion/actualVersion enable a timing oracle for public routes. Should note that version numbers are withheld from public 409 bodies (W3 ratification item).

401 uniform response adequately prevents credential oracle attacks

.claude/rules/one-api.md

Single uniform 401 body for all credential failure paths. Correct design — no action needed.

`object` rule says 'registry entity name' — shipped literals are lowercase shorthand

.claude/rules/one-api.md

PublicIdPrefix registry uses PascalCase (CfeJob). Shipped schemas use lowercase shorthand (z.literal('job')). 'Registry entity name' is ambiguous.

`concept_meaning` at envelope root not explained by nesting rule or JSend definition

.claude/rules/one-api.md

Rule defines envelope as {status, data}; concept_meaning lives at root. Real JSend departure not named as an exception.

Job flat nullable scalars violate the rule's own 'correlated nullable' smell without annotation

.claude/rules/one-api.md

Rule says correlated nullable scalars should be one optional block. Queued-job shows result:null, error:null, started_at:null, completed_at:null — no ⚠ explaining the intentional flat shape.

`items` as count vs array — unusual convention worth noting

.claude/rules/one-api.md

Most REST APIs use `items` as the array field name. Here it is a count. No inconsistency with code, but not self-documenting.

Missing PATCH/OCC example leaves Update mechanics unspecified

.claude/rules/one-api.md

No example showing request body with version, 200 response with version:N+1, or the 409/200 relationship. Implementors will omit version on first attempt.

Cursor inbound param name not shown — client will silently get wrong results

.claude/rules/one-api.md

parseBillsListQuery reads q.cursor — inbound param is 'cursor', not 'next_cursor'. A client passing ?next_cursor=<token> silently gets the full list via passthrough.

`object: 'job'` and `object: 'energy_summary'` have no registry entry

.claude/rules/one-api.md

Rule states object MUST equal the registry entity name. PublicIdPrefix has no 'job' or 'energy_summary' entry. Allocation rule for non-entity resources is unspecified.

`progress/result/error` mis-classified as optional block

.claude/rules/one-api.md

`progress` is always present; `result`/`error` are mutually exclusive non-null. Three fields do NOT appear/disappear together — closer to a discriminated union over lifecycle stages.

`completed_at` populated on failed jobs — misleading name not annotated

.claude/rules/one-api.md

Failed job example shows completed_at set even though status is 'failed'. Semantics are 'terminal state reached at'. Should be annotated as a ⚠ wart.

`hired_demand`/`connected_charge` as strings contradicts floats-for-measurements rule

.claude/rules/one-api.md

These are kW values (not money) yet appear as strings due to Drizzle numeric() coercion. Rule says measurements are floats (energy_summary). Exception not annotated.

GET single, DELETE, webhook event shapes have no examples

.claude/rules/one-api.md

Operation grammar lists 7 op types; examples cover List + Async-job create/poll. Single-resource GET, Delete response body, and signed webhook envelope are absent.

`partial_success` job status has no example

.claude/rules/one-api.md

PublicJobStatusSchema includes partial_success. An implementor may collapse it into 'completed' when deriving from examples rather than the schema.