@lunora/errors 1.0.0-alpha.5 → 1.0.0-alpha.50

package/dist/index.d.ts

@@ -1,18 +1,5 @@
-/**
-* The central Lunora error catalog — the single source of truth mapping a
-* machine-readable `code` to its transport `status`, a short human `title`, and
-* (where useful) an actionable Markdown `hint` plus a `docsUrl`.
-*
-* This table is consumed everywhere an error is surfaced: the runtime/DO wire
-* mappers (status), the client SDK (code discrimination), the CLI renderer and
-* the Vite overlay (hint), and the Studio UI (title + hint + docs link). It also
-* absorbs the former `@lunora/codegen` "solutions" table (see {@link MESSAGE_SOLUTIONS})
-* so codegen build-time errors — which are thrown as plain messages into
-* generated code and lose their class identity before a consumer sees them —
-* keep their message-matched hints.
-*/
 /** Markdown hint: a single string or an array of lines. Shape matches `@visulima/error`'s `hint`. */
-type ErrorHint = string | string[];
+type ErrorHint = string | ReadonlyArray<string>;
 /** A catalog entry: the fixed metadata for one error `code`. */
 interface ErrorCatalogEntry {
   /** Optional URL to deeper docs for this error. */
@@ -20,11 +7,11 @@ interface ErrorCatalogEntry {
   /** Optional actionable fix, authored as Markdown (rendered by CLI/overlay/Studio). */
   hint?: ErrorHint;
   /**
-  * When `true`, this code's `message` must NOT cross the wire — an internal
-  * failure or unhandled invariant may carry SQL fragments, file paths, or
-  * internal identifiers. The transport mappers emit a generic message for
-  * these (and log the real one server-side). See {@link isInternalCode}.
-  */
+   * When `true`, this code's `message` must NOT cross the wire — an internal
+   * failure or unhandled invariant may carry SQL fragments, file paths, or
+   * internal identifiers. The transport mappers emit a generic message for
+   * these (and log the real one server-side). See {@link isInternalCode}.
+   */
   internal?: boolean;
   /** HTTP/RPC status this code maps to on the wire. */
   status: number;
@@ -32,10 +19,10 @@ interface ErrorCatalogEntry {
   title: string;
 }
 /**
-* Every well-known Lunora error code. Domain packages may throw additional
-* codes (passing an explicit `status`); those are added here as their package is
-* migrated. The keys of this object form the {@link LunoraErrorCode} union.
-*/
+ * Every well-known Lunora error code. Domain packages may throw additional
+ * codes (passing an explicit `status`); those are added here as their package is
+ * migrated. The keys of this object form the {@link LunoraErrorCode} union.
+ */
 declare const ERROR_CATALOG: {
   readonly BAD_REQUEST: {
     readonly status: 400;
@@ -78,7 +65,8 @@ declare const ERROR_CATALOG: {
   readonly NOT_IMPLEMENTED: {
     readonly status: 501;
     readonly title: "Not implemented";
-  }; /** RPC/REST dispatch codes emitted by the runtime + Durable Object router. */
+  };
+  /** RPC/REST dispatch codes emitted by the runtime + Durable Object router. */
   readonly FUNCTION_NOT_FOUND: {
     readonly status: 404;
     readonly title: "Function not found";
@@ -90,7 +78,8 @@ declare const ERROR_CATALOG: {
   readonly PAYLOAD_TOO_LARGE: {
     readonly status: 413;
     readonly title: "Payload too large";
-  }; /** Free-form internal failure — redacted to a generic message on the wire. */
+  };
+  /** Free-form internal failure — redacted to a generic message on the wire. */
   readonly INTERNAL: {
     readonly internal: true;
     readonly status: 500;
@@ -130,10 +119,34 @@ declare const ERROR_CATALOG: {
     readonly status: 500;
     readonly title: "Run depth exceeded";
   };
+  /**
+   * A `query` context reached for `ctx.runMutation` / `ctx.runAction`. The
+   * generated context object installs all three `run*` methods on every kind, so
+   * the TYPE is the only thing that stops a read-only handler from writing — and
+   * a cast walks straight past it, inside a subscription re-run that may execute
+   * many times per write. Deliberately NOT `internal`: the message names the
+   * function that was reached for, and it is a programming error the developer
+   * needs to read.
+   */
+  readonly RUN_KIND_FORBIDDEN: {
+    readonly status: 500;
+    readonly title: "Function kind may not be composed from a query";
+  };
+  readonly TRANSACTION_LIMIT_EXCEEDED: {
+    readonly hint: readonly ["A single mutation may only read and write a bounded amount before it is stopped.", "", "Narrow the read with an index (`.withIndex(...)`) instead of scanning the table, or split the write across several mutations — for a large backfill use `defineMigration` + `lunora migrate up`, which batches and checkpoints for you.", "", "The ceilings are deliberately conservative — they exist to stop one request taking down the whole shard. A deployment that genuinely needs bigger transactions can raise them by overriding the `transactionLimits()` seam on its generated shard class."];
+    readonly status: 413;
+    readonly title: "Transaction limit exceeded";
+  };
   readonly MIGRATION_NOT_FOUND: {
     readonly status: 404;
     readonly title: "Data migration not found";
   };
+  /** `@lunora/d1`'s `MigrationRunner` refused to run: an applied migration's SQL changed, or the tracking table cannot say which migrations already ran. */
+  readonly MIGRATION_DRIFT: {
+    readonly hint: readonly ["An applied SQL migration is never re-run, so the runner stopped before applying anything.", "", "- **Its text changed after it ran:** revert the edit and put the change in a new migration. If the edit is inert (a comment, whitespace, line endings), record the new hash with the `UPDATE` the message prints.", "- **Tracking rows predate versions and match no migration:** set each row's `version` with the `UPDATE` the message prints, so the runner can tell what already ran."];
+    readonly status: 409;
+    readonly title: "Migration drift";
+  };
   readonly UNKNOWN_TABLE: {
     readonly status: 404;
     readonly title: "Unknown table";
@@ -150,14 +163,47 @@ declare const ERROR_CATALOG: {
     readonly status: 503;
     readonly title: "Shard unavailable";
   };
+  /** A fan-out shard call exceeded the coordinator's per-shard deadline. */
+  readonly SHARD_TIMEOUT: {
+    readonly status: 504;
+    readonly title: "Shard timeout";
+  };
+  /** A fan-out shard call answered with a non-2xx status; the status is in the message, the body is not. */
+  readonly SHARD_HTTP_ERROR: {
+    readonly status: 502;
+    readonly title: "Shard HTTP error";
+  };
+  /** The shard could not write a subscription's attachment to storage, so the subscription was refused. */
+  readonly SUBSCRIPTION_PERSIST_FAILED: {
+    readonly status: 500;
+    readonly title: "Subscription persist failed";
+  };
+  /** A connection asked for more concurrent subscriptions than the shard allows. */
+  readonly TOO_MANY_SUBSCRIPTIONS: {
+    readonly status: 429;
+    readonly title: "Too many subscriptions";
+  };
   readonly OFFLINE_IDENTITY_CHANGED: {
     readonly status: 409;
     readonly title: "Offline identity changed";
-  }; /** Package-specific codes. Build-time-only — never cross the RPC wire, so deliberately not `internal`. */
+  };
+  /** A replayed write named, in `x-lunora-expect-subject`, a different user than the request resolved to. */
+  readonly IDENTITY_MISMATCH: {
+    readonly hint: readonly ["A write queued offline was replayed on a session that now belongs to someone else (a sign-out, or another user's sign-in, while it waited), so the worker refused it rather than commit it as them.", "", "`@lunora/client` re-resolves the session on this refusal and settles the write itself. If every replay is refused while the same user stays signed in, your worker's `resolveIdentity` returns a different `userId` than better-auth's `user.id`, or the RPC request carries no session cookie."];
+    readonly status: 409;
+    readonly title: "Session changed since the write was queued";
+  };
+  /** Package-specific codes. Build-time-only — never cross the RPC wire, so deliberately not `internal`. */
   readonly CODEGEN_DIAGNOSTIC: {
     readonly status: 500;
     readonly title: "Codegen diagnostic";
   };
+  /** Build-time-only (codegen): `.jurisdiction()` would move DO-backed auth to a new, empty object without `{ pinAuth: true }`. */
+  readonly JURISDICTION_MOVE: {
+    readonly hint: readonly ["The schema declares `.jurisdiction(...)` and the project has DO-backed auth (`.auth({ namespace })`). Pinning the auth object to the jurisdiction resolves it to a new, empty one: every user, account and session stays in the unpinned object until copied across. Voice sessions are pinned without an acknowledgement: they store nothing, and their transcripts are rows in the already-pinned shards.", "", "Acknowledge with `.jurisdiction(\"eu\", { pinAuth: true })` and deploy, then copy the auth tables across with the `__lunora_admin__:copyAuthToJurisdiction` admin op and, once the counts check out, purge the unpinned copy with `__lunora_admin__:purgeUnpinnedAuth` (see [Pinning auth and voice](/docs/concepts/data-residency#pinning-auth-and-voice)). For D1-mode auth the acknowledgement changes nothing."];
+    readonly status: 422;
+    readonly title: "Unacknowledged jurisdiction move";
+  };
   /** Build-time-only — never crosses the RPC wire, so deliberately not `internal`. */
   readonly SCHEMA_SNAPSHOT_PARSE: {
     readonly status: 500;
@@ -176,14 +222,38 @@ declare const ERROR_CATALOG: {
     readonly title: "Auth headers missing";
   };
   /**
-  * Upstream Cloudflare API failures surfaced from an action. The message
-  * carries the upstream response body (Cloudflare's own error text — trusted
-  * infra, not user input), so it is echoed rather than redacted. `status`
-  * here is a fallback; each throw passes the actual upstream HTTP status.
-  */
-  readonly ANALYTICS_SQL_ERROR: {
+   * Signup rejected by `@lunora/auth`'s email-domain gate — a disposable/throwaway
+   * provider (or a caller deny-list hit). Client-safe: the message names only the
+   * offending domain class, never a secret, so it is echoed rather than redacted.
+   */
+  readonly EMAIL_DOMAIN_BLOCKED: {
+    readonly hint: readonly ["This address's domain is on the disposable/throwaway blocklist (or your configured deny-list).", "", "Sign up with a permanent mailbox. To tune the policy, pass `blockDisposable` / `allowDomains` / `denyDomains` in the `EmailGateConfig` you hand `assertEmailAllowed` / `classifyEmail` / `emailGateMiddleware` (`@lunora/auth/email-guard`)."];
+    readonly status: 400;
+    readonly title: "Email domain not allowed";
+  };
+  /**
+   * Opt-in MX verification (`@lunora/auth/email-guard`, `mx: true`) found no mail
+   * exchanger for the address's domain, so mail to it would never deliver.
+   * Client-safe: names only the domain, no secret.
+   */
+  readonly EMAIL_UNDELIVERABLE: {
+    readonly hint: readonly ["The address's domain publishes no MX (or fallback A/AAAA) records, so it can't receive mail.", "", "Check for a typo in the domain. MX verification is opt-in (`mx: true`) and needs DNS — leave it off on the edge path if DNS is unavailable."];
+    readonly status: 400;
+    readonly title: "Email domain cannot receive mail";
+  };
+  /**
+   * Upstream Cloudflare API failures surfaced from an action. The message
+   * carries the upstream response body (Cloudflare's own error text — trusted
+   * infra, not user input), so it is echoed rather than redacted. `status`
+   * here is a fallback; each throw passes the actual upstream HTTP status.
+   */
+  readonly ANALYTICS_SQL_QUERY_ERROR: {
     readonly status: 502;
-    readonly title: "Analytics Engine SQL API error";
+    readonly title: "Analytics SQL query error";
+  };
+  readonly BROWSER_RUN_ERROR: {
+    readonly status: 502;
+    readonly title: "Browser Run API error";
   };
   readonly R2_SQL_ERROR: {
     readonly status: 502;
@@ -193,25 +263,783 @@ declare const ERROR_CATALOG: {
     readonly status: 502;
     readonly title: "Cloudflare Workflows REST API error";
   };
+  /** Server-side payment wiring is wrong or missing (`webhook secret not configured`, a duplicate/absent adapter). A 500 that names internal configuration — redact on the wire. */
+  readonly CONFIG_INVALID: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Payment configuration invalid";
+  };
+  /** Arithmetic across two currencies. The message names only the two currency codes the caller supplied. */
+  readonly CURRENCY_MISMATCH: {
+    readonly status: 400;
+    readonly title: "Currency mismatch";
+  };
+  /**
+   * A payment provider refused or answered unusably. NOT `internal`, matching
+   * the upstream-API 502s above: the messages are fixed capability text
+   * ("<provider> does not support refundPayment") or echo back the malformed
+   * id the CALLER passed in, so none of them reveals state the caller did not
+   * already have.
+   */
+  readonly PROVIDER_ERROR: {
+    readonly status: 502;
+    readonly title: "Payment provider error";
+  };
+  /**
+   * Webhook rejections, addressed to the provider posting the hook, so NOT
+   * `internal`. Five of the six mint sites are fixed strings ("no matching
+   * signature", "missing creem-signature header"). The sixth,
+   * `providers/stripe.ts`, passes the Stripe SDK's own verification message
+   * through — "No signatures found matching…", "Timestamp outside the
+   * tolerance zone" — which still describes the REQUEST the poster sent, not
+   * this server's state. Keep that true of anything added here: an upstream
+   * message is only safe to forward while it is about the caller's input.
+   */
+  readonly WEBHOOK_EVENT_ID_MISSING: {
+    readonly status: 400;
+    readonly title: "Webhook event id missing";
+  };
+  readonly WEBHOOK_SIGNATURE_INVALID: {
+    readonly status: 400;
+    readonly title: "Webhook signature invalid";
+  };
+  readonly WEBHOOK_TIMESTAMP_INVALID: {
+    readonly status: 400;
+    readonly title: "Webhook timestamp outside tolerance";
+  };
+  /**
+   * Admin-gated `/_lunora/admin/*` and `__lunora_admin__:*` codes. Registered
+   * here (plan 230, ERRORS-01) after an audit found them minted with `code:`
+   * but never added to the catalog — `isInternalCode` fails OPEN for an
+   * unregistered code, so each was already echoing its message unredacted.
+   * Below is that audit's verdict per code, not a blanket allow: most of these
+   * are deliberately actionable ("you forgot to configure X") and stay
+   * client-safe; the ones that can carry backend detail are flagged
+   * `internal: true` individually, with the reason noted alongside.
+   */
+  readonly ADMIN_FORBIDDEN: {
+    readonly status: 403;
+    readonly title: "Admin access forbidden";
+  };
+  readonly ADMIN_TOKEN_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Admin token not configured";
+  };
+  /**
+   * Deliberately NOT `internal`, unlike its 500 neighbours: the message is
+   * fixed configuration guidance that names no table, path or identifier, and
+   * redacting it to "Internal error" would strip the only thing this code
+   * exists to deliver. It is raised before any query runs, so there is no
+   * backend detail to leak.
+   */
+  readonly AUTH_MIGRATOR_UNSUPPORTED: {
+    readonly hint: readonly ["better-auth migrates only through its Kysely adapter, so `ensureMigrated` / `compileMigrationsSql` need the raw D1 binding as `database` — a custom adapter (`lunoraD1Adapter`, `lunoraAuthAdapter`, `lunoraDoAdapter`) cannot be migrated through, and neither can an absent `database`.", "", "Build a SECOND, migration-only instance over the raw binding — `createAuth({ ...options, database: env.DB })` — and hand that one to `ensureMigrated`. Keep the adapter on the instance that serves requests: the adapter exists to dodge a dev-runner hang in `$context`, which the migration instance never resolves.", "", "To compile the SQL off-platform (`compileMigrationsSql`), diff against an empty local database — `new DatabaseSync(':memory:')` from `node:sqlite` — rather than passing no `database` at all."];
+    readonly status: 500;
+    readonly title: "Auth migrator cannot drive the configured database";
+  };
+  readonly AUTH_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Auth admin not configured";
+  };
+  readonly AUTH_OP_NOT_SUPPORTED: {
+    readonly status: 400;
+    readonly title: "Auth admin operation not supported";
+  };
+  /**
+   * MCP OAuth wiring mistakes, raised while the auth instance or MCP route is
+   * built (plan 461). Not `internal`, for the same reason as the auth migrator
+   * entry above: the message is fixed configuration guidance (at most echoing
+   * the app's own configured `resource` value), raised before any request is
+   * served, so it carries no backend detail and redacting it would hide the fix.
+   */
+  readonly AUTH_CIMD_FETCH_NOT_PUBLIC: {
+    readonly hint: "Add \"global_fetch_strictly_public\" to \"compatibility_flags\" in wrangler.jsonc, so CIMD metadata fetches cannot reach private addresses. `lunora doctor` reports it as `cimd-fetch-not-strictly-public`.";
+    readonly status: 500;
+    readonly title: "CIMD transport needs the global_fetch_strictly_public flag";
+  };
+  readonly AUTH_MCP_RESOURCE_AMBIGUOUS: {
+    readonly hint: "Use `mcp` from \"@lunora/auth/plugins\" (not `@better-auth/mcp`) and pass the plugin object as is: it records its `resource`, which the worker needs to serve the protected-resource metadata when the provider names several resources.";
+    readonly status: 500;
+    readonly title: "MCP resource cannot be told apart from the provider's other resources";
+  };
+  readonly AUTH_MCP_RESOURCE_INVALID: {
+    readonly hint: "Pass `resource` to `requireMcpAuth` (and `mcp()`) as the absolute URL of the MCP route, e.g. `https://app.example.com/mcp`: issued tokens are audience-bound to it.";
+    readonly status: 500;
+    readonly title: "MCP resource missing or not an absolute URL";
+  };
+  readonly MCP_STEP_UP_MISCONFIGURED: {
+    readonly hint: "Give `createAuthedMcpFetchHandler`'s `stepUp` a non-empty `scope` (such as `lunora:write`) and a `challenge` (`createInsufficientScopeError` from `@lunora/auth/plugins`), or leave `stepUp` out.";
+    readonly status: 500;
+    readonly title: "MCP step-up misconfigured";
+  };
+  readonly BACKUP_NOT_CONFIGURED: {
+    readonly status: 500;
+    readonly title: "Scheduled backup not configured";
+  };
+  readonly BACKUP_RETENTION_NOT_CONFIGURED: {
+    readonly hint: readonly ["`lunora backup prune` removes snapshots past the retention window, and this worker has no window: set `backupRetain` (how many to keep) and `backupCron` (which decides whose snapshots retention owns) on `createWorker`.", "", "Nothing was deleted. A default is deliberately not invented here — retention deleting on its own is exactly what this command exists to replace."];
+    readonly status: 400;
+    readonly title: "Backup retention window not configured";
+  };
+  readonly BACKUP_TOO_LARGE: {
+    readonly hint: readonly ["The scheduled backup is assembled inside the Worker isolate, so it caps the snapshot it will build. Nothing was written.", "", "The cap is on the NDJSON, not on peak memory: the export fan-out resolves every shard's rows before the first row is encoded, so a snapshot under the cap can still exhaust the isolate. It is set well below the isolate's limit for that reason.", "", "Narrow the snapshot with `backupTables`, or take this backup off-platform with `lunora backup create --bucket`, which runs on a machine rather than in an isolate. Backing up more often does not help — every run is a full snapshot."];
+    readonly status: 507;
+    readonly title: "Backup too large to assemble in a Worker";
+  };
+  readonly CRON_JOBS_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Cron jobs not configured";
+  };
+  readonly CRON_JOB_NOT_FOUND: {
+    readonly status: 404;
+    readonly title: "Cron job not found";
+  };
+  readonly EXPORT_SHARD_FAILED: {
+    readonly hint: readonly ["One or more shards failed to export, so the snapshot would have been short. Nothing is written when this fires — a partial export must never be mistaken for a complete one.", "", "The message names each failed shard key and its error. Re-run the export once those shards are reachable; a shard that fails repeatedly is usually over the per-request memory budget, which `backupTables` narrows."];
+    readonly status: 502;
+    readonly title: "Export failed on one or more shards";
+  };
+  readonly EXPORT_TAP_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Export tap not configured";
+  };
+  readonly FUNCTIONS_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Functions registry not configured";
+  };
+  readonly GLOBALS_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Global-table introspector not configured";
+  };
+  readonly ID_COLLISION: {
+    readonly hint: readonly ["The imported row carries an `_id` that is already held by a DIFFERENT table in this shard. Ids are per-table, so inserting it would leave two tables claiming one id and make a later lookup resolve to whichever one it reached first.", "", "This is reported per row rather than aborting the import: the remaining rows still apply. Re-mint the id on the source side, or import that table into a shard that does not already hold it."];
+    readonly status: 409;
+    readonly title: "Document id already belongs to another table";
+  };
+  readonly KV_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "KV introspector not configured";
+  };
+  readonly MIGRATION_ID_REQUIRED: {
+    readonly status: 400;
+    readonly title: "Migration id required";
+  };
+  readonly PITR_UNAVAILABLE: {
+    readonly status: 409;
+    readonly title: "Point-in-time recovery unavailable";
+  };
+  readonly SCHEDULER_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Scheduler not configured";
+  };
+  readonly STORAGE_CHECKSUM_MISMATCH: {
+    readonly hint: readonly ["The upload body did not match the declared `expectedSize` or `expectedSha256`, so nothing was written — this check fails closed.", "", "Re-read the bytes from the source export and retry the transfer. A persistent mismatch means the source blob is corrupt or truncated; fix the export rather than bypassing the check."];
+    readonly status: 400;
+    readonly title: "Storage checksum mismatch";
+  };
+  readonly STORAGE_DELETE_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Storage delete not configured";
+  };
+  readonly STORAGE_DOWNLOAD_NOT_CONFIGURED: {
+    readonly hint: readonly ["`GET /_lunora/admin/storage/object` needs a `storageDownload` function on the worker. The generated app worker wires it up; a hand-written `createWorker({ ... })` has to pass `(key, opts) => pick(opts?.bucket).download(key)` — forwarding `opts.bucket` to the right bucket, and wrapping rather than passing `createStorage(...).download` itself, whose second parameter is a byte range.", "", "Without it a bucket-backed `lunora backup restore --bucket` cannot read the snapshot. The object is still readable out of band with `wrangler r2 object get`."];
+    readonly status: 400;
+    readonly title: "Storage download not configured";
+  };
+  readonly STORAGE_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Storage not configured";
+  };
+  readonly STORAGE_OBJECT_NOT_FOUND: {
+    readonly status: 404;
+    readonly title: "Storage object not found";
+  };
+  readonly STORAGE_UPLOAD_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Storage upload not configured";
+  };
+  readonly STORAGE_URL_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Storage signed URL not configured";
+  };
+  readonly RAG_DIMENSION_MISMATCH: {
+    readonly hint: readonly ["A stored vector and the query embedding have different widths, so they cannot be compared.", "", "This is what changing a RAG index's `embeddingModel` (or a provider's `dimensions` option) without reindexing looks like. Either put the previous model back, or reindex the namespace under the new one — bump `embeddingModelVersion` so the index rebuilds instead of mixing widths."];
+    readonly status: 409;
+    readonly title: "Embedding dimension mismatch";
+  };
+  readonly VECTORS_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Vector index introspector not configured";
+  };
+  readonly VECTOR_QUERY_UNSUPPORTED: {
+    readonly status: 400;
+    readonly title: "Vector index querying not enabled";
+  };
+  readonly WORKFLOWS_NOT_CONFIGURED: {
+    readonly status: 501;
+    readonly title: "Workflows not configured";
+  };
+  /** The auth/security audit read plane (`__lunora_admin__:getAuthAuditLog`). */
+  readonly AUTH_AUDIT_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Auth audit reader not configured";
+  };
+  /**
+   * Backend/DB failure reading the auth audit store. The throw site already
+   * keeps the message generic and logs the real error server-side only — flagged
+   * `internal: true` anyway as the deliberate posture for "a backend read
+   * failed", so a future edit that inlines the driver error can't leak it.
+   */
+  readonly AUTH_AUDIT_READ_FAILED: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Auth audit read failed";
+  };
+  /** Copying DO-backed auth into its jurisdiction-pinned object (`__lunora_admin__:copyAuthToJurisdiction` / `purgeUnpinnedAuth`). */
+  readonly AUTH_MOVE_NOT_CONFIGURED: {
+    readonly hint: "The copy needs DO-backed auth (`.auth({ namespace })`) pinned with `.jurisdiction(…, { pinAuth: true })`, and the auth object's `internalSecret` set.";
+    readonly status: 400;
+    readonly title: "Auth jurisdiction move not configured";
+  };
+  readonly AUTH_MOVE_TARGET_NOT_EMPTY: {
+    readonly hint: "The pinned auth object holds users the copy did not write (someone signed up there), so copying into it would merge two user bases. Pass `force: true` to copy anyway: a copied row that collides with one of the pinned object's rows is left out and counted under `conflicts`.";
+    readonly status: 409;
+    readonly title: "Pinned auth object is not empty";
+  };
+  readonly AUTH_MOVE_CONFLICT: {
+    readonly hint: "A copied row has the same key or unique value (such as an email) as a row the pinned auth object holds on its own, or the pinned object changed a row the source changed too. Nothing from that page was written. Pass `force: true` to keep the pinned object's rows and count the collisions under `conflicts`.";
+    readonly status: 409;
+    readonly title: "Auth copy conflict";
+  };
+  readonly AUTH_MOVE_SOURCE_CHANGED: {
+    readonly hint: "The un-pinned auth object changed after the copy read it (an update, a delete, or a new row), for example during a gradual rollout or a rollback. Run the copy again: it reconciles the changed tables. Then purge.";
+    readonly status: 409;
+    readonly title: "Un-pinned auth object changed since the copy";
+  };
+  readonly AUTH_MOVE_SOURCE_PURGED: {
+    readonly hint: "The un-pinned auth object was already purged. Its tables may exist again (a rollback served requests there), but they hold only rows written since, so the copy refuses rather than read them as deletions and remove the pinned object's users. Nothing is left to copy.";
+    readonly status: 409;
+    readonly title: "Un-pinned auth object already purged";
+  };
+  readonly AUTH_MOVE_INCOMPLETE: {
+    readonly hint: "Run `__lunora_admin__:copyAuthToJurisdiction` until it answers `done: true`, check the per-table counts, then purge.";
+    readonly status: 409;
+    readonly title: "Auth copy not finished";
+  };
+  /**
+   * A move step failed inside an auth object. Not `internal`: the message is built by
+   * the object from the step, the table and a SQLite error class, never row data, so
+   * the admin caller sees why; the object logs the full error.
+   */
+  readonly AUTH_MOVE_FAILED: {
+    readonly hint: "The message names the step, the table and the class of the SQLite error; the auth object's log has the full error. The copy resumes where it stopped once the cause is fixed.";
+    readonly status: 500;
+    readonly title: "Auth jurisdiction move failed";
+  };
+  /**
+   * Cron-job codes. The `*_NOT_STATIC` / `_INVALID` family are codegen
+   * build-time diagnostics — like `CODEGEN_DIAGNOSTIC`, they're thrown as plain
+   * messages into the CLI/Vite-overlay output, never cross the RPC wire, and are
+   * deliberately not `internal` (the message IS the fix). `CRON_JOB_FAILED` is
+   * the one runtime-reachable code in this family — its message interpolates
+   * binding/function/job names from the deployment, so it is flagged internal.
+   */
+  readonly CRON_EXPR_INVALID: {
+    readonly status: 500;
+    readonly title: "Invalid cron expression";
+  };
+  readonly CRON_EXPR_NOT_STATIC: {
+    readonly status: 500;
+    readonly title: "Cron expression is not statically analyzable";
+  };
+  readonly CRON_JOB_FAILED: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Cron job failed";
+  };
+  readonly CRON_NAME_NOT_STATIC: {
+    readonly status: 500;
+    readonly title: "Cron job name is not statically analyzable";
+  };
+  readonly CRON_NON_STATIC_FN: {
+    readonly status: 500;
+    readonly title: "Cron function reference is not statically analyzable";
+  };
+  readonly CRON_NON_STATIC_VALUE: {
+    readonly status: 500;
+    readonly title: "Cron value is not statically analyzable";
+  };
+  readonly CRON_SCHEDULE_INVALID: {
+    readonly status: 500;
+    readonly title: "Invalid cron schedule";
+  };
+  readonly CRON_SCHEDULE_NOT_STATIC: {
+    readonly status: 500;
+    readonly title: "Cron schedule is not statically analyzable";
+  };
+  readonly DUPLICATE_CRON_NAME: {
+    readonly status: 500;
+    readonly title: "Duplicate cron job name";
+  };
+  /** More codegen build-time diagnostics — see the cron-family comment above; same reasoning applies. */
+  readonly DUPLICATE_AGENT_CLASS: {
+    readonly status: 500;
+    readonly title: "Duplicate agent generated class name";
+  };
+  readonly DUPLICATE_AGENT_NAME: {
+    readonly status: 500;
+    readonly title: "Duplicate agent name";
+  };
+  readonly DUPLICATE_MIGRATION_ID: {
+    readonly status: 500;
+    readonly title: "Duplicate migration id";
+  };
+  readonly DUPLICATE_QUEUE_BINDING: {
+    readonly status: 500;
+    readonly title: "Duplicate queue binding";
+  };
+  readonly DUPLICATE_QUEUE_NAME: {
+    readonly status: 500;
+    readonly title: "Duplicate queue name";
+  };
+  readonly DUPLICATE_WORKFLOW_CLASS: {
+    readonly status: 500;
+    readonly title: "Duplicate workflow generated class name";
+  };
+  readonly MIGRATION_ID_NOT_STATIC: {
+    readonly status: 500;
+    readonly title: "Migration id is not statically analyzable";
+  };
+  readonly NAMESPACE_COLLISION: {
+    readonly status: 500;
+    readonly title: "Function namespace collision";
+  };
+  /**
+   * `@lunora/runtime`'s dispatch/security-boundary codes — RPC/HTTP entry, not
+   * admin-gated. Fixed, non-sensitive messages throughout, so none are `internal`.
+   */
+  readonly BAD_ROW: {
+    readonly status: 400;
+    readonly title: "Malformed import row";
+  };
+  readonly BAD_SUBSCRIPTION_ARGS: {
+    readonly status: 400;
+    readonly title: "Invalid subscription arguments";
+  };
+  readonly BATCH_LIMIT_EXCEEDED: {
+    readonly status: 400;
+    readonly title: "Batch limit exceeded";
+  };
+  readonly CROSS_SHARD_RANK_UNSUPPORTED: {
+    readonly status: 400;
+    readonly title: "Cross-shard rank() is unsupported";
+  };
+  /**
+   * The `/_lunora/scheduler/dispatch` entry rejected the request's own
+   * signature/bearer — a worker/scheduler MISCONFIGURATION (missing, wrong, or
+   * rotated `LUNORA_SCHEDULER_SECRET` / `LUNORA_ADMIN_TOKEN`), not a verdict on
+   * the function being dispatched. Distinct from `FORBIDDEN`/`FORBIDDEN_SHARD`
+   * because dispatch consumers classify a 403 as deterministic and stop
+   * retrying: an auth failure clears the moment the secret is fixed, so it must
+   * stay retryable or every queued message drains into the void while the
+   * credential is wrong. See `isDeterministicDispatchFailure` in
+   * `@lunora/dispatch`.
+   */
+  readonly DISPATCH_UNAUTHENTICATED: {
+    readonly hint: "The scheduler could not authenticate to the worker. Check that `LUNORA_SCHEDULER_SECRET` matches on both sides, or that `LUNORA_ADMIN_TOKEN` is set and current.";
+    readonly status: 403;
+    readonly title: "Dispatch caller not authenticated";
+  };
+  /**
+   * A dispatch arrived carrying an `x-lunora-mutation-id` whose handler is
+   * ALREADY executing in the shard, on the ungated (non-mutation) path where
+   * nothing serialises the two. The shard declines the second delivery rather
+   * than running it alongside the first.
+   *
+   * Deliberately a `409` and deliberately NOT one of `@lunora/dispatch`'s
+   * `DETERMINISTIC_DISPATCH_STATUSES`: the refusal is about WHEN the request
+   * arrived, not about the request. It clears on its own the moment the first
+   * attempt settles — at which point the same id replays into the dedup row
+   * and is served its cached result — so every caller (the scheduler's retry
+   * ladder, a queue consumer, a workflow step) must keep retrying it.
+   */
+  readonly DISPATCH_IN_PROGRESS: {
+    readonly hint: "A dispatch with this idempotency id is still running on the shard. Retry it; once the first attempt settles the same id is served from the replay cache.";
+    readonly status: 409;
+    readonly title: "Dispatch already in progress";
+  };
+  readonly FORBIDDEN_FANOUT: {
+    readonly status: 403;
+    readonly title: "Fan-out forbidden";
+  };
+  readonly GLOBAL_SEARCH_SCORES_UNSUPPORTED: {
+    readonly status: 400;
+    readonly title: "collectWithScores() is unsupported on a global table";
+  };
+  readonly FORBIDDEN_ORIGIN: {
+    readonly status: 403;
+    readonly title: "Origin forbidden";
+  };
+  readonly FORBIDDEN_SHARD: {
+    readonly status: 403;
+    readonly title: "Shard access forbidden";
+  };
+  readonly GLOBAL_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Global table import not configured";
+  };
+  readonly INVALID_INPUT: {
+    readonly status: 400;
+    readonly title: "Invalid input";
+  };
+  /** A caller-supplied `RunOptions.id` that is not a safe key segment. NOT internal: the message is fixed guidance about the caller's own argument, and withholding it would leave them guessing at a 400. */
+  readonly INVALID_SCHEDULE_ID: {
+    readonly status: 400;
+    readonly title: "Invalid schedule id";
+  };
+  readonly RATE_LIMITED: {
+    readonly status: 429;
+    readonly title: "Rate limited";
+  };
+  /**
+   * A read replica could not answer at the freshness the caller required. `421`
+   * rather than an error class: it is a ROUTING verdict the runtime turns into
+   * one retry against the owner, and a caller never sees it.
+   */
+  readonly REPLICA_NOT_READY: {
+    readonly status: 421;
+    readonly title: "Replica not caught up";
+  };
+  /** A write reached a read replica. Same `421` routing verdict — writes belong to the owner. */
+  readonly REPLICA_READ_ONLY: {
+    readonly status: 421;
+    readonly title: "Replica is read-only";
+  };
+  /**
+   * A search index is provisioned but still covers only part of its table, so
+   * the read refuses rather than answering from the indexed prefix.
+   *
+   * `503` and retryable, but deliberately NOT `SERVICE_UNAVAILABLE`: nothing is
+   * down. One index on one table is warming, every other read is fine, and the
+   * backfill advances on each read — so a caller that retries makes progress,
+   * where a generic outage code invites it to back off. The message names both
+   * exits (wait, or run the `backfillSearch` admin op).
+   */
+  readonly SEARCH_INDEX_BUILDING: {
+    readonly status: 503;
+    readonly title: "Search index is still building";
+  };
+  /** Thrown by `@lunora/auth` (Turnstile) and `@lunora/ratelimit` — an upstream dependency didn't respond. Fixed, safe message. */
+  readonly SERVICE_UNAVAILABLE: {
+    readonly status: 503;
+    readonly title: "Service unavailable";
+  };
+  /**
+   * A shape was declared over, or whose predicate joins, a `.memory()` table. Refused at subscribe, because
+   * the poke path replicates from `__cdc_log` and a memory table is deliberately
+   * never appended to it — so the shape would seed once and then stay frozen
+   * while the table changed underneath it. Same registration-time refusal as
+   * `SHAPE_CROSS_SHARD_JOIN`, for the same reason: the diff can never move.
+   */
+  readonly SHAPE_MEMORY_TABLE: {
+    readonly status: 400;
+    readonly title: "Shape over a memory table is unsupported";
+  };
+  readonly SHAPE_CROSS_SHARD_JOIN: {
+    readonly status: 400;
+    readonly title: "Shape cross-shard join is unsupported";
+  };
+  readonly UNAUTHENTICATED: {
+    readonly status: 401;
+    readonly title: "Unauthenticated";
+  };
+  /**
+   * The client could not decode a frame the server sent for a subscription.
+   *
+   * `502` because the failure is upstream of the caller: their query was valid
+   * and the payload that came back was not readable. Delivered to the
+   * subscription's `onError` rather than thrown, so one bad frame cannot escape
+   * the socket listener and abort every other subscription on the connection —
+   * which is what it did before, while the status indicator still read
+   * `connected` and the cursor silently stopped advancing.
+   */
+  readonly WIRE_DECODE_FAILED: {
+    readonly status: 502;
+    readonly title: "Could not decode a server frame";
+  };
+  /**
+   * A function's RETURN value cannot be carried by the wire codec — a class
+   * instance (`Decimal`, an ORM entity, `Temporal.*`, `RegExp`, `Headers`), or
+   * nesting past the codec's depth cap.
+   *
+   * Deliberately NOT `internal`: the message names the offending constructor,
+   * which is the caller's own handler code and the only thing that makes the
+   * failure actionable. Redacting it leaves a bare 500 with nothing to grep.
+   * Raised INSIDE a mutation's transaction, so the writes roll back rather than
+   * committing behind a response that then fails to serialize.
+   */
+  readonly WIRE_ENCODE_FAILED: {
+    readonly status: 500;
+    readonly title: "Could not encode a return value";
+  };
+  readonly UNKNOWN_COLUMN: {
+    readonly status: 404;
+    readonly title: "Unknown column";
+  };
+  /**
+   * `@lunora/do`'s ShardDO — WebSocket-frame codes, changelog-retention refusals
+   * and SQLite-in-DO invariants.
+   *
+   * `NESTED_TRANSACTION` and `SQL_UNAVAILABLE` are "should never happen" state
+   * invariants (mirrors `RUN_DEPTH_EXCEEDED`'s posture above): today's message
+   * is static and safe, but flagged internal so a future edit that adds
+   * diagnostic detail can't accidentally start leaking it. The three `CDC_*`
+   * codes are the opposite — ordinary, expected outcomes of a configured
+   * retention window or an operator-ordered restore — and all three are `409`
+   * because the cursor the caller holds is real but no longer serveable, so
+   * the recovery is a snapshot rather than a retry.
+   */
+  /** A resume below the deleted changelog prefix: the entries are gone outright, for every consumer. */
+  readonly CDC_LOG_TRIMMED: {
+    readonly status: 409;
+    readonly title: "CDC log trimmed";
+  };
+  /** A resume from ABOVE the changelog's high-watermark: the shard's log rewound (a point-in-time restore), so the cursor indexes a timeline that no longer exists. Carries the surviving cursor and the freshly minted epoch to resynchronise against. */
+  readonly CDC_TIMELINE_FORKED: {
+    readonly status: 409;
+    readonly title: "CDC timeline forked";
+  };
+  /** A resume below the compacted prefix: the keys survive but their post-images do not, so only a payload consumer (streaming export, replay-PITR, a read replica) is refused. */
+  readonly CDC_PAYLOAD_COMPACTED: {
+    readonly status: 409;
+    readonly title: "CDC payloads compacted";
+  };
+  readonly EXPIRED: {
+    readonly status: 404;
+    readonly title: "Session expired";
+  };
+  readonly NESTED_TRANSACTION: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Nested transaction";
+  };
+  readonly OUT_OF_ORDER: {
+    readonly status: 409;
+    readonly title: "Out-of-order mutation";
+  };
+  readonly SHAPE_GLOBAL_TOO_LARGE: {
+    readonly status: 413;
+    readonly title: "Global shape too large";
+  };
+  readonly SHAPE_NOT_FOUND: {
+    readonly status: 404;
+    readonly title: "Shape not found";
+  };
+  readonly SHAPE_REQUIRES_CDC: {
+    readonly status: 409;
+    readonly title: "Shape requires change-data-capture";
+  };
+  readonly SQL_UNAVAILABLE: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "SQL storage unavailable";
+  };
+  readonly STREAM_ID_IN_USE: {
+    readonly status: 409;
+    readonly title: "Stream id already in use";
+  };
+  readonly STREAM_INTERRUPTED: {
+    readonly status: 503;
+    readonly title: "Durable stream interrupted";
+  };
+  readonly STREAM_TOO_LONG: {
+    readonly status: 507;
+    readonly title: "Durable stream exceeded its chunk ceiling";
+  };
+  readonly TOKEN_EXPIRED: {
+    readonly hint: readonly ["The caller's credential verified but its expiry has passed. The worker refuses an HTTP call with this code before it runs; a shard drops a socket with close code `4001` and the same code.", "", "It is a refusal of the credential, not of the call: `@lunora/client` holds a queued write, fires `onTokenExpired`, and re-sends it after `setAuthToken`. The held write survives the refresh only if you pass the same `subject` (the user id) with the new token, `setAuthToken(freshToken, user.id)`; without one a refresh reads as a user switch and the write is rejected `OFFLINE_IDENTITY_CHANGED`. Under a cookie session there is no token to replace: renew the cookie and the write is re-sent on a backoff. The worker can only tell expired from anonymous if your `resolveIdentity` returns the identity with its past `exp` (or `expiresAtMs`), or throws a `LunoraError` with this code. Returning `null` runs the call anonymous."];
+    readonly status: 401;
+    readonly title: "Authentication token expired";
+  };
+  readonly TOO_MANY_STREAMS: {
+    readonly status: 429;
+    readonly title: "Too many streams";
+  };
+  /**
+   * A socket asked an `onWhisper` authorizer to decide more distinct topics
+   * than the shard allows. Names only the socket's own ceiling — never the
+   * topic, never what the authorizer would have answered — so it is safe on
+   * the wire and not `internal`.
+   */
+  readonly TOO_MANY_WHISPER_TOPICS: {
+    readonly hint: "Reuse a stable set of whisper topic names, or reconnect — the per-socket verdict memo is in-memory, so a new connection starts empty. Leaving a topic does not free its entry.";
+    readonly status: 429;
+    readonly title: "Too many whisper topics";
+  };
+  readonly UNKNOWN_ADMIN_OP: {
+    readonly status: 404;
+    readonly title: "Unknown admin operation";
+  };
+  /**
+   * `@lunora/platform-cloudflare`'s `SocketHost.accept` guard — a caller
+   * supplied more accept-time tags (or a longer tag) than Cloudflare's
+   * `acceptWebSocket` budget allows once the host's own identity tag is
+   * reserved. Caller-actionable and safe (names counts, not internals) —
+   * not `internal`.
+   */
+  readonly SOCKET_TAG_BUDGET_EXCEEDED: {
+    readonly status: 400;
+    readonly title: "Socket tag budget exceeded";
+  };
+  /**
+   * `@lunora/shard-engine`'s relay hub (cross-shard shape relay coordination).
+   * Mirrors `SHARD_ERROR`/`SHARD_UNAVAILABLE` above: operational status for an
+   * app's own relay topology, not a secret — not `internal`.
+   */
+  readonly RELAY_CANNOT_SEED: {
+    readonly status: 500;
+    readonly title: "Relay cannot seed";
+  };
+  readonly RELAY_MISCONFIGURED: {
+    readonly status: 500;
+    readonly title: "Relay misconfigured";
+  };
+  readonly RELAY_SEED_FAILED: {
+    readonly status: 502;
+    readonly title: "Relay seed failed";
+  };
+  readonly RELAY_SHAPE_UNROUTABLE: {
+    readonly status: 500;
+    readonly title: "Relay shape unroutable";
+  };
+  /**
+   * A worker option required by the request path is absent (a deploy-config
+   * gap, not a caller error) — the fixed message names the missing option, so
+   * it's actionable and echoed. `MISCONFIGURED` is the one exception: its
+   * message interpolates the caller-supplied `functionPath`, and it's the code
+   * this plan's audit found live-leaking (`create-worker.ts`'s x402 gate).
+   */
+  readonly MISCONFIGURED: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Worker misconfigured";
+  };
+  /** `@lunora/nuxt`'s Nitro bridge: the request carried no Cloudflare bindings. Fixed, safe message. */
+  readonly LUNORA_RUNTIME_UNAVAILABLE: {
+    readonly status: 500;
+    readonly title: "Lunora runtime unavailable";
+  };
+  /**
+   * `@lunora/replica`'s event-log Durable Object: generic request-handler
+   * catch-all, mirroring `INTERNAL`/`INTERNAL_SERVER_ERROR`/`RPC_FAILED` above
+   * — the real error is logged server-side only, never in this code's message.
+   */
+  readonly INTERNAL_ERROR: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Internal error";
+  };
+  /**
+   * Client-SDK-only codes (`@lunora/client`), thrown locally in the browser/app
+   * process rather than by the server — `internal`'s wire-redaction semantics
+   * don't apply the same way here, since the "wire" is the app's own code
+   * catching its own client's exception. Kept in the catalog for the client's
+   * `code`-discrimination union and Studio/CLI rendering consistency.
+   */
+  readonly BROWSER_TIMEOUT: {
+    readonly status: 504;
+    readonly title: "Browser operation timed out";
+  };
+  readonly CLIENT_CLOSED: {
+    readonly status: 400;
+    readonly title: "Client is closed";
+  };
+  readonly HTTP_STREAM_BAD_CHUNK: {
+    readonly status: 502;
+    readonly title: "Malformed HTTP stream chunk";
+  };
+  readonly HTTP_STREAM_INTERRUPTED: {
+    readonly status: 502;
+    readonly title: "HTTP stream interrupted";
+  };
+  readonly HTTP_STREAM_MISSING_PARAM: {
+    readonly status: 400;
+    readonly title: "HTTP stream missing path parameter";
+  };
+  readonly HTTP_STREAM_NO_BODY: {
+    readonly status: 502;
+    readonly title: "HTTP stream response has no body";
+  };
+  readonly HTTP_STREAM_STATUS: {
+    readonly status: 502;
+    readonly title: "HTTP stream request failed";
+  };
+  readonly HTTP_STREAM_TRANSPORT: {
+    readonly status: 502;
+    readonly title: "HTTP stream transport error";
+  };
+  readonly STREAM_BACKPRESSURE: {
+    readonly status: 429;
+    readonly title: "Stream backpressure";
+  };
+  readonly STREAM_DISCONNECTED: {
+    readonly status: 503;
+    readonly title: "Stream disconnected";
+  };
+  readonly STREAM_QUEUE_OVERFLOW: {
+    readonly status: 429;
+    readonly title: "Stream queue overflow";
+  };
+  /** `@lunora/db`'s offline outbox: a queued write targeted a collection removed/renamed in a later deploy. */
+  readonly UNKNOWN_MUTATION_FN: {
+    readonly status: 404;
+    readonly title: "Unknown mutation function";
+  };
+  /**
+   * A local tool the CLI shells out to — `wrangler`, `git`, `docker`, a
+   * package manager — is not on PATH, so the child process never started.
+   *
+   * CLI-only and build-time-like: it never crosses the RPC wire (the same
+   * posture as `CODEGEN_DIAGNOSTIC`), so it is deliberately not `internal` —
+   * the message names the missing command, which IS the fix. The `500` is a
+   * placeholder for a transport that never carries it; `@lunora/cli` maps this
+   * code to its `missing local dependency` exit code BY NAME, because no HTTP
+   * status means "that program isn't installed".
+   */
+  readonly LOCAL_DEPENDENCY_MISSING: {
+    readonly hint: readonly ["The command Lunora tried to run is not on your PATH, so nothing ran.", "", "Install it (or put it on PATH) and retry — `wrangler` ships as a dependency of a Lunora app, so `pnpm install` usually fixes that one; `git` and `docker` are installed separately."];
+    readonly status: 500;
+    readonly title: "Required local tool not found";
+  };
 };
 /** A well-known Lunora error code (a key of {@link ERROR_CATALOG}). */
 type LunoraErrorCode = keyof typeof ERROR_CATALOG;
 /**
-* True when `code` is an internal/redacted code — an internal failure or
-* unhandled invariant whose `message` must NOT cross the wire (it may carry SQL
-* fragments, file paths, or internal identifiers). Derived from the catalog's
-* `internal` flag so the redaction posture stays in one place (the table).
-* Throwing a `LunoraError` with any non-internal code is the author's vouch that
-* its message is client-safe; an unknown/unregistered code is treated as safe.
-*/
+ * Look up a catalog entry by `code`, or `undefined` when the code isn't
+ * registered. The single guarded seam for reading `ERROR_CATALOG` by an
+ * arbitrary string: because the catalog is a plain object literal, a bracket
+ * read for an inherited key (e.g. `"constructor"`, `"toString"`) would resolve
+ * to `Object.prototype`'s member instead of `undefined`, so this uses
+ * `Object.hasOwn` to only ever return an own entry. Reused by the
+ * `LunoraError` constructor, {@link isInternalCode}, and {@link resolveHint}.
+ */
+declare const getCatalogEntry: (code: string) => ErrorCatalogEntry | undefined;
+/**
+ * True when `code` is an internal/redacted code — an internal failure or
+ * unhandled invariant whose `message` must NOT cross the wire (it may carry SQL
+ * fragments, file paths, or internal identifiers). Derived from the catalog's
+ * `internal` flag so the redaction posture stays in one place (the table).
+ * Throwing a `LunoraError` with any non-internal code is the author's vouch that
+ * its message is client-safe; an unknown/unregistered code is treated as safe.
+ */
 declare const isInternalCode: (code: string) => boolean;
 /**
-* A message-matched solution for errors that reach a consumer without a `code`
-* — chiefly `@lunora/codegen` build errors, which are thrown as plain messages
-* into generated code (and flattened to `{ message }` by the Vite overlay), so
-* the message text is the only stable join key. Ordered most- to least-specific;
-* the first matching rule wins.
-*/
+ * A message-matched solution for errors that reach a consumer without a `code`
+ * — chiefly `@lunora/codegen` build errors, which are thrown as plain messages
+ * into generated code (and flattened to `{ message }` by the Vite overlay), so
+ * the message text is the only stable join key. Ordered most- to least-specific;
+ * the first matching rule wins.
+ */
 interface Solution {
   /** Markdown body shown under the header. */
   body: string;
@@ -226,27 +1054,92 @@ interface SolutionRule extends Solution {
   test: (message: string) => boolean;
 }
 /**
-* Message-matched solutions (migrated verbatim from the former
-* `@lunora/codegen` solutions table). Re-exported by `@lunora/codegen` as
-* `LUNORA_SOLUTION_RULES` for backward compatibility.
-*/
+ * Message-matched solutions (migrated verbatim from the former
+ * `@lunora/codegen` solutions table). Re-exported by `@lunora/codegen` as
+ * `LUNORA_SOLUTION_RULES` for backward compatibility.
+ */
 declare const MESSAGE_SOLUTIONS: ReadonlyArray<SolutionRule>;
 /**
-* Flatten a Markdown hint to plain text for a terminal / non-Markdown surface:
-* drop code-fence markers and strip inline `**bold**` / `` `code` `` emphasis.
-* Shared by the CLI renderer and the Studio `ErrorAlert` so the two can't drift.
-*/
+ * One documented Cloudflare **platform** error — an edge/origin (5xx) or
+ * Cloudflare-service (1xxx) failure surfaced in an error *message* rather than
+ * thrown by Lunora as a coded `LunoraError`. These reach a Lunora app as
+ * plain text: a Worker that fetches a Cloudflare-fronted origin sees `Error 522`,
+ * a deploy that throws surfaces as `Error 1101`, and so on. The fields are the
+ * curated facts a grounded explainer elaborates on — never invents beyond.
+ */
+interface CloudflarePlatformError {
+  /** Documented likely causes (a short, comma-joined clause). */
+  causes: string;
+  /** The numeric Cloudflare error code, as it appears in the message (e.g. `"522"`, `"1101"`). */
+  code: string;
+  /** Canonical Cloudflare support-docs URL for this error's family. */
+  docsUrl: string;
+  /** Which docs family the code belongs to — shown in the "see docs" line. */
+  family: "1xxx" | "5xx";
+  /** The documented remediation. */
+  fix: string;
+  /** One-line summary of what the code means. */
+  summary: string;
+  /** Cloudflare's short name for the code (e.g. `"Connection timed out"`). */
+  title: string;
+}
+/**
+ * The curated Cloudflare platform-error table. Sourced from Cloudflare's official
+ * support docs — the codes surfaced to app authors on Workers/DO deployments (the
+ * origin-connection 52x family and the Worker/DNS/security 1xxx family). `1101`
+ * (a Worker threw) and `1102` (a Worker exceeded CPU) are the most Lunora-relevant.
+ */
+declare const CLOUDFLARE_PLATFORM_ERRORS: ReadonlyArray<CloudflarePlatformError>;
+/**
+ * Recognize a Cloudflare platform-error {@link CloudflarePlatformError} in a raw
+ * error message, conservatively: the message must carry Cloudflare's own
+ * `Error <code>` phrasing, or mention `cloudflare` alongside the standalone
+ * code. That keeps a bare number (`expected 520 items`) from false-matching a 5xx
+ * code, at the cost of missing a context-free code — the safe trade for a
+ * grounded hint. Returns the matched code's {@link Solution}, or `undefined`.
+ *
+ * Matching runs in two passes, strongest first: Cloudflare's own `Error <code>`
+ * phrasing is unambiguous, so it must win over the weaker "mentions cloudflare
+ * near some number" heuristic regardless of table order. A single pass let a weak
+ * match on an earlier entry beat an explicit match on a later one — `"Cloudflare
+ * Error 1102: exceeded after 524 ms"` resolved to 524, and that wrong grounded
+ * fix is exactly what the explainer prompt is built from.
+ */
+declare const findCloudflarePlatformSolution: (message: string) => Solution | undefined;
+/**
+ * Flatten a Markdown hint to plain text for a terminal / non-Markdown surface:
+ * drop code-fence markers and strip inline `**bold**` / `` `code` `` emphasis.
+ * Shared by the CLI renderer and the Studio `ErrorAlert` so the two can't drift.
+ */
 declare const flattenHint: (hint: ErrorHint) => string;
 /**
-* Find the first message-matched {@link Solution} for `message`, or `undefined`
-* if none recognize it. Re-exported by `@lunora/codegen` as `findLunoraSolution`.
-*/
+ * Find the first message-matched {@link Solution} for `message`, or `undefined`
+ * if none recognize it. Re-exported by `@lunora/codegen` as `findLunoraSolution`.
+ */
 declare const findSolutionByMessage: (message: string) => Solution | undefined;
 /**
-* Resolve an actionable hint for an error: prefer a hint carried on the error
-* (or its `code`'s catalog entry), then fall back to a message match. Returns
-* `undefined` when nothing recognizes it.
-*/
+ * Find a solution for `message` across BOTH Lunora's own rules and the curated
+ * Cloudflare platform-error table — the lookup the Studio Issues panel and the
+ * `explainIssue` grounding use.
+ *
+ * Deliberately separate from {@link findSolutionByMessage} rather than folded into
+ * it. That function is on `resolveHint`, and therefore on `toErrorBody` — the
+ * envelope builder for every failed request. Most `ERROR_CATALOG` entries
+ * carry no `hint`, so folding the platform table in there meant an ordinary
+ * `BAD_REQUEST` whose message merely mentioned "cloudflare" near a number shipped
+ * zone-configuration guidance ("review the zone's Firewall/WAF and IP Access
+ * Rules") to unauthenticated browsers. The same fold put the table on the CLI
+ * renderer and the Vite overlay, and on `toErrorBody`'s hot path.
+ *
+ * Platform errors are operator-facing context for an already-persisted Issue, so
+ * the operator-facing surfaces opt in here and the wire path stays Lunora-only.
+ */
+declare const findIssueSolution: (message: string) => Solution | undefined;
+/**
+ * Resolve an actionable hint for an error: prefer a hint carried on the error
+ * (or its `code`'s catalog entry), then fall back to a message match. Returns
+ * `undefined` when nothing recognizes it.
+ */
 declare const resolveHint: (input: {
   code?: string;
   hint?: ErrorHint;
@@ -278,16 +1171,16 @@ interface LunoraErrorOptions {
   title?: string;
 }
 /**
-* A code string: a well-known {@link LunoraErrorCode} (with autocomplete) or any
-* package-specific code not yet in the catalog.
-*/
+ * A code string: a well-known {@link LunoraErrorCode} (with autocomplete) or any
+ * package-specific code not yet in the catalog.
+ */
 type LunoraErrorCodeInput = LunoraErrorCode | (string & {});
 declare class LunoraError extends Error {
   /**
-  * Discriminator recognised by `@visulima/error`'s `renderError`/`isVisulimaError`
-  * (`error.type === "VisulimaError"`), so a `LunoraError` renders like a native
-  * `VisulimaError` — hint and all.
-  */
+   * Discriminator recognised by `@visulima/error`'s `renderError`/`isVisulimaError`
+   * (`error.type === "VisulimaError"`), so a `LunoraError` renders like a native
+   * `VisulimaError` — hint and all.
+   */
   readonly type = "VisulimaError";
   /** Actionable fix (Markdown), rendered by the CLI/overlay/Studio. */
   readonly hint: ErrorHint | undefined;
@@ -316,16 +1209,37 @@ interface LunoraErrorLike extends Error {
   type: "VisulimaError";
 }
 /**
-* True when `error` carries the Lunora transport shape (string `code` + numeric
-* `status` + the `VisulimaError` brand). The `type` brand is what distinguishes
-* a real `LunoraError` (or its wire-decoded twin) from a foreign error that
-* happens to carry `code`/`status` — see plan 119 for the full rationale.
-*/
+ * True when `error` carries the Lunora transport shape (string `code` + numeric
+ * `status` + the `VisulimaError` brand). The `type` brand is what distinguishes
+ * a real `LunoraError` (or its wire-decoded twin) from a foreign error that
+ * happens to carry `code`/`status` — see plan 119 for the full rationale.
+ */
 declare const isLunoraError: (error: unknown) => error is LunoraErrorLike;
 /** Throw an `INTERNAL` {@link LunoraError} when `condition` is falsy. */
 declare const invariant: (condition: unknown, message: string) => asserts condition;
 /** Throw an `INTERNAL` {@link LunoraError} for an unreachable branch. */
 declare const unreachable: (message: string) => never;
+/**
+ * Throw a {@link LunoraError} from expression position.
+ *
+ * `throw` is a statement, so it cannot sit on the right of `??` or in a ternary
+ * arm — the two places a missing value is most naturally rejected. Unlike
+ * {@link invariant} and {@link unreachable}, which are pinned to `INTERNAL`, this
+ * takes the code, which is what a client-actionable failure needs.
+ *
+ * Any string is a valid `code`. A well-known `ERROR_CATALOG` key fills in the
+ * status, title and hint; a package-specific code with no catalog entry defaults
+ * to status 500 and no hint, so pass those in `options` instead.
+ * @param code machine-readable reason
+ * @param message human-readable detail; defaults to `code`
+ * @param options status/title/hint/data overrides
+ * @example
+ * ```ts
+ * const thread = (await ctx.db.threads.get(id)) ?? raise("NOT_FOUND", `thread ${id}`);
+ * // thread is non-nullable here
+ * ```
+ */
+declare const raise: (code: LunoraErrorCodeInput, message?: string, options?: LunoraErrorOptions) => never;
 /** The client-facing error envelope body. */
 interface ErrorBody {
   code: string;
@@ -336,9 +1250,9 @@ interface ErrorBody {
 }
 interface ToErrorBodyOptions {
   /**
-  * Wire-encode a `LunoraError`'s structured `data` for the client (so a
-  * `bigint`/`bytes` inside it survives). Omit to drop `data` from the body.
-  */
+   * Wire-encode a `LunoraError`'s structured `data` for the client (so a
+   * `bigint`/`bytes` inside it survives). Omit to drop `data` from the body.
+   */
   encodeData?: (data: unknown) => unknown;
   /** Code for an unrecognized (non-`LunoraError`) throw. Default `"INTERNAL"`. */
   fallbackCode?: string;
@@ -353,12 +1267,42 @@ interface ToErrorBodyResult {
   status: number;
 }
 /**
-* Turn a thrown value into an {@link ErrorBody} + status, applying the redaction
-* invariant. A `LunoraError` with a non-internal code is echoed with its
-* `message`, resolved `hint`, `docsUrl`, and (when `encodeData` is given) its
-* `data`. An internal-coded `LunoraError` keeps its `code`/`status` but its
-* message is replaced with `redactedMessage`. Anything else becomes a generic
-* `fallbackCode`/500. When `redacted` is `true`, log the raw error server-side.
-*/
+ * Turn a thrown value into an {@link ErrorBody} + status, applying the redaction
+ * invariant. A `LunoraError` with a non-internal code is echoed with its
+ * `message`, resolved `hint`, `docsUrl`, and (when `encodeData` is given) its
+ * `data`. An internal-coded `LunoraError` keeps its `code`/`status` but its
+ * message is replaced with `redactedMessage`. Anything else becomes a generic
+ * `fallbackCode`/500. When `redacted` is `true`, log the raw error server-side.
+ */
 declare const toErrorBody: (error: unknown, options?: ToErrorBodyOptions) => ToErrorBodyResult;
-export { ERROR_CATALOG, type ErrorBody, type ErrorCatalogEntry, type ErrorHint, type ErrorLocation, LunoraError, type LunoraErrorCode, type LunoraErrorCodeInput, type LunoraErrorLike, type LunoraErrorOptions, MESSAGE_SOLUTIONS, type Solution, type SolutionRule, type ToErrorBodyOptions, type ToErrorBodyResult, findSolutionByMessage, flattenHint, invariant, isInternalCode, isLunoraError, resolveHint, toErrorBody, unreachable };
+export { CLOUDFLARE_PLATFORM_ERRORS, type CloudflarePlatformError, ERROR_CATALOG, type ErrorBody, type ErrorCatalogEntry, type ErrorHint,
+/**
+ * `@lunora/errors` — the unified error layer.
+ *
+ * This package is **zero-dependency** and safe on every runtime (browser client,
+ * workerd runtime, Node CLI): it exports the `LunoraError` class, the central
+ * catalog, the structural guard, and the invariant helpers. The terminal
+ * renderer (`renderLunoraError`, using `@visulima/error`'s `renderError`) lives
+ * in `@lunora/cli`, which already depends on `@visulima/error`.
+ */
+type ErrorLocation, LunoraError, type LunoraErrorCode,
+/**
+ * `@lunora/errors` — the unified error layer.
+ *
+ * This package is **zero-dependency** and safe on every runtime (browser client,
+ * workerd runtime, Node CLI): it exports the `LunoraError` class, the central
+ * catalog, the structural guard, and the invariant helpers. The terminal
+ * renderer (`renderLunoraError`, using `@visulima/error`'s `renderError`) lives
+ * in `@lunora/cli`, which already depends on `@visulima/error`.
+ */
+type LunoraErrorCodeInput, type LunoraErrorLike,
+/**
+ * `@lunora/errors` — the unified error layer.
+ *
+ * This package is **zero-dependency** and safe on every runtime (browser client,
+ * workerd runtime, Node CLI): it exports the `LunoraError` class, the central
+ * catalog, the structural guard, and the invariant helpers. The terminal
+ * renderer (`renderLunoraError`, using `@visulima/error`'s `renderError`) lives
+ * in `@lunora/cli`, which already depends on `@visulima/error`.
+ */
+type LunoraErrorOptions, MESSAGE_SOLUTIONS, type Solution, type SolutionRule, type ToErrorBodyOptions, type ToErrorBodyResult, findCloudflarePlatformSolution, findIssueSolution, findSolutionByMessage, flattenHint, getCatalogEntry, invariant, isInternalCode, isLunoraError, raise, resolveHint, toErrorBody, unreachable };