Type the AI plane's error codes; normalize retryAfter to a Date

[jonahc44]

bool.ai threw a BoolAiError whose code was a bare string, so nothing in
the SDK described what an app could actually receive. Ten codes come back as
JSON from the plane; none were typed. And one of the two things an app most wants
to do with a failure — wait the right amount of time, then retry — had no
supported shape at all.

What's in here

All ten codes are typed. BoolAiWireErrorCode lists them with the status
each arrives on and a line on what it means: out_of_app_credits,
app_credit_daily_cap, rate_limited, payload_too_large, missing_prompt,
invalid_json, method_not_allowed, not_found, ai_unavailable, ai_failed.
BoolAiErrorCode adds "unknown_error" and stays an open union — the
gateway ships independently of this package, so an app pinned to an older SDK can
meet a code published after it, and that's a runtime case to handle rather than a
compile error at the default arm. Known codes still autocomplete and are still
checked when spelled.

Branch on code, never on status. 429 is now two conditions:
rate_limited (per-caller pacing) and app_credit_daily_cap (this app has spent
its share of the owner's credits for the day, while the pool still has credits).
Those want different copy and different retry behavior. The SDK already read
body.error at both throw sites rather than mapping from the status, so what's
new is the type and the tests that pin the distinction.

New BoolAiError.retryAfter, a Date. The field has two incompatible wire
forms — an ISO-8601 instant on the credit codes, a count of seconds on
rate_limited — and no Retry-After header on any of them. Accepting both and
exposing one means app code can compare or subtract it without knowing which code
produced it. Absent, null, negative, and unparseable all yield undefined
rather than an Invalid Date, so if (err.retryAfter) means what it looks like.

One behavior change worth reading

A failure whose body carries no readable code now surfaces as unknown_error.
It previously defaulted to ai_failed — a real code meaning the provider
request failed, credit refunded, which apps reasonably retry. The shared plane
preamble answers some 403s and 404s in text/plain, so those have no JSON to
read and were being reported as a transient provider blip. Retrying a 404 forever
was the result. A genuine 502 still arrives as ai_failed, and now only then.

Apps branching on ai_failed to drive a retry should keep doing exactly that.

Verification

Read against origin/main in the platform repo rather than trusting the
description of the wire, which was worth doing — it corrected two things:

• retryAfter can be an explicit null, not just absent (a credit code whose
  period has no known end). Now covered by a test rather than working by
  accident.
• The plane returns ten JSON codes, not thirteen. Every error: "..." in
  lib/gateway/ai-route.ts is accounted for above.

Both ISO producers use .toISOString(), so the instant form is always UTC — the
digits-only-string guard stays as a guard, not a live path.

bun test — 181 pass, 0 fail. bun run typecheck and bun run build clean;
the new types reach dist/.

Scope

Minor bump: additive types plus the one fallback change. bool.ai stays gated
server-side by the bool-ai flag, off by default, so these codes only reach apps
in workspaces opted into the battery.

Two related items are deliberately not here, because they live in the
platform repo:

• The text/plain 403/404 in the shared plane preamble. Fixing it at the source
  touches the GA entities and users planes, so it belongs in its own change with
  its own tests rather than riding along behind a flag-gated one.
• The starter-template version floor that gates the current codes, the way
  LIVE_SDK_CANARY_SINCE gates live spellings. Per the NOTE FOR THE SDK in
  ai-route.ts, that floor is the real gate before the battery flag can go on
  for real users, and it needs a published SDK version to point at — this one.

Also noted while reading: the comment above the app_credit_daily_cap branch in
ai-route.ts says retryAfter is an ISO timestamp on every code in the plane.
That's true of the two credit codes but not of rate_limited, ~80 lines above in
the same file. Worth a one-line fix upstream; the normalization here handles it
either way.

🤖 Generated with Claude Code

[jonahc44]

Added the runtime list and the guard, per review.

BOOL_AI_WIRE_ERROR_CODES is now the single source the union derives from ((typeof BOOL_AI_WIRE_ERROR_CODES)[number]) rather than a second list beside a hand-written union — two lists would be two things to update, and the drift would stay invisible until an app hit a code that was in one but not the other.

isBoolAiWireErrorCode() narrows the open union to the closed set, which is what actually buys typo-catching: inside the guard a switch is exhaustiveness-checked, so a missing or misspelled case is a compile error instead of an arm that silently never runs.

Two tests worth calling out:

• The exhaustiveness check is verified to be load-bearing, not decorative — removing a single case fails tsc with Type '"ai_failed"' is not assignable to type 'never'. I checked that by actually deleting a case and confirming the failure, then restoring it.
• The list is pinned against ai-route.ts, so adding a code to the gateway fails here and points at the array to update.

184 pass, 0 fail; typecheck and build clean, both symbols reach dist/.