@lunora/errors 1.0.0-alpha.1 → 1.0.0-alpha.11

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;
@@ -59,9 +46,9 @@ declare const ERROR_CATALOG: {
     readonly title: "Conflict";
   };
   readonly NOT_UNIQUE: {
-    readonly hint: readonly ["A row with the same value already exists in a `unique` index.", "", "- If you meant to upsert, use `ctx.db.<table>().upsert(...)` (or `.patch(...)` an existing row) instead of `.insert(...)`.", "- Otherwise pick a value that isn't already taken, and consider surfacing a friendly \"already exists\" message to the user."];
+    readonly hint: readonly ["`.unique()` matched more than one document — it expects the query to identify at most one row.", "", "- If several matches are legitimate, use `.first()` (take one) or `.collect()` (take all) instead.", "- Otherwise tighten the query (e.g. filter on a unique/indexed field) so it can only match one row."];
     readonly status: 400;
-    readonly title: "Unique constraint violation";
+    readonly title: "Query matched more than one document";
   };
   readonly VALIDATION_ERROR: {
     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;
@@ -125,6 +114,28 @@ declare const ERROR_CATALOG: {
     readonly status: 403;
     readonly title: "RLS policy required";
   };
+  readonly RUN_DEPTH_EXCEEDED: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Run depth exceeded";
+  };
+  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";
+  };
+  readonly UNKNOWN_TABLE: {
+    readonly status: 404;
+    readonly title: "Unknown table";
+  };
+  readonly GLOBAL_TABLE_NOT_EDITABLE: {
+    readonly status: 400;
+    readonly title: "Global table is not editable";
+  };
   readonly SHARD_ERROR: {
     readonly status: 503;
     readonly title: "Shard error";
@@ -136,29 +147,55 @@ declare const ERROR_CATALOG: {
   readonly OFFLINE_IDENTITY_CHANGED: {
     readonly status: 409;
     readonly title: "Offline identity changed";
-  }; /** Package-specific codes. Build-time (codegen) codes never cross the RPC wire. */
+  };
+  /** 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 — never crosses the RPC wire, so deliberately not `internal`. */
   readonly SCHEMA_SNAPSHOT_PARSE: {
     readonly status: 500;
     readonly title: "Schema snapshot parse error";
   };
+  /** Runtime-reachable (env.ts): message enumerates failing env key names — redact on the wire. */
   readonly ENV_INVALID: {
+    readonly internal: true;
     readonly status: 500;
     readonly title: "Invalid environment";
   };
+  /** Runtime-reachable (auth/middleware.ts): message carries auth-wiring guidance — redact on the wire. */
   readonly AUTH_HEADERS_MISSING: {
+    readonly internal: true;
     readonly status: 500;
     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";
@@ -171,25 +208,419 @@ 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 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_DELETE_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Storage delete not configured";
+  };
+  readonly STORAGE_NOT_CONFIGURED: {
+    readonly status: 400;
+    readonly title: "Storage not configured";
+  };
+  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 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_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";
+  };
+  readonly FORBIDDEN_FANOUT: {
+    readonly status: 403;
+    readonly title: "Fan-out forbidden";
+  };
+  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";
+  };
+  /** 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";
+  };
+  readonly SHAPE_CROSS_SHARD_JOIN: {
+    readonly status: 400;
+    readonly title: "Shape cross-shard join is unsupported";
+  };
+  readonly UNAUTHENTICATED: {
+    readonly status: 401;
+    readonly title: "Unauthenticated";
+  };
+  readonly UNKNOWN_COLUMN: {
+    readonly status: 404;
+    readonly title: "Unknown column";
+  };
+  /**
+   * `@lunora/do`'s ShardDO — WebSocket-frame codes 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.
+   */
+  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 SQL_UNAVAILABLE: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "SQL storage unavailable";
+  };
+  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/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";
+  };
+  /**
+   * 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;
@@ -204,27 +635,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 &lt;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 &lt;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;
@@ -256,16 +752,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;
@@ -273,7 +769,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;
@@ -290,8 +786,15 @@ interface LunoraErrorLike extends Error {
   docsUrl?: string;
   hint?: ErrorHint;
   status: number;
+  /** Wire brand that distinguishes real `LunoraError`s from foreign errors. */
+  type: "VisulimaError";
 }
-/** True when `error` carries the Lunora transport shape (string `code` + numeric `status`). */
+/**
+ * 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;
@@ -307,9 +810,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;
@@ -324,12 +827,12 @@ 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, type ErrorLocation, LunoraError, type LunoraErrorCode, type LunoraErrorCodeInput, type LunoraErrorLike, type LunoraErrorOptions, MESSAGE_SOLUTIONS, type Solution, type SolutionRule, type ToErrorBodyOptions, type ToErrorBodyResult, findCloudflarePlatformSolution, findIssueSolution, findSolutionByMessage, flattenHint, invariant, isInternalCode, isLunoraError, resolveHint, toErrorBody, unreachable };