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

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/dist/index.d.mts

@@ -59,9 +59,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;
@@ -125,6 +125,23 @@ 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 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,20 +153,25 @@ 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";
   };
@@ -290,8 +312,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;

package/dist/index.d.ts

@@ -59,9 +59,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;
@@ -125,6 +125,23 @@ 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 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,20 +153,25 @@ 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";
   };
@@ -290,8 +312,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;

package/dist/index.mjs

@@ -1,5 +1,5 @@
-export { LunoraError } from './packem_shared/LunoraError-bpS_TPIe.mjs';
-export { ERROR_CATALOG, MESSAGE_SOLUTIONS, findSolutionByMessage, flattenHint, isInternalCode, resolveHint } from './packem_shared/ERROR_CATALOG-D3knuUQT.mjs';
-export { isLunoraError } from './packem_shared/isLunoraError-BvsoKcWE.mjs';
-export { invariant, unreachable } from './packem_shared/invariant-DLXTsHpj.mjs';
-export { toErrorBody } from './packem_shared/toErrorBody-DihI5p4Q.mjs';
+export { LunoraError } from './packem_shared/LunoraError-CwQSmeL3.mjs';
+export { ERROR_CATALOG, MESSAGE_SOLUTIONS, findSolutionByMessage, flattenHint, isInternalCode, resolveHint } from './packem_shared/ERROR_CATALOG-CoCPcAHf.mjs';
+export { isLunoraError } from './packem_shared/isLunoraError-CSQtYMrF.mjs';
+export { invariant, unreachable } from './packem_shared/invariant-DawIQfjN.mjs';
+export { toErrorBody } from './packem_shared/toErrorBody-CyqyVwGF.mjs';

package/dist/packem_shared/{ERROR_CATALOG-D3knuUQT.mjs → ERROR_CATALOG-CoCPcAHf.mjs}

@@ -14,13 +14,13 @@ const ERROR_CATALOG = {
   },
   NOT_UNIQUE: {
     hint: [
-      "A row with the same value already exists in a `unique` index.",
+      "`.unique()` matched more than one document — it expects the query to identify at most one row.",
       "",
-      "- 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.`
+      "- 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."
     ],
     status: 400,
-    title: "Unique constraint violation"
+    title: "Query matched more than one document"
   },
   VALIDATION_ERROR: { status: 400, title: "Validation failed" },
   TOO_MANY_REQUESTS: { status: 429, title: "Too many requests" },
@@ -48,14 +48,21 @@ const ERROR_CATALOG = {
     status: 403,
     title: "RLS policy required"
   },
+  RUN_DEPTH_EXCEEDED: { internal: true, status: 500, title: "Run depth exceeded" },
+  MIGRATION_NOT_FOUND: { status: 404, title: "Data migration not found" },
+  UNKNOWN_TABLE: { status: 404, title: "Unknown table" },
+  GLOBAL_TABLE_NOT_EDITABLE: { status: 400, title: "Global table is not editable" },
   SHARD_ERROR: { status: 503, title: "Shard error" },
   SHARD_UNAVAILABLE: { status: 503, title: "Shard unavailable" },
   OFFLINE_IDENTITY_CHANGED: { status: 409, 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`. */
   CODEGEN_DIAGNOSTIC: { status: 500, title: "Codegen diagnostic" },
+  /** Build-time-only — never crosses the RPC wire, so deliberately not `internal`. */
   SCHEMA_SNAPSHOT_PARSE: { status: 500, title: "Schema snapshot parse error" },
-  ENV_INVALID: { status: 500, title: "Invalid environment" },
-  AUTH_HEADERS_MISSING: { status: 500, title: "Auth headers missing" },
+  /** Runtime-reachable (env.ts): message enumerates failing env key names — redact on the wire. */
+  ENV_INVALID: { internal: true, status: 500, title: "Invalid environment" },
+  /** Runtime-reachable (auth/middleware.ts): message carries auth-wiring guidance — redact on the wire. */
+  AUTH_HEADERS_MISSING: { internal: true, status: 500, 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
@@ -167,7 +174,17 @@ const MESSAGE_SOLUTIONS = [
     test: (message) => message.includes("not exported by your worker entry")
   },
   {
-    body: ERROR_CATALOG.NOT_UNIQUE.hint.join("\n"),
+    // Deliberately NOT ERROR_CATALOG.NOT_UNIQUE.hint: that code (and hint)
+    // describes the read-side `.unique()` multi-match, while this matcher
+    // fires on the WRITE-path message ("unique constraint violation on
+    // <table>") thrown as a CONFLICT by an insert/patch breaching a
+    // `unique` index — a different error class needing insert remediation.
+    body: [
+      "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.`
+    ].join("\n"),
     header: "Unique constraint violation",
     id: "lunora-runtime-unique",
     test: (message) => message.includes("unique constraint violation on")

package/dist/packem_shared/{LunoraError-bpS_TPIe.mjs → LunoraError-CwQSmeL3.mjs}

@@ -1,4 +1,4 @@
-import { ERROR_CATALOG } from './ERROR_CATALOG-D3knuUQT.mjs';
+import { ERROR_CATALOG } from './ERROR_CATALOG-CoCPcAHf.mjs';
 
 class LunoraError extends Error {
   /**

package/dist/packem_shared/{invariant-DLXTsHpj.mjs → invariant-DawIQfjN.mjs}

@@ -1,4 +1,4 @@
-import { LunoraError } from './LunoraError-bpS_TPIe.mjs';
+import { LunoraError } from './LunoraError-CwQSmeL3.mjs';
 
 const invariant = (condition, message) => {
   if (!condition) {

package/dist/packem_shared/{isLunoraError-BvsoKcWE.mjs → isLunoraError-CSQtYMrF.mjs}

@@ -3,7 +3,7 @@ const isLunoraError = (error) => {
     return false;
   }
   const candidate = error;
-  return typeof candidate.code === "string" && typeof candidate.status === "number";
+  return candidate.type === "VisulimaError" && typeof candidate.code === "string" && typeof candidate.status === "number";
 };
 
 export { isLunoraError };

package/dist/packem_shared/{toErrorBody-DihI5p4Q.mjs → toErrorBody-CyqyVwGF.mjs}

@@ -1,5 +1,5 @@
-import { isInternalCode, resolveHint } from './ERROR_CATALOG-D3knuUQT.mjs';
-import { isLunoraError } from './isLunoraError-BvsoKcWE.mjs';
+import { isInternalCode, resolveHint } from './ERROR_CATALOG-CoCPcAHf.mjs';
+import { isLunoraError } from './isLunoraError-CSQtYMrF.mjs';
 
 const toErrorBody = (error, options = {}) => {
   const redactedMessage = options.redactedMessage ?? "Internal error";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/errors",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "description": "Unified error layer for Lunora: one LunoraError base + a central catalog of codes, statuses, and actionable hints, rendered across CLI, overlay, Studio, and the client",
   "keywords": [
     "cloudflare",