@lunora/errors 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/index.d.mts

@@ -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,6 +119,24 @@ 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";
@@ -150,10 +157,31 @@ 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`. */
+  };
+  /** 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";
@@ -176,11 +204,31 @@ 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.
-  */
+   * 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` to `emailGate(...)` (`@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_ERROR: {
     readonly status: 502;
     readonly title: "Analytics Engine SQL API error";
@@ -193,25 +241,567 @@ declare const ERROR_CATALOG: {
     readonly status: 502;
     readonly title: "Cloudflare Workflows REST API error";
   };
+  /**
+   * 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";
+  };
+  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";
+  };
+  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_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 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";
+  };
+  /**
+   * 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_BINDING: {
+    readonly status: 500;
+    readonly title: "Duplicate agent binding";
+  };
+  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";
+  };
+  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";
+  };
+  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";
+  };
+  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 two `CDC_*`
+   * codes are the opposite — ordinary, expected, operator-configured outcomes
+   * — and both 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 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_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 status: 401;
+    readonly title: "Authentication token expired";
+  };
+  readonly TOO_MANY_STREAMS: {
+    readonly status: 429;
+    readonly title: "Too many streams";
+  };
+  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 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.
-*/
+ * 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 +816,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 +933,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;
@@ -295,7 +950,7 @@ declare class LunoraError extends Error {
   readonly title: string | undefined;
   /** Source location, when known (mirrors `VisulimaError.loc`). */
   readonly loc: ErrorLocation | undefined;
-  /** Machine-readable reason, keyed into {@link ERROR_CATALOG}. */
+  /** Machine-readable reason, keyed into `ERROR_CATALOG`. */
   readonly code: string;
   /** HTTP/RPC status for the transport mappers. */
   readonly status: number;
@@ -316,16 +971,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 +1012,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 +1029,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, invariant, isInternalCode, isLunoraError, raise, resolveHint, toErrorBody, unreachable };