@lunora/do 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-BfPNp3Jh.mjs → ROOT_DO_SIZE_WARN_BYTES-BM4TOOvf.mjs}

@@ -1,11 +1,12 @@
+import { LunoraError, toErrorBody } from '@lunora/errors';
 import { drizzle } from 'drizzle-orm/durable-sqlite';
 import { e as encodeWire, a as awaitWsDrain, t as trySendFrame, d as decodeWire, s as subscriptionListDeltas, b as sendDeltaFrames } from './subscription-delivery-CK8qga-k.mjs';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-DZEhUeyI.mjs';
 import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-DfPxn8I0.mjs';
+import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-DB3IYUR3.mjs';
 import { SCAN_DEP, createDependencyTracker, tableFromDepKey } from './SCAN_DEP-DLJF8dsj.mjs';
 import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-import { createFanoutCounters, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, summarizeFanoutTopics, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, recordFanoutPass, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-DSUQ5fX9.mjs';
+import { createFanoutCounters, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, summarizeFanoutTopics, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, recordFanoutPass, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-BbQdj8h1.mjs';
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
 import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
 import { readBookmark, armRestore } from './armRestore-BJk53Ro8.mjs';
@@ -14,21 +15,21 @@ import { stableStringify } from './stableStringify-MydiuScU.mjs';
 import { redact, standardRules } from '@visulima/redact';
 import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } from './security-audit-CucgBice.mjs';
 import { runReadonlySql } from './MAX_SQL_ROWS-dDcFE1YZ.mjs';
-import { ConflictError } from './ConflictError-C0STs6bU.mjs';
+import { ConflictError } from './ConflictError-CLoq37xH.mjs';
 import { e as deleteGlobalShapeSnapshotsForConnection, g as readIdempotent, h as writeIdempotent, t as trimIdempotent, r as readClientWatermark, m as migrateClientWatermark, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, f as readGlobalShapeSnapshot, w as writeGlobalShapeSnapshot } from './ctx-db-idempotency-BdcNpvY4.mjs';
-import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-DSycmnDf.mjs';
-import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-0RaIOy7J.mjs';
+import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-DZSVKRr7.mjs';
+import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
 
 const MAX_BATCH_ENTRIES = 500;
 
 const AUDIT_LOG_TABLE = "__lunora_audit__";
 const AUDIT_LOG_RETENTION = 1e3;
-const runSql$2 = (sql, query, ...params) => {
+const runSql$3 = (sql, query, ...params) => {
   const runner = sql.exec;
   return runner.call(sql, query, ...params);
 };
 const ensureAuditTable = (sql) => {
-  runSql$2(
+  runSql$3(
     sql,
     `CREATE TABLE IF NOT EXISTS "${AUDIT_LOG_TABLE}" (
             seq INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -42,7 +43,7 @@ const ensureAuditTable = (sql) => {
 };
 const appendAuditEntry = (sql, entry) => {
   ensureAuditTable(sql);
-  runSql$2(
+  runSql$3(
     sql,
     `INSERT INTO "${AUDIT_LOG_TABLE}" (ts, op, "table", id, detail) VALUES (?, ?, ?, ?, ?)`,
     entry.ts,
@@ -54,13 +55,13 @@ const appendAuditEntry = (sql, entry) => {
     // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for an op with no associated table/id/detail.
     entry.detail === void 0 ? null : JSON.stringify(entry.detail)
   );
-  runSql$2(sql, `DELETE FROM "${AUDIT_LOG_TABLE}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${AUDIT_LOG_TABLE}")`, AUDIT_LOG_RETENTION);
+  runSql$3(sql, `DELETE FROM "${AUDIT_LOG_TABLE}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${AUDIT_LOG_TABLE}")`, AUDIT_LOG_RETENTION);
 };
 const readAuditLog = (sql, options = {}) => {
   ensureAuditTable(sql);
   const sinceSeq = options.sinceSeq ?? 0;
   const limit = Math.max(1, Math.min(options.limit ?? AUDIT_LOG_RETENTION, 1e4));
-  const rows = runSql$2(
+  const rows = runSql$3(
     sql,
     `SELECT seq, ts, op, "table", id, detail FROM "${AUDIT_LOG_TABLE}" WHERE seq > ? ORDER BY seq DESC LIMIT ?`,
     sinceSeq,
@@ -116,7 +117,7 @@ const buildBatchEntryRequest = (batchRequest, entry) => {
 const QUERY_METRICS_TABLE = "__lunora_metrics_queries";
 const QUERY_METRICS_MAX_SQL_LEN = 512;
 const QUERY_METRICS_MAX_STATEMENTS = 500;
-const runSql$1 = (sql, query, ...params) => {
+const runSql$2 = (sql, query, ...params) => {
   const runner = sql.exec;
   return runner.call(sql, query, ...params);
 };
@@ -128,7 +129,7 @@ const normalizeSql = (sql) => {
   return normalized;
 };
 const ensureQueryMetricsTable = (sql) => {
-  runSql$1(
+  runSql$2(
     sql,
     `CREATE TABLE IF NOT EXISTS "${QUERY_METRICS_TABLE}" (
             normalized_sql TEXT PRIMARY KEY,
@@ -145,10 +146,10 @@ const recordQueryMetric = (sql, rawSql, durationMs, rowsRead, rowsWritten) => {
     return;
   }
   ensureQueryMetricsTable(sql);
-  const countRow = runSql$1(sql, `SELECT COUNT(*) AS n FROM "${QUERY_METRICS_TABLE}"`).one();
+  const countRow = runSql$2(sql, `SELECT COUNT(*) AS n FROM "${QUERY_METRICS_TABLE}"`).one();
   const count = countRow.n;
   if (count >= QUERY_METRICS_MAX_STATEMENTS) {
-    const existing = runSql$1(sql, `SELECT COUNT(*) AS c FROM "${QUERY_METRICS_TABLE}" WHERE normalized_sql = ?`, normalized).one();
+    const existing = runSql$2(sql, `SELECT COUNT(*) AS c FROM "${QUERY_METRICS_TABLE}" WHERE normalized_sql = ?`, normalized).one();
     if (existing.c === 0) {
       return;
     }
@@ -160,11 +161,11 @@ const recordQueryMetric = (sql, rawSql, durationMs, rowsRead, rowsWritten) => {
              total_duration_ms = total_duration_ms + excluded.total_duration_ms,
              rows_read = rows_read + excluded.rows_read,
              rows_written = rows_written + excluded.rows_written`;
-  runSql$1(sql, upsertSql, normalized, durationMs, rowsRead, rowsWritten);
+  runSql$2(sql, upsertSql, normalized, durationMs, rowsRead, rowsWritten);
 };
 const readQueryMetrics = (sql) => {
   ensureQueryMetricsTable(sql);
-  const rows = runSql$1(
+  const rows = runSql$2(
     sql,
     `SELECT normalized_sql, exec_count, total_duration_ms, rows_read, rows_written FROM "${QUERY_METRICS_TABLE}" ORDER BY total_duration_ms DESC`
   ).toArray();
@@ -179,6 +180,128 @@ const readQueryMetrics = (sql) => {
   });
 };
 
+const QUEUE_TABLE = "__lunora_queue_messages";
+const QUEUE_RETENTION = 500;
+const MAX_BODY_CHARS = 128 * 1024;
+const runSql$1 = (sql, query, ...params) => {
+  const runner = sql.exec;
+  return runner.call(sql, query, ...params);
+};
+const orNull = (value) => (
+  // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for an absent column.
+  value ?? null
+);
+const TRUNCATION_SUFFIX = "… [truncated by the dev queue catcher]";
+const UNSERIALIZABLE_MARKER = "[unserializable message body]";
+const encodeBody = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  try {
+    const encoded = JSON.stringify(value);
+    if (encoded.length > MAX_BODY_CHARS) {
+      return JSON.stringify(`${encoded.slice(0, MAX_BODY_CHARS)}${TRUNCATION_SUFFIX}`);
+    }
+    return encoded;
+  } catch {
+    return JSON.stringify(UNSERIALIZABLE_MARKER);
+  }
+};
+const isLossyBody = (body) => typeof body === "string" && (body === UNSERIALIZABLE_MARKER || body.endsWith(TRUNCATION_SUFFIX));
+const decodeBody = (value) => {
+  if (value === null || value === void 0 || value === "") {
+    return void 0;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+};
+const ensureQueueTable = (sql) => {
+  runSql$1(
+    sql,
+    `CREATE TABLE IF NOT EXISTS "${QUEUE_TABLE}" (
+            id TEXT PRIMARY KEY,
+            captured_at INTEGER NOT NULL,
+            message_id TEXT NOT NULL,
+            queue TEXT NOT NULL,
+            export_name TEXT,
+            body TEXT NOT NULL,
+            attempts INTEGER NOT NULL,
+            outcome TEXT NOT NULL,
+            error TEXT,
+            dead_lettered INTEGER NOT NULL,
+            message_ts INTEGER NOT NULL
+        )`
+  );
+};
+const recordQueueMessages = (sql, inputs, capturedAt) => {
+  ensureQueueTable(sql);
+  for (const input of inputs) {
+    runSql$1(
+      sql,
+      `INSERT INTO "${QUEUE_TABLE}" (id, captured_at, message_id, queue, export_name, body, attempts, outcome, error, dead_lettered, message_ts)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      crypto.randomUUID(),
+      capturedAt,
+      input.messageId,
+      input.queue,
+      orNull(input.exportName),
+      encodeBody(input.body),
+      input.attempts,
+      input.outcome,
+      orNull(input.error),
+      input.deadLettered === true ? 1 : 0,
+      input.timestamp
+    );
+  }
+  runSql$1(
+    sql,
+    `DELETE FROM "${QUEUE_TABLE}"
+         WHERE id NOT IN (
+            SELECT id FROM "${QUEUE_TABLE}" ORDER BY captured_at DESC, id DESC LIMIT ?
+         )`,
+    QUEUE_RETENTION
+  );
+  return { recorded: inputs.length };
+};
+const rowToEntry = (row) => {
+  return {
+    attempts: row.attempts,
+    body: decodeBody(row.body),
+    capturedAt: row.captured_at,
+    deadLettered: row.dead_lettered === 1,
+    error: row.error ?? void 0,
+    exportName: row.export_name ?? void 0,
+    id: row.id,
+    messageId: row.message_id,
+    outcome: row.outcome,
+    queue: row.queue,
+    timestamp: row.message_ts
+  };
+};
+const readQueueMessages = (sql, options = {}) => {
+  ensureQueueTable(sql);
+  const limit = Math.min(Math.max(options.limit ?? 100, 1), QUEUE_RETENTION);
+  const filterQueue = typeof options.queue === "string" && options.queue.length > 0 ? options.queue : void 0;
+  const where = filterQueue === void 0 ? "" : `WHERE queue = ?`;
+  const params = filterQueue === void 0 ? [limit] : [filterQueue, limit];
+  const rows = runSql$1(sql, `SELECT * FROM "${QUEUE_TABLE}" ${where} ORDER BY captured_at DESC, id DESC LIMIT ?`, ...params).toArray();
+  return { entries: rows.map((row) => rowToEntry(row)) };
+};
+const readQueueMessageById = (sql, id) => {
+  ensureQueueTable(sql);
+  const rows = runSql$1(sql, `SELECT * FROM "${QUEUE_TABLE}" WHERE id = ? LIMIT 1`, id).toArray();
+  const row = rows[0];
+  return row === void 0 ? void 0 : rowToEntry(row);
+};
+const clearQueueMessages = (sql) => {
+  ensureQueueTable(sql);
+  runSql$1(sql, `DELETE FROM "${QUEUE_TABLE}"`);
+  return { cleared: true };
+};
+
 const RELAY_NAME_INFIX = "::relay::";
 const relayName = (ownerKey, index) => `${ownerKey}${RELAY_NAME_INFIX}${String(index)}`;
 const parseRelayName = (name) => {
@@ -199,7 +322,7 @@ const shapeRoutingKey = (name, args) => stableStringify({ args: args ?? {}, name
 const DEFAULT_PROMOTION_THRESHOLDS = { tDown: 4e3, tUp: 8e3 };
 const nextPromotionState = (current, subscribers, thresholds = DEFAULT_PROMOTION_THRESHOLDS) => {
   if (thresholds.tDown >= thresholds.tUp) {
-    throw new Error(`invalid promotion thresholds: tDown (${String(thresholds.tDown)}) must be < tUp (${String(thresholds.tUp)})`);
+    throw new LunoraError("INTERNAL", `invalid promotion thresholds: tDown (${String(thresholds.tDown)}) must be < tUp (${String(thresholds.tUp)})`);
   }
   if (current === "owned") {
     return subscribers >= thresholds.tUp ? "promoted" : "owned";
@@ -305,7 +428,7 @@ const envPositiveInt = (env, key, fallback) => {
 };
 const RELAY_MULTICAST_IDENTITY = {};
 const assertNeverFrame = (frame) => {
-  throw new Error(`unhandled relay frame: ${JSON.stringify(frame)}`);
+  throw new LunoraError("INTERNAL", `unhandled relay frame: ${JSON.stringify(frame)}`);
 };
 const asRelayNamespace = (value) => {
   if (value === null || typeof value !== "object") {
@@ -1511,6 +1634,84 @@ Verify your email: ${link}`,
     to: recipient
   };
 };
+const parseRecordQueueMessageArgs = (args) => {
+  const bad = (message) => {
+    throw Object.assign(new Error(`recordQueueMessage: ${message}`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  };
+  const raw = args["messages"];
+  if (!Array.isArray(raw)) {
+    bad("`messages` must be an array");
+  }
+  const outcomes = /* @__PURE__ */ new Set(["ack", "error", "retry"]);
+  return raw.map((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      bad(`\`messages[${String(index)}]\` must be an object`);
+    }
+    const record = entry;
+    const messageId = typeof record["messageId"] === "string" ? record["messageId"] : "";
+    const queue = typeof record["queue"] === "string" ? record["queue"] : "";
+    const outcome = typeof record["outcome"] === "string" ? record["outcome"] : "";
+    if (messageId === "") {
+      bad(`\`messages[${String(index)}].messageId\` is required`);
+    }
+    if (queue === "") {
+      bad(`\`messages[${String(index)}].queue\` is required`);
+    }
+    if (!outcomes.has(outcome)) {
+      bad(`\`messages[${String(index)}].outcome\` must be one of ack | error | retry`);
+    }
+    const { attempts, timestamp } = record;
+    return {
+      attempts: typeof attempts === "number" && Number.isFinite(attempts) ? attempts : 1,
+      body: record["body"],
+      deadLettered: record["deadLettered"] === true,
+      error: typeof record["error"] === "string" ? record["error"] : void 0,
+      exportName: typeof record["exportName"] === "string" ? record["exportName"] : void 0,
+      messageId,
+      outcome,
+      queue,
+      timestamp: typeof timestamp === "number" && Number.isFinite(timestamp) ? timestamp : 0
+    };
+  });
+};
+const MAX_QUEUE_SEND_BATCH = 100;
+const parseSendQueueMessageArgs = (args) => {
+  const exportName = typeof args["exportName"] === "string" ? args["exportName"].trim() : "";
+  if (exportName === "") {
+    throw Object.assign(new Error("sendQueueMessage: `exportName` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  const delayRaw = args["delaySeconds"];
+  if (delayRaw !== void 0 && (typeof delayRaw !== "number" || !Number.isFinite(delayRaw) || delayRaw < 0)) {
+    throw Object.assign(new Error("sendQueueMessage: `delaySeconds` must be a non-negative number"), {
+      code: "BAD_REQUEST",
+      name: "LunoraError",
+      status: 400
+    });
+  }
+  const batch = Array.isArray(args["batch"]) ? args["batch"] : void 0;
+  if (batch !== void 0 && (batch.length === 0 || batch.length > MAX_QUEUE_SEND_BATCH)) {
+    throw Object.assign(new Error(`sendQueueMessage: \`batch\` must contain between 1 and ${String(MAX_QUEUE_SEND_BATCH)} messages`), {
+      code: "BAD_REQUEST",
+      name: "LunoraError",
+      status: 400
+    });
+  }
+  return {
+    batch,
+    body: args["body"],
+    contentType: typeof args["contentType"] === "string" ? args["contentType"] : void 0,
+    delaySeconds: delayRaw,
+    exportName
+  };
+};
+const parseReplayQueueMessageArgs = (args) => {
+  const id = typeof args["id"] === "string" ? args["id"].trim() : "";
+  if (id === "") {
+    throw Object.assign(new Error("replayQueueMessage: `id` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  const target = typeof args["target"] === "string" && args["target"].trim() !== "" ? args["target"].trim() : void 0;
+  return { id, target };
+};
 const parseRankBeforeArgs = (args) => {
   const table = typeof args["table"] === "string" ? args["table"] : "";
   const index = typeof args["index"] === "string" ? args["index"] : "";
@@ -4009,27 +4210,11 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method (groups with the request handlers); kept non-static so subclasses can override the error mapping
   errorToResponse(error) {
-    if (error instanceof ConflictError) {
-      return jsonResponse({ error: { code: error.code, message: error.message } }, error.status);
-    }
-    if (error && typeof error === "object" && error.name === "ValidationError") {
-      const message = error instanceof Error ? error.message : "validation failed";
-      return jsonResponse({ error: { code: "VALIDATION_ERROR", message } }, 400);
-    }
-    if (error && typeof error === "object" && error.name === "LunoraError") {
-      const lunoraError = error;
-      const status = typeof lunoraError.status === "number" ? lunoraError.status : 500;
-      const body = {
-        code: lunoraError.code ?? "INTERNAL",
-        message: lunoraError.message ?? "internal error"
-      };
-      if (lunoraError.data !== void 0) {
-        body.data = encodeWire(lunoraError.data);
-      }
-      return jsonResponse({ error: body }, status);
+    const { body, redacted, status } = toErrorBody(error, { encodeData: encodeWire, fallbackCode: "RPC_FAILED", redactedMessage: "internal error" });
+    if (redacted) {
+      console.error("[@lunora/do] internal error:", error);
     }
-    console.error("[@lunora/do] unhandled RPC error:", error);
-    return jsonResponse({ error: { code: "RPC_FAILED", message: "internal error" } }, 500);
+    return jsonResponse({ error: body }, status);
   }
   /**
    * Batch dispatch (plan 088). Applies each `calls[]` entry through the SAME
@@ -4201,6 +4386,18 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.sendTestMail) {
       return this.handleSendTestMail(args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.recordQueueMessage) {
+      return this.handleRecordQueueMessage(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.clearQueueMessages) {
+      return this.handleClearQueueMessages();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.sendQueueMessage) {
+      return this.handleSendQueueMessage(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.replayQueueMessage) {
+      return this.handleReplayQueueMessage(args);
+    }
     if (functionPath === ADMIN_FUNCTIONS.createWorkflowInstance) {
       return this.handleCreateWorkflowInstance(args);
     }
@@ -4410,6 +4607,127 @@ class ShardDO {
     const result = recordCapturedMail(this.state.storage.sql, input, Date.now());
     return jsonResponse({ result }, 200);
   }
+  /**
+   * Serve `__lunora_admin__:recordQueueMessage` — the capture sink the generated
+   * worker `queue()` handler (via `@lunora/queue`'s `dispatchQueueBatch`) posts
+   * every consumed message batch to. Records it into the reserved
+   * `__lunora_queue_messages` table (bounded, auto-trimmed) so the studio Queues
+   * panel shows one unified consumed-message log across every push consumer. Like
+   * the mail catcher, the gate is the admin token alone — a token holder can
+   * already mutate the shard, so a token-gated capture insert adds no privilege.
+   */
+  handleRecordQueueMessage(args) {
+    const messages = parseRecordQueueMessageArgs(args);
+    const result = recordQueueMessages(this.state.storage.sql, messages, Date.now());
+    return jsonResponse({ result }, 200);
+  }
+  /** Empty the dev queue consumed-message log (studio "clear log" action). Admin-gated by the caller. */
+  handleClearQueueMessages() {
+    const result = clearQueueMessages(this.state.storage.sql);
+    return jsonResponse({ result }, 200);
+  }
+  /**
+   * Serve `__lunora_admin__:sendQueueMessage` — the studio's "Send test message"
+   * button. Resolves the declared queue's `QUEUE_*` producer binding and calls
+   * `.send(body, { delaySeconds?, contentType? })`, or `.sendBatch(...)` when a
+   * `batch` array is supplied. No SQLite write happens here (the message is only
+   * captured once a consumer processes it), so this only records an audit entry.
+   * Admin-gated by `handleAdminRpc`'s caller.
+   */
+  async handleSendQueueMessage(args) {
+    const parsed = parseSendQueueMessageArgs(args);
+    const { binding } = this.resolveQueueBinding(parsed.exportName);
+    let sent;
+    if (parsed.batch === void 0) {
+      await binding.send(parsed.body, { contentType: parsed.contentType, delaySeconds: parsed.delaySeconds });
+      sent = 1;
+    } else {
+      await binding.sendBatch(
+        parsed.batch.map((body) => {
+          return { body, contentType: parsed.contentType, delaySeconds: parsed.delaySeconds };
+        })
+      );
+      sent = parsed.batch.length;
+    }
+    this.recordAudit("sendQueueMessage", { detail: { count: sent, exportName: parsed.exportName } });
+    return jsonResponse({ result: { sent } }, 200);
+  }
+  /**
+   * Serve `__lunora_admin__:replayQueueMessage` — the studio's one-click replay /
+   * DLQ redrive. Looks the captured row up by id, resolves the destination export
+   * (explicit `target` → the parent queue when the message was captured off a
+   * dead-letter queue → the queue it was consumed from), and re-enqueues the
+   * stored body onto that producer. Records an audit entry; no SQLite write beyond
+   * that (the replayed message is re-captured when a consumer processes it).
+   * Admin-gated by `handleAdminRpc`'s caller.
+   */
+  async handleReplayQueueMessage(args) {
+    const parsed = parseReplayQueueMessageArgs(args);
+    const row = readQueueMessageById(this.state.storage.sql, parsed.id);
+    if (row === void 0) {
+      throw Object.assign(new Error(`replayQueueMessage: captured message "${parsed.id}" was not found`), {
+        code: "BAD_REQUEST",
+        name: "LunoraError",
+        status: 404
+      });
+    }
+    if (isLossyBody(row.body)) {
+      throw Object.assign(
+        new Error(`replayQueueMessage: captured message "${parsed.id}" has a truncated or unserializable body and can't be replayed faithfully`),
+        { code: "BAD_REQUEST", name: "LunoraError", status: 422 }
+      );
+    }
+    const target = parsed.target ?? this.resolveReplayTarget(row.queue) ?? row.exportName;
+    if (typeof target !== "string" || target === "") {
+      throw Object.assign(new Error(`replayQueueMessage: captured message "${parsed.id}" has no declared producer to replay onto (pass \`target\`)`), {
+        code: "BAD_REQUEST",
+        name: "LunoraError",
+        status: 400
+      });
+    }
+    const { binding } = this.resolveQueueBinding(target);
+    await binding.send(row.body);
+    this.recordAudit("replayQueueMessage", { detail: { messageId: row.messageId, target }, id: parsed.id });
+    return jsonResponse({ result: { sent: 1, target } }, 200);
+  }
+  /**
+   * Resolve a declared queue's runtime producer binding from this shard's `env`.
+   * Looks the `exportName` up in {@link queuesMetadata} (the codegen subclass's
+   * statically-discovered list) to find its generated `QUEUE_*` binding, then
+   * reads `env[binding]` and validates it carries `send`/`sendBatch`. A bad export
+   * name or a missing/malformed binding throws a 400 `LunoraError` so the studio
+   * surfaces an actionable message. Mirrors {@link resolveWorkflowBinding}.
+   */
+  resolveQueueBinding(exportName) {
+    const metadata = this.queuesMetadata().queues.find((queue) => queue.exportName === exportName);
+    if (!metadata) {
+      throw Object.assign(new Error(`queue "${exportName}" is not declared`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    }
+    const binding = this.env?.[metadata.binding];
+    if (typeof binding !== "object" || binding === null || typeof binding.send !== "function") {
+      throw Object.assign(new Error(`queue binding "${metadata.binding}" is not available on this deployment`), {
+        code: "BAD_REQUEST",
+        name: "LunoraError",
+        status: 400
+      });
+    }
+    return { binding, metadata };
+  }
+  /**
+   * Pick the replay destination export for a captured message's origin queue.
+   * When the message was consumed off a queue that is another queue's dead-letter
+   * queue, prefer that PARENT queue's producer (a DLQ usually has no producer of
+   * its own) so replay redrives onto the original; otherwise re-enqueue onto the
+   * queue the message came from. Returns `undefined` when neither is declared.
+   */
+  resolveReplayTarget(queueName) {
+    const { queues } = this.queuesMetadata();
+    const parent = queues.find((queue) => queue.deadLetterQueue === queueName);
+    if (parent !== void 0) {
+      return parent.exportName;
+    }
+    return queues.find((queue) => queue.name === queueName)?.exportName;
+  }
   /**
    * Append one durable audit entry for a state-changing admin op that just
    * succeeded, folding the acting user (from `getCurrentUserId`) into `detail`.
@@ -4831,6 +5149,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.getCapturedMail) {
       return this.readAdminCapturedMail(sql, args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.getQueueMessages) {
+      return this.readAdminQueueMessages(sql, args);
+    }
     return void 0;
   }
   // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
@@ -4861,6 +5182,28 @@ class ShardDO {
     }
     return { result, tables: /* @__PURE__ */ new Set([MAIL_TABLE]) };
   }
+  /**
+   * Resolve a `getQueueMessages` admin read — the dev queue catcher's consumed
+   * message log (`queue-catcher.ts`), newest-first, optionally filtered to one
+   * queue. Best-effort: a SQL failure returns an empty log rather than throwing.
+   * Reported against the {@link QUEUE_TABLE} so this read participates in
+   * table-scoped subscription invalidation, but new captures arrive via the
+   * worker→root-shard `recordQueueMessage` write, which (like the mail catcher)
+   * inserts directly without a `flushChangedTables` — so the panel refreshes on
+   * its poll (`useAutoRefresh`) rather than a live push.
+   */
+  // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
+  readAdminQueueMessages(sql, args) {
+    const limit = typeof args["limit"] === "number" ? args["limit"] : void 0;
+    const queue = typeof args["queue"] === "string" ? args["queue"] : void 0;
+    let result;
+    try {
+      result = readQueueMessages(sql, { limit, queue });
+    } catch {
+      result = { entries: [] };
+    }
+    return { result, tables: /* @__PURE__ */ new Set([QUEUE_TABLE]) };
+  }
   /** Resolve a `readTablePage` admin read, parsing the loosely-typed args into the reader's options. */
   readAdminTablePage(sql, args) {
     const table = typeof args["table"] === "string" ? args["table"] : "";
@@ -5007,7 +5350,6 @@ class ShardDO {
    * 4. On normal completion send `{type:"complete"}`; on throw send
    * `{type:"error"}`. Either way drop the controller.
    */
-  // eslint-disable-next-line sonarjs/cognitive-complexity -- the stream lifecycle (ack → chunk pump → complete/error) plus the structured-vs-redacted error branch is the wire protocol and reads clearer inline than split across helpers sharing the controller + socket
   async handleStream(ws, id, functionPath, args) {
     const iterable = this.executeStream(functionPath, args);
     if (!iterable) {
@@ -5047,16 +5389,13 @@ class ShardDO {
         ws.send(JSON.stringify({ id, type: "complete" }));
       }
     } catch (error) {
-      const { code } = error;
-      const isStructured = typeof code === "string";
-      if (!isStructured) {
+      const { body, redacted } = toErrorBody(error, { fallbackCode: "INTERNAL_SERVER_ERROR", redactedMessage: "internal error" });
+      if (redacted) {
         console.error("[@lunora/do] unhandled stream error:", error);
       }
-      const rawMessage = error instanceof Error ? error.message : String(error);
-      const message = isStructured ? rawMessage : "internal error";
       ws.send(
         JSON.stringify({
-          error: { code: isStructured ? code : "INTERNAL_SERVER_ERROR", message },
+          error: { code: body.code, message: body.message },
           id,
           type: "error"
         })
@@ -5338,8 +5677,8 @@ class ShardDO {
       resolved = this.resolveShape(shape.name, shape.args ?? {}, identity);
     } catch (error) {
       this.recordShapeError(`shape:seed:${subId}`, error);
-      const code = typeof error.code === "string" ? error.code : "SHAPE_RESOLVE_FAILED";
-      return { code, message: error instanceof Error ? error.message : "shape resolution failed" };
+      const { body } = toErrorBody(error, { fallbackCode: "SHAPE_RESOLVE_FAILED", redactedMessage: "shape resolution failed" });
+      return { code: body.code, message: body.message };
     }
     if (!resolved) {
       return { code: "SHAPE_NOT_FOUND", message: `shape "${shape.name}" not found or not permitted` };
@@ -5351,8 +5690,8 @@ class ShardDO {
       return await this.seedOpLogShape(ws, subId, shape, resolved);
     } catch (error) {
       this.recordShapeError(`shape:seed:${subId}`, error);
-      const code = typeof error.code === "string" ? error.code : "SHAPE_SEED_FAILED";
-      return { code, message: error instanceof Error ? error.message : "shape seed failed" };
+      const { body } = toErrorBody(error, { fallbackCode: "SHAPE_SEED_FAILED", redactedMessage: "shape seed failed" });
+      return { code: body.code, message: body.message };
     }
   }
   /**

package/dist/packem_shared/{applyOnDelete-BQ-8ZlZ1.mjs → applyOnDelete-CAwZfp-5.mjs}

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 import { applySelect } from './applySelect-BvZdFUBT.mjs';
 
 const projectChildren = (documents, nested) => nested.select ? applySelect(documents, nested.select, nested.with) : documents;
@@ -27,13 +28,13 @@ const resolveWith = async (options) => {
   }
   const parentDefinition = schema.tables[tableName];
   if (!parentDefinition) {
-    throw new Error(`unknown table: ${tableName}`);
+    throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
   }
   const relationMap = parentDefinition.relationMap ?? {};
   const requireRelation = (name) => {
     const relation = relationMap[name];
     if (!relation) {
-      throw new Error(`unknown relation "${name}" on table "${tableName}"`);
+      throw new LunoraError("INTERNAL", `unknown relation "${name}" on table "${tableName}"`);
     }
     return relation;
   };
@@ -145,7 +146,7 @@ const applyRelationOnDelete = async (options, holderTable, relation) => {
 const applyOnDelete = async (options) => {
   const { schema, tableName } = options;
   if (!schema.tables[tableName]) {
-    throw new Error(`unknown table: ${tableName}`);
+    throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
   }
   for (const [holderTable, holderDefinition] of Object.entries(schema.tables)) {
     const relations = holderDefinition.relationMap;

package/dist/packem_shared/{backfillAggregateIndexes-BZsOqDXP.mjs → backfillAggregateIndexes-DDoT-UUI.mjs}

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import { matchesStaticWhere } from './AGGREGATE_SQL_FUNCTION-CFk6adSu.mjs';
+import { matchesStaticWhere } from './AGGREGATE_SQL_FUNCTION-CQsu2Xga.mjs';
 import { encodeAggregateKey, foldAggregateTally, aggregateTableName } from './aggregateTableName-CxNqY1Sl.mjs';
 import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
 import { D as DOC_COLUMN, r as rowToDocument, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT } from './do-sql-BCHCWtrD.mjs';

package/dist/packem_shared/{compileWhereSql-MW_Lk8nJ.mjs → compileWhereSql-DE6yfRcQ.mjs}

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 import { sql } from 'drizzle-orm';
 
 const RELATION_EXISTS_KEY = "__relationExists";
@@ -94,7 +95,7 @@ const STRUCTURAL_KEYS = /* @__PURE__ */ new Set(["AND", "NOT", "OR", RELATION_EX
 const compileStructuralKey = (key, value, strategy) => {
   if (key === RELATION_EXISTS_KEY) {
     if (!strategy.relationExists) {
-      throw new Error("encountered a relation EXISTS marker without a relationExists strategy hook");
+      throw new LunoraError("INTERNAL", "encountered a relation EXISTS marker without a relationExists strategy hook");
     }
     return strategy.relationExists(value);
   }