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

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 import { SQL } from 'drizzle-orm';
 import { DrizzleSqliteDODatabase } from 'drizzle-orm/durable-sqlite';
 /**
@@ -110,17 +111,13 @@ interface GroupByEntry {
   value: AggregateResult;
 }
 /**
-* Thrown when `count` runs in an RLS-restricted ctx. The structural shape
-* (`name: "LunoraError"`, `code`, `status`) lets the runtime's error mapper
-* route it without an `instanceof` check, so `@lunora/do` stays free of a
-* runtime dependency on `@lunora/server`. Status mirrors the
-* `COUNT_RLS_UNSUPPORTED` entry in the `LunoraErrorCode` taxonomy (422):
-* the operation is invalid in this context, not malformed.
+* Thrown when `count` runs in an RLS-restricted ctx. A `LunoraError` subclass
+* (`code: "COUNT_RLS_UNSUPPORTED"`, `status: 422`) recognised structurally by the
+* runtime's error mapper (via `isLunoraError`), so `@lunora/do` needs no runtime
+* dependency on `@lunora/server`. 422 = the operation is invalid in this context,
+* not malformed.
 */
-declare class CountRlsUnsupportedError extends Error {
-  readonly code: string;
-  override readonly name = "LunoraError";
-  readonly status: number;
+declare class CountRlsUnsupportedError extends LunoraError {
   constructor(table?: string);
 }
 /**
@@ -761,37 +758,6 @@ declare class ReactiveCache {
 * everyone. Anonymous/subscription callers pass `null` (their own bucket).
 */
 declare const reactiveCacheKey: (functionPath: string, args: Record<string, unknown>, identity: null | string) => string;
-/**
-* `ctx.db.system` — a best-effort, read-only reader over Lunora's *system*
-* tables.
-*
-* Convex surfaces a handful of read-only system tables (`_scheduled_functions`,
-* `_storage`, ...) through `ctx.db.system`. Lunora mirrors that surface, but with
-* one load-bearing caveat: **the data these tables expose does not live in the
-* shard's SQLite**. Scheduled functions live in the `SchedulerDO`; storage
-* objects live in R2. So unlike `ctx.db.&lt;table>` — which reads the same
-* transactional SQLite snapshot the mutation writes into — `ctx.db.system`
-* reaches across a network/DO boundary on every call.
-*
-* Consequences callers must keep in mind:
-*
-* Asynchronous + eventually consistent: each `collect()` / `get()` issues a fresh
-* read against the backing source. A row a mutation just scheduled may not yet be
-* visible; a job that just fired may still appear pending.
-*
-* NOT part of the transaction snapshot: reading a system table inside a mutation
-* does not pin it; there is no OCC guard and no subscription dependency is
-* recorded. Treat the result as a point-in-time best effort.
-*
-* Read-only: there is no `insert`/`patch`/`delete`. Mutate scheduled jobs via
-* `ctx.scheduler`, storage objects via `ctx.storage`.
-*
-* The reader is intentionally minimal: `query(table).collect()` returns the full
-* list (no indexes, no filtering, no pagination) and `get(table, id)` resolves a
-* single row. That matches Convex's system-table read surface closely enough for
-* the studio / introspection use cases without re-implementing the query
-* planner against a remote source.
-*/
 /** The system tables `ctx.db.system` can read. */
 type SystemTableName = "_scheduled_functions" | "_storage";
 /**
@@ -1893,14 +1859,12 @@ interface DatabaseWriterLike {
   system?: SystemDatabaseReader;
 }
 /**
-* Thrown by `.unique()` when more than one row matches. Like {@link ConflictError}
-* / `NotFoundError`, `code` / `status` are declared as own properties so the
-* cross-package structural error mapper renders it as a 400 without an
-* `instanceof` check against `@lunora/do`.
+* Thrown by `.unique()` when more than one row matches. A `LunoraError` subclass
+* (`code: "NOT_UNIQUE"`, `status: 400`) recognised structurally by the
+* cross-package transport mapper (via `isLunoraError`) without an `instanceof`
+* check against `@lunora/do`.
 */
-declare class NotUniqueError extends Error {
-  readonly code: string;
-  readonly status: number;
+declare class NotUniqueError extends LunoraError {
   constructor(message?: string);
 }
 /**
@@ -2496,6 +2460,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly applyCdc: "__lunora_admin__:applyCdc";
   readonly cdcSync: "__lunora_admin__:cdcSync";
   readonly clearCapturedMail: "__lunora_admin__:clearCapturedMail";
+  readonly clearQueueMessages: "__lunora_admin__:clearQueueMessages";
   readonly clearTable: "__lunora_admin__:clearTable";
   readonly createWorkflowInstance: "__lunora_admin__:createWorkflowInstance";
   readonly deleteRows: "__lunora_admin__:deleteRows";
@@ -2514,6 +2479,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getLogs: "__lunora_admin__:getLogs";
   readonly getMetrics: "__lunora_admin__:getMetrics";
   readonly getPitrBookmark: "__lunora_admin__:getPitrBookmark";
+  readonly getQueueMessages: "__lunora_admin__:getQueueMessages";
   readonly getRequestLog: "__lunora_admin__:getRequestLog";
   readonly getSecurityAudit: "__lunora_admin__:getSecurityAudit";
   readonly getSettings: "__lunora_admin__:getSettings";
@@ -2532,10 +2498,13 @@ declare const ADMIN_FUNCTIONS: {
   readonly recordAuthEvent: "__lunora_admin__:recordAuthEvent";
   readonly recordContainerEvent: "__lunora_admin__:recordContainerEvent";
   readonly recordMail: "__lunora_admin__:recordMail";
+  readonly recordQueueMessage: "__lunora_admin__:recordQueueMessage";
+  readonly replayQueueMessage: "__lunora_admin__:replayQueueMessage";
   readonly rlsPolicies: "__lunora_admin__:rlsPolicies";
   readonly runAs: "__lunora_admin__:runAs";
   readonly runMigration: "__lunora_admin__:runMigration";
   readonly runSql: "__lunora_admin__:runSql";
+  readonly sendQueueMessage: "__lunora_admin__:sendQueueMessage";
   readonly sendTestMail: "__lunora_admin__:sendTestMail";
   readonly storageOrphans: "__lunora_admin__:storageOrphans";
   readonly storageReferences: "__lunora_admin__:storageReferences";
@@ -3449,13 +3418,11 @@ declare const clearCapturedMail: (sql: SqlExec) => {
 /**
 * Thrown by `findFirstOrThrow` when no document matches the query.
 *
-* Like `ConflictError`, `code` / `status` are declared as own properties
-* so the cross-package structural error mapper maps it to a 404 without an
-* `instanceof` check against `@lunora/do`.
+* A `LunoraError` subclass (`code: "NOT_FOUND"`, `status: 404`) so the
+* cross-package transport mapper maps it to a 404 structurally (via
+* `isLunoraError`) without an `instanceof` check against `@lunora/do`.
 */
-declare class NotFoundError extends Error {
-  readonly code: string;
-  readonly status: number;
+declare class NotFoundError extends LunoraError {
   constructor(message?: string);
 }
 /**
@@ -3691,24 +3658,6 @@ interface LogEventInput {
 * that want the raw values.
 */
 /**
-* Secure-by-default write-path guard for `ctx.db`.
-*
-* When a schema is marked `defineSchema(...).rls("required")`, the generated
-* user-facing ctx wraps its writer with {@link guardWriter}. The guard denies
-* every read/write against a PROTECTED table (any table not marked `.public()`)
-* so a procedure that forgot `.use(rls(policies))` fails CLOSED — it can never
-* silently see or mutate a protected table through the unwrapped writer.
-*
-* The guard is transparent to the RLS middleware: it hangs the UNWRAPPED writer
-* off {@link RLS_UNWRAP_SYMBOL}, so `@lunora/server`'s `rls()` middleware
-* recovers the raw writer (via the same `Symbol.for` key — no cross-package
-* import) to evaluate policies and issue policy-filtered reads without tripping
-* the guard. Only procedures that NEVER engaged RLS keep talking to the guard.
-*
-* Admin / migration / studio writers (built from `createShardCtxDb` WITHOUT
-* `enforceRls`) are never guarded — they are trusted system paths.
-*/
-/**
 * Well-known symbol the guard hangs the unwrapped writer off of. `Symbol.for`
 * (the cross-realm global registry) lets `@lunora/server`'s RLS middleware read
 * it WITHOUT importing this module — both sides reference the same registered
@@ -3717,14 +3666,12 @@ interface LogEventInput {
 declare const RLS_UNWRAP_SYMBOL: symbol;
 /**
 * Thrown when a raw (non-RLS) handler touches a protected table under a
-* `.rls("required")` schema. `code` / `status` / `table` are own properties (not
-* just inherited prototype state) so structural callers across packages — which
-* deliberately avoid a hard `@lunora/do` runtime dependency — recognise the
-* shape without an `instanceof` check (mirrors `ConflictError`).
-*/
-declare class RlsRequiredError extends Error {
-  readonly code: string;
-  readonly status: number;
+* `.rls("required")` schema. A `LunoraError` subclass (`code: "RLS_REQUIRED"`,
+* `status: 403`) recognised structurally across packages (via `isLunoraError`) —
+* which deliberately avoid a hard `@lunora/do` runtime dependency — without an
+* `instanceof` check. `table` is kept as an own property.
+*/
+declare class RlsRequiredError extends LunoraError {
   readonly table: string;
   constructor(table: string);
 }
@@ -5713,6 +5660,54 @@ declare abstract class ShardDO {
   */
   private handleSendTestMail;
   /**
+  * 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.
+  */
+  private handleRecordQueueMessage;
+  /** Empty the dev queue consumed-message log (studio "clear log" action). Admin-gated by the caller. */
+  private handleClearQueueMessages;
+  /**
+  * 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.
+  */
+  private handleSendQueueMessage;
+  /**
+  * 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.
+  */
+  private handleReplayQueueMessage;
+  /**
+  * 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}.
+  */
+  private resolveQueueBinding;
+  /**
+  * 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.
+  */
+  private resolveReplayTarget;
+  /**
   * Append one durable audit entry for a state-changing admin op that just
   * succeeded, folding the acting user (from `getCurrentUserId`) into `detail`.
   * Called only on the success path, so a rejected/validated op leaves no
@@ -5918,6 +5913,17 @@ declare abstract class ShardDO {
   * JSON memo still suppresses byte-identical pushes).
   */
   private readAdminCapturedMail;
+  /**
+  * 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.
+  */
+  private readAdminQueueMessages;
   /** Resolve a `readTablePage` admin read, parsing the loosely-typed args into the reader's options. */
   private readAdminTablePage;
   /**
@@ -6587,18 +6593,14 @@ type ConflictKind = "conflict" | "occ" | "restrict" | "trigger" | "unique";
 * Thrown by mutation handlers when an optimistic-concurrency check fails (or a
 * related write guard trips — see {@link ConflictKind}).
 *
-* The runtime maps this to a 409 response so clients can decide whether to
-* refetch + retry or surface the conflict. `code` / `status` / `kind` are
-* declared as own properties (not just inherited prototype state) so structural
-* callers across packages — which deliberately avoid taking a hard runtime
-* dependency on `@lunora/do` — can recognise the shape without an `instanceof`
-* check.
-*/
-declare class ConflictError extends Error {
-  readonly code: string;
+* A `LunoraError` subclass (`code: "CONFLICT"`, `status: 409`) so the runtime/DO
+* transport mappers recognise it structurally (via `isLunoraError`) — structural
+* callers across packages still avoid a hard `instanceof` dependency on
+* `@lunora/do`. `kind` is kept as an own property for the metrics layer.
+*/
+declare class ConflictError extends LunoraError {
   /** Why the conflict fired; `occ` is the contention signal the metrics layer counts. */
   readonly kind: ConflictKind;
-  readonly status: number;
   constructor(message?: string, kind?: ConflictKind);
 }
 /**

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { LunoraError } from '@lunora/errors';
 import { SQL } from 'drizzle-orm';
 import { DrizzleSqliteDODatabase } from 'drizzle-orm/durable-sqlite';
 /**
@@ -110,17 +111,13 @@ interface GroupByEntry {
   value: AggregateResult;
 }
 /**
-* Thrown when `count` runs in an RLS-restricted ctx. The structural shape
-* (`name: "LunoraError"`, `code`, `status`) lets the runtime's error mapper
-* route it without an `instanceof` check, so `@lunora/do` stays free of a
-* runtime dependency on `@lunora/server`. Status mirrors the
-* `COUNT_RLS_UNSUPPORTED` entry in the `LunoraErrorCode` taxonomy (422):
-* the operation is invalid in this context, not malformed.
+* Thrown when `count` runs in an RLS-restricted ctx. A `LunoraError` subclass
+* (`code: "COUNT_RLS_UNSUPPORTED"`, `status: 422`) recognised structurally by the
+* runtime's error mapper (via `isLunoraError`), so `@lunora/do` needs no runtime
+* dependency on `@lunora/server`. 422 = the operation is invalid in this context,
+* not malformed.
 */
-declare class CountRlsUnsupportedError extends Error {
-  readonly code: string;
-  override readonly name = "LunoraError";
-  readonly status: number;
+declare class CountRlsUnsupportedError extends LunoraError {
   constructor(table?: string);
 }
 /**
@@ -761,37 +758,6 @@ declare class ReactiveCache {
 * everyone. Anonymous/subscription callers pass `null` (their own bucket).
 */
 declare const reactiveCacheKey: (functionPath: string, args: Record<string, unknown>, identity: null | string) => string;
-/**
-* `ctx.db.system` — a best-effort, read-only reader over Lunora's *system*
-* tables.
-*
-* Convex surfaces a handful of read-only system tables (`_scheduled_functions`,
-* `_storage`, ...) through `ctx.db.system`. Lunora mirrors that surface, but with
-* one load-bearing caveat: **the data these tables expose does not live in the
-* shard's SQLite**. Scheduled functions live in the `SchedulerDO`; storage
-* objects live in R2. So unlike `ctx.db.&lt;table>` — which reads the same
-* transactional SQLite snapshot the mutation writes into — `ctx.db.system`
-* reaches across a network/DO boundary on every call.
-*
-* Consequences callers must keep in mind:
-*
-* Asynchronous + eventually consistent: each `collect()` / `get()` issues a fresh
-* read against the backing source. A row a mutation just scheduled may not yet be
-* visible; a job that just fired may still appear pending.
-*
-* NOT part of the transaction snapshot: reading a system table inside a mutation
-* does not pin it; there is no OCC guard and no subscription dependency is
-* recorded. Treat the result as a point-in-time best effort.
-*
-* Read-only: there is no `insert`/`patch`/`delete`. Mutate scheduled jobs via
-* `ctx.scheduler`, storage objects via `ctx.storage`.
-*
-* The reader is intentionally minimal: `query(table).collect()` returns the full
-* list (no indexes, no filtering, no pagination) and `get(table, id)` resolves a
-* single row. That matches Convex's system-table read surface closely enough for
-* the studio / introspection use cases without re-implementing the query
-* planner against a remote source.
-*/
 /** The system tables `ctx.db.system` can read. */
 type SystemTableName = "_scheduled_functions" | "_storage";
 /**
@@ -1893,14 +1859,12 @@ interface DatabaseWriterLike {
   system?: SystemDatabaseReader;
 }
 /**
-* Thrown by `.unique()` when more than one row matches. Like {@link ConflictError}
-* / `NotFoundError`, `code` / `status` are declared as own properties so the
-* cross-package structural error mapper renders it as a 400 without an
-* `instanceof` check against `@lunora/do`.
+* Thrown by `.unique()` when more than one row matches. A `LunoraError` subclass
+* (`code: "NOT_UNIQUE"`, `status: 400`) recognised structurally by the
+* cross-package transport mapper (via `isLunoraError`) without an `instanceof`
+* check against `@lunora/do`.
 */
-declare class NotUniqueError extends Error {
-  readonly code: string;
-  readonly status: number;
+declare class NotUniqueError extends LunoraError {
   constructor(message?: string);
 }
 /**
@@ -2496,6 +2460,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly applyCdc: "__lunora_admin__:applyCdc";
   readonly cdcSync: "__lunora_admin__:cdcSync";
   readonly clearCapturedMail: "__lunora_admin__:clearCapturedMail";
+  readonly clearQueueMessages: "__lunora_admin__:clearQueueMessages";
   readonly clearTable: "__lunora_admin__:clearTable";
   readonly createWorkflowInstance: "__lunora_admin__:createWorkflowInstance";
   readonly deleteRows: "__lunora_admin__:deleteRows";
@@ -2514,6 +2479,7 @@ declare const ADMIN_FUNCTIONS: {
   readonly getLogs: "__lunora_admin__:getLogs";
   readonly getMetrics: "__lunora_admin__:getMetrics";
   readonly getPitrBookmark: "__lunora_admin__:getPitrBookmark";
+  readonly getQueueMessages: "__lunora_admin__:getQueueMessages";
   readonly getRequestLog: "__lunora_admin__:getRequestLog";
   readonly getSecurityAudit: "__lunora_admin__:getSecurityAudit";
   readonly getSettings: "__lunora_admin__:getSettings";
@@ -2532,10 +2498,13 @@ declare const ADMIN_FUNCTIONS: {
   readonly recordAuthEvent: "__lunora_admin__:recordAuthEvent";
   readonly recordContainerEvent: "__lunora_admin__:recordContainerEvent";
   readonly recordMail: "__lunora_admin__:recordMail";
+  readonly recordQueueMessage: "__lunora_admin__:recordQueueMessage";
+  readonly replayQueueMessage: "__lunora_admin__:replayQueueMessage";
   readonly rlsPolicies: "__lunora_admin__:rlsPolicies";
   readonly runAs: "__lunora_admin__:runAs";
   readonly runMigration: "__lunora_admin__:runMigration";
   readonly runSql: "__lunora_admin__:runSql";
+  readonly sendQueueMessage: "__lunora_admin__:sendQueueMessage";
   readonly sendTestMail: "__lunora_admin__:sendTestMail";
   readonly storageOrphans: "__lunora_admin__:storageOrphans";
   readonly storageReferences: "__lunora_admin__:storageReferences";
@@ -3449,13 +3418,11 @@ declare const clearCapturedMail: (sql: SqlExec) => {
 /**
 * Thrown by `findFirstOrThrow` when no document matches the query.
 *
-* Like `ConflictError`, `code` / `status` are declared as own properties
-* so the cross-package structural error mapper maps it to a 404 without an
-* `instanceof` check against `@lunora/do`.
+* A `LunoraError` subclass (`code: "NOT_FOUND"`, `status: 404`) so the
+* cross-package transport mapper maps it to a 404 structurally (via
+* `isLunoraError`) without an `instanceof` check against `@lunora/do`.
 */
-declare class NotFoundError extends Error {
-  readonly code: string;
-  readonly status: number;
+declare class NotFoundError extends LunoraError {
   constructor(message?: string);
 }
 /**
@@ -3691,24 +3658,6 @@ interface LogEventInput {
 * that want the raw values.
 */
 /**
-* Secure-by-default write-path guard for `ctx.db`.
-*
-* When a schema is marked `defineSchema(...).rls("required")`, the generated
-* user-facing ctx wraps its writer with {@link guardWriter}. The guard denies
-* every read/write against a PROTECTED table (any table not marked `.public()`)
-* so a procedure that forgot `.use(rls(policies))` fails CLOSED — it can never
-* silently see or mutate a protected table through the unwrapped writer.
-*
-* The guard is transparent to the RLS middleware: it hangs the UNWRAPPED writer
-* off {@link RLS_UNWRAP_SYMBOL}, so `@lunora/server`'s `rls()` middleware
-* recovers the raw writer (via the same `Symbol.for` key — no cross-package
-* import) to evaluate policies and issue policy-filtered reads without tripping
-* the guard. Only procedures that NEVER engaged RLS keep talking to the guard.
-*
-* Admin / migration / studio writers (built from `createShardCtxDb` WITHOUT
-* `enforceRls`) are never guarded — they are trusted system paths.
-*/
-/**
 * Well-known symbol the guard hangs the unwrapped writer off of. `Symbol.for`
 * (the cross-realm global registry) lets `@lunora/server`'s RLS middleware read
 * it WITHOUT importing this module — both sides reference the same registered
@@ -3717,14 +3666,12 @@ interface LogEventInput {
 declare const RLS_UNWRAP_SYMBOL: symbol;
 /**
 * Thrown when a raw (non-RLS) handler touches a protected table under a
-* `.rls("required")` schema. `code` / `status` / `table` are own properties (not
-* just inherited prototype state) so structural callers across packages — which
-* deliberately avoid a hard `@lunora/do` runtime dependency — recognise the
-* shape without an `instanceof` check (mirrors `ConflictError`).
-*/
-declare class RlsRequiredError extends Error {
-  readonly code: string;
-  readonly status: number;
+* `.rls("required")` schema. A `LunoraError` subclass (`code: "RLS_REQUIRED"`,
+* `status: 403`) recognised structurally across packages (via `isLunoraError`) —
+* which deliberately avoid a hard `@lunora/do` runtime dependency — without an
+* `instanceof` check. `table` is kept as an own property.
+*/
+declare class RlsRequiredError extends LunoraError {
   readonly table: string;
   constructor(table: string);
 }
@@ -5713,6 +5660,54 @@ declare abstract class ShardDO {
   */
   private handleSendTestMail;
   /**
+  * 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.
+  */
+  private handleRecordQueueMessage;
+  /** Empty the dev queue consumed-message log (studio "clear log" action). Admin-gated by the caller. */
+  private handleClearQueueMessages;
+  /**
+  * 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.
+  */
+  private handleSendQueueMessage;
+  /**
+  * 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.
+  */
+  private handleReplayQueueMessage;
+  /**
+  * 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}.
+  */
+  private resolveQueueBinding;
+  /**
+  * 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.
+  */
+  private resolveReplayTarget;
+  /**
   * Append one durable audit entry for a state-changing admin op that just
   * succeeded, folding the acting user (from `getCurrentUserId`) into `detail`.
   * Called only on the success path, so a rejected/validated op leaves no
@@ -5918,6 +5913,17 @@ declare abstract class ShardDO {
   * JSON memo still suppresses byte-identical pushes).
   */
   private readAdminCapturedMail;
+  /**
+  * 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.
+  */
+  private readAdminQueueMessages;
   /** Resolve a `readTablePage` admin read, parsing the loosely-typed args into the reader's options. */
   private readAdminTablePage;
   /**
@@ -6587,18 +6593,14 @@ type ConflictKind = "conflict" | "occ" | "restrict" | "trigger" | "unique";
 * Thrown by mutation handlers when an optimistic-concurrency check fails (or a
 * related write guard trips — see {@link ConflictKind}).
 *
-* The runtime maps this to a 409 response so clients can decide whether to
-* refetch + retry or surface the conflict. `code` / `status` / `kind` are
-* declared as own properties (not just inherited prototype state) so structural
-* callers across packages — which deliberately avoid taking a hard runtime
-* dependency on `@lunora/do` — can recognise the shape without an `instanceof`
-* check.
-*/
-declare class ConflictError extends Error {
-  readonly code: string;
+* A `LunoraError` subclass (`code: "CONFLICT"`, `status: 409`) so the runtime/DO
+* transport mappers recognise it structurally (via `isLunoraError`) — structural
+* callers across packages still avoid a hard `instanceof` dependency on
+* `@lunora/do`. `kind` is kept as an own property for the metrics layer.
+*/
+declare class ConflictError extends LunoraError {
   /** Why the conflict fired; `occ` is the contention signal the metrics layer counts. */
   readonly kind: ConflictKind;
-  readonly status: number;
   constructor(message?: string, kind?: ConflictKind);
 }
 /**

package/dist/index.mjs

@@ -1,40 +1,40 @@
 export { exportShardRows, exportShardTable, importShardRows, parseExportShardArgs, parseImportShardArgs, selectExportTables, validateImportRow } from './packem_shared/exportShardRows-DZEhUeyI.mjs';
-export { AGGREGATE_SQL_FUNCTION, aggregateSqlFunction, matchesStaticWhere, normalizeCountArgument, throwingScheduler } from './packem_shared/AGGREGATE_SQL_FUNCTION-CFk6adSu.mjs';
+export { AGGREGATE_SQL_FUNCTION, aggregateSqlFunction, matchesStaticWhere, normalizeCountArgument, throwingScheduler } from './packem_shared/AGGREGATE_SQL_FUNCTION-CQsu2Xga.mjs';
 export { aggregateTableName, coerceAggregateNumber, encodeAggregateKey, foldAggregateTally, readAggregateValue } from './packem_shared/aggregateTableName-CxNqY1Sl.mjs';
-export { CountRlsUnsupportedError, mergeWhere, planAggregateLookup, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy } from './packem_shared/CountRlsUnsupportedError-28ZvvwKS.mjs';
+export { CountRlsUnsupportedError, mergeWhere, planAggregateLookup, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy } from './packem_shared/CountRlsUnsupportedError-BGxj0pgS.mjs';
 export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, ensureAuthMetricsTables, readAuthMetrics, recordAuthEvent } from './packem_shared/AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-Do5h_jiW.mjs';
-export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } from './packem_shared/DATA_MIGRATION_STATE_TABLE-DfPxn8I0.mjs';
+export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-D1U5SBFR.mjs';
+export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } from './packem_shared/DATA_MIGRATION_STATE_TABLE-DB3IYUR3.mjs';
 export { SCAN_DEP, createDependencyTracker, depKey } from './packem_shared/SCAN_DEP-DLJF8dsj.mjs';
 export { renderSql } from './packem_shared/renderSql-D6eUcn2N.mjs';
 export { diffExternalSource } from './packem_shared/diffExternalSource-Cx9HUPJj.mjs';
-export { materializeExternalRows, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-Bj6EXy50.mjs';
-export { isSourceDue, liftSourceId, pullExternalSourceTick } from './packem_shared/isSourceDue-9mJRJ9Ld.mjs';
+export { materializeExternalRows, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-DNcvoLRT.mjs';
+export { isSourceDue, liftSourceId, pullExternalSourceTick } from './packem_shared/isSourceDue-BptUN8CR.mjs';
 export { FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, ensureFunctionMetricsTables, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, recordFunctionMetric } from './packem_shared/FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-DSUQ5fX9.mjs';
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-BbQdj8h1.mjs';
 export { LogBuffer } from './packem_shared/LogBuffer-B_Ezju_N.mjs';
 export { MAIL_RETENTION, MAIL_TABLE, clearCapturedMail, ensureMailTable, readCapturedMail, recordCapturedMail } from './packem_shared/MAIL_RETENTION-CPpgl-dX.mjs';
-export { default as NotFoundError } from './packem_shared/NotFoundError-CMuMZt81.mjs';
+export { default as NotFoundError } from './packem_shared/NotFoundError-C70b9hLw.mjs';
 export { armRestore, readBookmark } from './packem_shared/armRestore-BJk53Ro8.mjs';
 export { applySelect, buildSeekWhere, decodeCursor, encodeCursor, normalizeOrderKeys, softDeleteScope } from './packem_shared/applySelect-BvZdFUBT.mjs';
 export { RANK_TIEBREAK, encodePartitionKey, matchesRankStaticWhere, rankTableName, resolveRankPartition, sortColumnName } from './packem_shared/RANK_TIEBREAK-CXhdcA1o.mjs';
 export { ReactiveCache, reactiveCacheKey } from './packem_shared/ReactiveCache-BYlSGY0N.mjs';
-export { serveRelationFanout } from './packem_shared/serveRelationFanout-C5axmGDj.mjs';
-export { DEFAULT_MAX_RELATION_KEYS, assertFlatPredicate, assertShapeShardable, containsRelationPredicate, isRelationPredicate, resolveRelationPredicates } from './packem_shared/DEFAULT_MAX_RELATION_KEYS-DU-Y4-LJ.mjs';
-export { applyOnDelete, fanOutScalarCounts, resolveWith, runRowValidators } from './packem_shared/applyOnDelete-BQ-8ZlZ1.mjs';
-export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_shared/RLS_UNWRAP_SYMBOL-EtGQdC9d.mjs';
+export { serveRelationFanout } from './packem_shared/serveRelationFanout-BhZF9AuB.mjs';
+export { DEFAULT_MAX_RELATION_KEYS, assertFlatPredicate, assertShapeShardable, containsRelationPredicate, isRelationPredicate, resolveRelationPredicates } from './packem_shared/DEFAULT_MAX_RELATION_KEYS-CjM9Y1_G.mjs';
+export { applyOnDelete, fanOutScalarCounts, resolveWith, runRowValidators } from './packem_shared/applyOnDelete-CAwZfp-5.mjs';
+export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_shared/RLS_UNWRAP_SYMBOL-DnjkqVgY.mjs';
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-ilPZsVwu.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-BfPNp3Jh.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-BM4TOOvf.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-BsAbi5Mn.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-dDcFE1YZ.mjs';
-export { createSystemReader } from './packem_shared/createSystemReader-8CzSZP9V.mjs';
-export { ConflictError } from './packem_shared/ConflictError-C0STs6bU.mjs';
+export { createSystemReader } from './packem_shared/createSystemReader-D12eNH13.mjs';
+export { ConflictError } from './packem_shared/ConflictError-CLoq37xH.mjs';
 export { hasTrigger, runTriggers } from './packem_shared/hasTrigger-5N6_Fx0A.mjs';
-export { compileWhereSql } from './packem_shared/compileWhereSql-MW_Lk8nJ.mjs';
-export { CDC_LOG_TABLE, applyCdcChanges, readCdcChanges, trimCdcChanges } from './packem_shared/CDC_LOG_TABLE-DSycmnDf.mjs';
-export { backfillAggregateIndexes, backfillRankIndexes } from './packem_shared/backfillAggregateIndexes-BZsOqDXP.mjs';
-export { runShardMigrations } from './packem_shared/runShardMigrations-nIwoQeOK.mjs';
+export { compileWhereSql } from './packem_shared/compileWhereSql-DE6yfRcQ.mjs';
+export { CDC_LOG_TABLE, applyCdcChanges, readCdcChanges, trimCdcChanges } from './packem_shared/CDC_LOG_TABLE-DZSVKRr7.mjs';
+export { backfillAggregateIndexes, backfillRankIndexes } from './packem_shared/backfillAggregateIndexes-DDoT-UUI.mjs';
+export { runShardMigrations } from './packem_shared/runShardMigrations-DeZr0KZp.mjs';
 export { stableStringify } from './packem_shared/stableStringify-MydiuScU.mjs';
 export { s as subscriptionListDeltas } from './packem_shared/subscription-delivery-CK8qga-k.mjs';