spec: register the three AI_* quota codes in the error-code ledger (ruled Option A on the cloud#1168 vocabulary fork)

[claude]

Part of objectstack-ai/cloud#1168. Maintainer ruling 2026-08-11, from the four-lens decision review: Option A — register three codes in ERROR_CODE_LEDGER (packages/spec/src/api/error-code-ledger.zod.ts):

• AI_ALLOWANCE_EXHAUSTED
• AI_DESIGN_QUOTA_EXHAUSTED
• AI_DATA_CHAT_TRIAL_EXHAUSTED

Casing per the mechanical rule in error-code-ledger.test.ts. Each entry documents its CTA semantics (upgrade / top-up / trial) so the three-state mapping is on the ledger row, not in consumer folklore.

Why A over the standard-QUOTA_EXCEEDED-plus-details route: the three states carry distinct CTAs — real business branches, not synonyms; closed-enum literals are the hardest shape for AI consumers to misuse, whereas a structured details read downgrades the check even with a declared shape.

Downstream (not this card): cloud's two producers converge on the literals (cloud#1168, which should carry a Blocked-by: on this card); objectui's parseAiQuotaError switches to the three literals (objectui#3804, held finding until this lands).

Note: this changes the accepted error-code vocabulary — an acceptance-face change, hence domain:spec per the standing red line.

Filed by the triage seat Routine (#5474 pilot) recording a maintainer ruling of 2026-08-11. Unassigned — recording, not claiming.

---

Generated by Claude Code

[os-zhuang]

CLAIM — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-7495-ai-quota-error-codes. Dispatching a cloud dev session (model: Opus — the ruling enumerates the three literals and their CTA semantics; mechanical ledger registration).

Executing the maintainer ruling of 2026-08-11 (Option A on the cloud#1168 vocabulary fork) as recorded in the card body: register AI_ALLOWANCE_EXHAUSTED / AI_DESIGN_QUOTA_EXHAUSTED / AI_DATA_CHAT_TRIAL_EXHAUSTED in ERROR_CODE_LEDGER, casing per the mechanical rule in error-code-ledger.test.ts, each entry documenting its CTA semantics (upgrade / top-up / trial) on the ledger row.

Scope boundary: downstream convergence (cloud#1168 producers, objectui#3804 parseAiQuotaError) is NOT this card. Serial check: no in-flight writers on error-code-ledger.zod.ts in this lane.

---

Generated by Claude Code

[os-zhuang]

DEV CLAIM — dev seat, session session_01TrAWA6xJPVSjtrfJtEY6yr. Branch: claude/issue-7495-ai-quota-error-codes.

Implementing the maintainer ruling of 2026-08-11 (Option A on the cloud#1168 vocabulary fork) exactly as recorded in the card body: register AI_ALLOWANCE_EXHAUSTED / AI_DESIGN_QUOTA_EXHAUSTED / AI_DATA_CHAT_TRIAL_EXHAUSTED in ERROR_CODE_LEDGER (packages/spec/src/api/error-code-ledger.zod.ts), casing per the mechanical rule in error-code-ledger.test.ts, each row documenting its CTA semantics (upgrade / top-up / trial) in the file's own convention.

Scope boundary held: no cloud/ or objectui/ changes (cloud#1168 producers and objectui#3804 parseAiQuotaError land separately); no content/docs/releases/, no docs/adr/**.

---

Generated by Claude Code

[os-zhuang]

OS-DEV-REPORT — #7495

Outcome: blocked — premise broken. No code written, no PR opened.

The card cannot be executed as written, for a reason that is not a judgement call: there is no valid owner key for these three codes, and registering them here reverses a separate, twice-confirmed maintainer ruling (#4805) that the card never addresses.

The blocker, in the target file's own words

error-code-ledger.zod.ts opens with the #4805 scope rule (lines 19–54), a maintainer ruling of 2026-08-03, re-confirmed 2026-08-09 — two days before this card's ruling:

> Every owner key below is a package published from this repository, and that is a RULE … A downstream product repo (objectstack-ai/cloud, or any product built on the platform) does not register its codes here. It maintains its OWN ledger, in its own repo …
>
> A commercial vocabulary does not belong in an Apache-2.0 spec. The codes worth registering are precisely the product-specific ones (billing and plan-gating states, control-plane provisioning refusals) …
>
> … a PR adding an owner key for a package that is not published from this repository is out of scope by construction.

The three AI_* codes are cloud's plan-gating states — their CTAs are literally upgrade / top-up / trial. They are the paradigm case #4805 excludes.

Mechanically: ERROR_CODE_LEDGER is keyed by emitting package, and the rows are provenance. I verified there is no framework producer: no AI/quota service exists anywhere in packages/ (no service-ai, no matches for aiAllowance / designQuota / dataChatTrial), and the only repo-wide mentions of this vocabulary are the mirrored objectui changelog lines for parseAiQuotaError. Every candidate owner key would be fabricated. I could not pick one by default without asserting a provenance that does not exist.

The seam is pinned in code, not just prose. contract.test.ts:588 (makeApiErrorSchema (federated ledger, #4805)) uses DOWNSTREAM_CODES = ['CONTACT_SALES_PLAN', 'PRODUCTION_ENV_LIMIT'] — plan-gating literals of exactly this class — and asserts ApiErrorSchema refuses them, accepting them only through the downstream factory.

Why I read this as an oversight, not an override

The 2026-08-11 ruling resolved a shape fork: closed literals vs QUOTA_EXCEEDED + structured details. Option A won on the merits recorded in the card — closed-enum literals are the hardest shape for AI consumers to misuse. That verdict is untouched by #4805. Option A is fully achievable with the ledger where #4805 put it:

// in cloud's own repo
const CloudApiError = makeApiErrorSchema(CLOUD_ERROR_CODES);  // StandardErrorCode ∪ cloud's ledger

The three literals stay closed, stay checkable, and objectui's parseAiQuotaError switches to the same three literals either way. The only thing that changes is which repo's ledger declares them — which is the exact question #4805 decided, and which this card's four-lens review does not appear to have had in front of it (the card cites neither #4805 nor an owner key). The filing seat was a triage Routine recording a ruling, which is the seat most likely to miss a cross-cutting rule.

Reverse verification (predicted in writing, then run)

All probes on a throwaway copy in the worktree; reverted, tree is clean, nothing committed.

#	Predicted	Observed
A	Adding the 3 codes under a framework owner key passes every gate — the violation is invisible to CI	Confirmed. 3 spec suites (error-code-ledger, contract, error-catalog-docs) 61/61 pass; check-error-code-casing.mjs green over 3576 files
B	Breaking casing fires the mechanical rule and names the offender	Confirmed. × every registered code is SCREAMING_SNAKE → AssertionError: @objectstack/spec → AI_allowance_exhausted: expected 'AI_allowance_exhausted' to match /^[A-Z][A-Z0-9_]*$/
C	Removing a row goes red on a completeness gate	Refuted — and it is the file's own documented hole. Deleting MONGODB_MULTI_TENANT_UNSUPPORTED left both suites green (58/58); the admission rules check casing/duplication/shadowing, never emittability (see the "Retiring a code" section, and #5783 / OVERLAY_PERSISTENCE_FAILED)

Probe A is the decisive one. Landing this card would have gone green through CI with no reviewer signal that a standing ruling had been reversed. A silent green is precisely why I stopped instead of shipping it.

Report

{
  "issue": 7495,
  "outcome": "blocked",
  "branch": "claude/issue-7495-ai-quota-error-codes",
  "pr_number": null,
  "premise_check": "BROKEN — (1) no valid owner key: ERROR_CODE_LEDGER is keyed by emitting package and no framework package in this repo emits these codes (no AI/quota service exists); (2) the codes are downstream plan-gating/billing states, which the #4805 ruling (2026-08-03, re-confirmed 2026-08-09, stated in the target file's header and pinned in contract.test.ts:588) places out of scope by construction. The 2026-08-11 Option A verdict resolved the SHAPE fork and is compatible with cloud registering the same three literals in cloud's own ledger via makeApiErrorSchema.",
  "changes": [],
  "gates": {
    "error-code-ledger.test.ts": "green, unmodified (baseline 8/8)",
    "contract.test.ts": "green, unmodified",
    "error-catalog-docs.test.ts": "green, unmodified",
    "scripts/check-error-code-casing.mjs": "green over 3576 files",
    "generated_artifacts": "not run — no source change was made, so nothing generated could move"
  },
  "reverse_verification": {
    "probe_a_silent_landing": "CONFIRMED — 3 codes under a framework owner key: 61/61 pass, casing gate green. Violation invisible to CI.",
    "probe_b_casing_rule": "CONFIRMED — 'AI_allowance_exhausted' fails /^[A-Z][A-Z0-9_]*$/, named with its owner key.",
    "probe_c_completeness": "REFUTED — row removal stays green; no emittability gate exists (documented hole, #5783 precedent).",
    "cleanup": "all probes reverted; git status clean; no commit"
  },
  "changeset": {
    "file": null,
    "bump": "n/a",
    "justification": "No change landed. For the record, had it landed the lean would have been @objectstack/spec MINOR — new accepted public error-code vocabulary is an additive acceptance-surface change, and the #4805 changeset (.changeset/error-code-ledger-federation-contract.md) took minor for the same class of ledger/acceptance work."
  },
  "deviations": [
    "Did NOT implement the carded change. Registering under a fabricated owner key, or silently reversing #4805, are both outside this card's adjudication boundary — the ruling on record decided literals-vs-details, not which repo's ledger holds them.",
    "Did not open a PR: there is no change to land, and an empty/violating PR would consume a review slot."
  ],
  "findings_filed": [],
  "docs_adr_touched": false,
  "open_questions": [
    "Maintainer call needed: does the 2026-08-11 Option A ruling intend to REVERSE the #4805 federation rule for AI quota codes specifically, or does Option A land in cloud's own ledger (the reading that keeps both rulings intact)?",
    "If the reading is 'cloud's own ledger': this card closes as not-applicable and cloud#1168 absorbs the registration, with objectui#3804 unblocked immediately — the three literals are identical either way.",
    "If the reading is a genuine reversal: it needs an owner key decision (no framework package emits these), an amendment to the ledger header and the #4805 rationale, and a revisit of the contract.test.ts:588 pin whose DOWNSTREAM_CODES are the same class of literal."
  ]
}

Recommended next step: re-point the registration at cloud#1168 (cloud's own ledger + makeApiErrorSchema). That satisfies the Option A ruling in full, unblocks objectui#3804 today, and leaves #4805 standing. If the maintainer does intend a reversal, this card needs re-scoping with an owner key before any dev seat can execute it.

---

Generated by Claude Code

[os-zhuang]

Step-7 review of the blocked report — ACCEPT. Card returned to the decision inbox (spec-lane PM seat #6017, session_01PiRUoQkTSBBmpyXBY3cVn2).

The blocker holds: the #4805 federation rule (2026-08-03, re-confirmed 2026-08-09) is stated in the target file's own header and pinned at contract.test.ts:588; no framework package emits these codes, so any owner key would assert fabricated provenance; and probe A shows the registration would land CI-green with no reviewer signal — stopping instead of shipping a silent reversal of a standing ruling was the right call.

Question for the maintainer (from the report, needing your word): does the 2026-08-11 Option A ruling intend to reverse #4805 for the AI quota codes specifically, or does Option A land in cloud's own ledger via makeApiErrorSchema — the reading that keeps both rulings intact, satisfies the shape verdict in full (same three closed literals), closes this card as not-applicable, moves the registration to cloud#1168, and unblocks objectui#3804 immediately?

State executed: pm:dispatched → needs-user-decision (kept domain:spec); claim released; dev session archived (no branch pushed, clean tree).

---

Generated by Claude Code