@lunora/do 1.0.0-alpha.22 → 1.0.0-alpha.24

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

@@ -2460,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";
@@ -2478,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";
@@ -2496,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";
@@ -3801,43 +3806,6 @@ declare const MIN_AUTH_SECRET_LENGTH = 32;
 * a *missing* token is never itself a finding here (introspection is simply off).
 */
 declare const buildSecurityAudit: (rawEnv: unknown) => SecurityAuditResult;
-/**
-* Durable Object that owns auth session state.
-*
-* `@lunora/auth` used to write sessions directly into D1 alongside user
-* records. That worked but coupled session lifecycle to a global database —
-* every read had to cross the region, every write contended with user
-* inserts. SessionDO owns sessions in a DO-local KV store: same-prefix
-* tokens co-locate (via `idFromName(token.slice(0, 16))`) so the DO instance
-* count stays bounded; reads and writes never round-trip to D1.
-*
-* Wire shape: HTTP only, never RPC. The auth package calls
-*
-* `await env.SESSION.get(env.SESSION.idFromName(prefix)).fetch(...)`
-*
-* with one of:
-*
-* POST   /create   body: { token, userId, ttlSeconds }
-* GET    /get      header: `x-lunora-session-token: <token>`
-* DELETE /revoke   header: `x-lunora-session-token: <token>`
-*
-* Every request must additionally carry an `x-lunora-session-secret` header
-* whose value matches `env.SESSION_DO_SECRET`. The DO is reachable from any
-* worker bound to its namespace, so a shared secret is the only thing that
-* prevents a compromised or misbehaving worker from reading arbitrary
-* sessions — the binding alone is not an auth surface.
-*
-* The DO returns JSON bodies that `@lunora/auth` reshapes into its public
-* `AuthSession` type. Keep the surface narrow — anything more elaborate
-* should ride on top via a wrapper, not by widening this contract.
-*
-* # Subclassing
-*
-* Apps subclass `SessionDO` (or use the codegen subclass) and register the
-* subclass in `wrangler.jsonc` as `SESSION`. The platform DO binding requires
-* a concrete `DurableObject` class today; the structural state shape used by
-* the unit tests is preserved so plain-object doubles still work.
-*/
 /** Default TTL for new sessions (7 days), matching `@lunora/auth`. */
 declare const SESSION_DO_TTL_DEFAULT: number;
 /** Hard ceiling on the requested TTL — 90 days. Longer sessions should ride on top via refresh. */
@@ -5655,6 +5623,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
@@ -5860,6 +5876,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;
   /**
@@ -6389,42 +6416,6 @@ declare abstract class ShardDO {
   private deliverWhisperLocal;
   private readAttachment;
 }
-/**
-* Durable Object that owns the live set of shard keys per sharded table.
-*
-* The query coordinator (`@lunora/runtime`) fans out cross-shard reads to
-* every live shard. With the static registry, the app supplies the shard
-* key list at boot — which is fine for fixed-cardinality deployments
-* (a known set of tenants) and unworkable for dynamic ones (one shard per
-* user-created channel, organisation, project, …).
-*
-* `ShardRegistryDO` is the persistent source of truth. A worker:
-*
-* - calls `POST /register {table, shardKey}` when a sharded table first
-* sees a write on a new key (typically from `ctx.db.<table>.insert` via
-* the worker's onWrite hook, fired through `ctx.waitUntil` so the
-* user-facing write doesn't pay the registry round-trip);
-* - calls `POST /unregister {table, shardKey}` when a shard is decommissioned;
-* - calls `GET /list?table=X` to materialise the fan-out target list. The
-* client (`createDynamicShardRegistry` in `@lunora/runtime`) caches the
-* answer with a small TTL so a wide fan-out doesn't pay a registry
-* round-trip on every call.
-*
-* Single-instance contract: deploy one DO instance per environment, by
-* convention named {@link SHARD_REGISTRY_DO_NAME}. The DO is small (just a
-* `Map<table, Set<shardKey>>`) and writes are infrequent (only on first-seen
-* shardKey per table), so a single instance is sufficient up to tens of
-* thousands of distinct shard keys.
-*
-* Wire shape: HTTP only, never RPC.
-*
-* POST /register   body: { table, shardKey }
-* POST /unregister body: { table, shardKey }
-* GET  /list?table=...
-* GET  /snapshot                (debug: returns the full table → [keys] map)
-*
-* Responses are JSON; the client shapes them. Keep the surface narrow.
-*/
 /** Conventional DO instance name, passed to `idFromName` to address the single registry instance. */
 declare const SHARD_REGISTRY_DO_NAME: string;
 /**

package/dist/index.d.ts

@@ -2460,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";
@@ -2478,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";
@@ -2496,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";
@@ -3801,43 +3806,6 @@ declare const MIN_AUTH_SECRET_LENGTH = 32;
 * a *missing* token is never itself a finding here (introspection is simply off).
 */
 declare const buildSecurityAudit: (rawEnv: unknown) => SecurityAuditResult;
-/**
-* Durable Object that owns auth session state.
-*
-* `@lunora/auth` used to write sessions directly into D1 alongside user
-* records. That worked but coupled session lifecycle to a global database —
-* every read had to cross the region, every write contended with user
-* inserts. SessionDO owns sessions in a DO-local KV store: same-prefix
-* tokens co-locate (via `idFromName(token.slice(0, 16))`) so the DO instance
-* count stays bounded; reads and writes never round-trip to D1.
-*
-* Wire shape: HTTP only, never RPC. The auth package calls
-*
-* `await env.SESSION.get(env.SESSION.idFromName(prefix)).fetch(...)`
-*
-* with one of:
-*
-* POST   /create   body: { token, userId, ttlSeconds }
-* GET    /get      header: `x-lunora-session-token: <token>`
-* DELETE /revoke   header: `x-lunora-session-token: <token>`
-*
-* Every request must additionally carry an `x-lunora-session-secret` header
-* whose value matches `env.SESSION_DO_SECRET`. The DO is reachable from any
-* worker bound to its namespace, so a shared secret is the only thing that
-* prevents a compromised or misbehaving worker from reading arbitrary
-* sessions — the binding alone is not an auth surface.
-*
-* The DO returns JSON bodies that `@lunora/auth` reshapes into its public
-* `AuthSession` type. Keep the surface narrow — anything more elaborate
-* should ride on top via a wrapper, not by widening this contract.
-*
-* # Subclassing
-*
-* Apps subclass `SessionDO` (or use the codegen subclass) and register the
-* subclass in `wrangler.jsonc` as `SESSION`. The platform DO binding requires
-* a concrete `DurableObject` class today; the structural state shape used by
-* the unit tests is preserved so plain-object doubles still work.
-*/
 /** Default TTL for new sessions (7 days), matching `@lunora/auth`. */
 declare const SESSION_DO_TTL_DEFAULT: number;
 /** Hard ceiling on the requested TTL — 90 days. Longer sessions should ride on top via refresh. */
@@ -5655,6 +5623,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
@@ -5860,6 +5876,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;
   /**
@@ -6389,42 +6416,6 @@ declare abstract class ShardDO {
   private deliverWhisperLocal;
   private readAttachment;
 }
-/**
-* Durable Object that owns the live set of shard keys per sharded table.
-*
-* The query coordinator (`@lunora/runtime`) fans out cross-shard reads to
-* every live shard. With the static registry, the app supplies the shard
-* key list at boot — which is fine for fixed-cardinality deployments
-* (a known set of tenants) and unworkable for dynamic ones (one shard per
-* user-created channel, organisation, project, …).
-*
-* `ShardRegistryDO` is the persistent source of truth. A worker:
-*
-* - calls `POST /register {table, shardKey}` when a sharded table first
-* sees a write on a new key (typically from `ctx.db.<table>.insert` via
-* the worker's onWrite hook, fired through `ctx.waitUntil` so the
-* user-facing write doesn't pay the registry round-trip);
-* - calls `POST /unregister {table, shardKey}` when a shard is decommissioned;
-* - calls `GET /list?table=X` to materialise the fan-out target list. The
-* client (`createDynamicShardRegistry` in `@lunora/runtime`) caches the
-* answer with a small TTL so a wide fan-out doesn't pay a registry
-* round-trip on every call.
-*
-* Single-instance contract: deploy one DO instance per environment, by
-* convention named {@link SHARD_REGISTRY_DO_NAME}. The DO is small (just a
-* `Map<table, Set<shardKey>>`) and writes are infrequent (only on first-seen
-* shardKey per table), so a single instance is sufficient up to tens of
-* thousands of distinct shard keys.
-*
-* Wire shape: HTTP only, never RPC.
-*
-* POST /register   body: { table, shardKey }
-* POST /unregister body: { table, shardKey }
-* GET  /list?table=...
-* GET  /snapshot                (debug: returns the full table → [keys] map)
-*
-* Responses are JSON; the client shapes them. Keep the surface narrow.
-*/
 /** Conventional DO instance name, passed to `idFromName` to address the single registry instance. */
 declare const SHARD_REGISTRY_DO_NAME: string;
 /**

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { exportShardRows, exportShardTable, importShardRows, parseExportShardArgs, parseImportShardArgs, selectExportTables, validateImportRow } from './packem_shared/exportShardRows-DZEhUeyI.mjs';
+export { exportShardRows, exportShardTable, importShardRows, parseExportShardArgs, parseImportShardArgs, selectExportTables, validateImportRow } from './packem_shared/exportShardRows-Dy3oFZ26.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-BGxj0pgS.mjs';
@@ -11,7 +11,7 @@ export { diffExternalSource } from './packem_shared/diffExternalSource-Cx9HUPJj.
 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-C70b9hLw.mjs';
@@ -19,15 +19,15 @@ export { armRestore, readBookmark } from './packem_shared/armRestore-BJk53Ro8.mj
 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 { 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-BQoX61l-.mjs';
-export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-BsAbi5Mn.mjs';
+export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-D71QAL5h.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-KQQiPDQ3.mjs';
+export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-D99roc-r.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-dDcFE1YZ.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-D12eNH13.mjs';
 export { ConflictError } from './packem_shared/ConflictError-CLoq37xH.mjs';

package/dist/packem_shared/{ADMIN_FUNCTIONS-DSUQ5fX9.mjs → ADMIN_FUNCTIONS-BbQdj8h1.mjs}

@@ -7,6 +7,7 @@ const ADMIN_FUNCTIONS = {
   applyCdc: "__lunora_admin__:applyCdc",
   cdcSync: "__lunora_admin__:cdcSync",
   clearCapturedMail: "__lunora_admin__:clearCapturedMail",
+  clearQueueMessages: "__lunora_admin__:clearQueueMessages",
   clearTable: "__lunora_admin__:clearTable",
   createWorkflowInstance: "__lunora_admin__:createWorkflowInstance",
   deleteRows: "__lunora_admin__:deleteRows",
@@ -25,6 +26,7 @@ const ADMIN_FUNCTIONS = {
   getLogs: "__lunora_admin__:getLogs",
   getMetrics: "__lunora_admin__:getMetrics",
   getPitrBookmark: "__lunora_admin__:getPitrBookmark",
+  getQueueMessages: "__lunora_admin__:getQueueMessages",
   getRequestLog: "__lunora_admin__:getRequestLog",
   getSecurityAudit: "__lunora_admin__:getSecurityAudit",
   getSettings: "__lunora_admin__:getSettings",
@@ -44,10 +46,13 @@ const ADMIN_FUNCTIONS = {
   recordAuthEvent: "__lunora_admin__:recordAuthEvent",
   recordContainerEvent: "__lunora_admin__:recordContainerEvent",
   recordMail: "__lunora_admin__:recordMail",
+  recordQueueMessage: "__lunora_admin__:recordQueueMessage",
+  replayQueueMessage: "__lunora_admin__:replayQueueMessage",
   rlsPolicies: "__lunora_admin__:rlsPolicies",
   runAs: "__lunora_admin__:runAs",
   runMigration: "__lunora_admin__:runMigration",
   runSql: "__lunora_admin__:runSql",
+  sendQueueMessage: "__lunora_admin__:sendQueueMessage",
   sendTestMail: "__lunora_admin__:sendTestMail",
   storageOrphans: "__lunora_admin__:storageOrphans",
   storageReferences: "__lunora_admin__:storageReferences",

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-BQoX61l-.mjs → ROOT_DO_SIZE_WARN_BYTES-KQQiPDQ3.mjs}

@@ -1,12 +1,13 @@
 import { LunoraError, toErrorBody } from '@lunora/errors';
 import { drizzle } from 'drizzle-orm/durable-sqlite';
+import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
 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 { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-Dy3oFZ26.mjs';
 import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.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';
@@ -24,12 +25,12 @@ 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,
@@ -43,7 +44,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,
@@ -55,13 +56,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,
@@ -117,7 +118,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);
 };
@@ -129,7 +130,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,
@@ -146,10 +147,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;
     }
@@ -161,11 +162,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();
@@ -180,6 +181,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) => {
@@ -642,7 +765,8 @@ class OwnerRelay extends RelayLink {
     try {
       resolved = this.host.resolveShape(request.name, request.args, identity);
     } catch (error) {
-      return { error: { code: "SHAPE_RESOLVE_FAILED", message: error instanceof Error ? error.message : "shape resolve failed" } };
+      const { body } = toErrorBody(error, { fallbackCode: "SHAPE_RESOLVE_FAILED", redactedMessage: "shape resolution failed" });
+      return { error: { code: body.code, message: body.message } };
     }
     if (resolved === void 0 || resolved.global === true) {
       return { error: { code: "SHAPE_NOT_FOUND", message: `shape not relayable: ${request.name}` } };
@@ -1512,6 +1636,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"] : "";
@@ -1642,13 +1844,7 @@ const parseCdcSyncArgs = (args) => {
   };
   return { limit: toCount(args["limit"]), sinceSeq: toCount(args["sinceSeq"]) ?? 0 };
 };
-const jsonResponse = (body, status = 200, bookmark) => {
-  const headers = { "content-type": "application/json" };
-  if (bookmark) {
-    headers["x-d1-bookmark"] = bookmark;
-  }
-  return Response.json(body, { headers, status });
-};
+const bookmarkHeaders = (bookmark) => bookmark ? { "x-d1-bookmark": bookmark } : void 0;
 const parseIdentityHeader = (raw) => {
   if (!raw) {
     return void 0;
@@ -2194,7 +2390,7 @@ class ShardDO {
     try {
       if (payload.functionPath.startsWith(RELATION_FUNCTION_PREFIX)) {
         const value = await this.runRelationFanoutRead(payload.functionPath, payload.args ?? {});
-        return jsonResponse(value, 200, this.currentResponseBookmark);
+        return jsonResponse(value, 200, bookmarkHeaders(this.currentResponseBookmark));
       }
       const mutatorClass = this.isCustomMutator(payload.functionPath) ? this.classifyClientMutation() : void 0;
       this.currentMutatorClass = mutatorClass;
@@ -3239,7 +3435,7 @@ class ShardDO {
     }
     this.recordFunctionCall(functionPath, Date.now() - dispatchStartedAt, void 0, this.currentScannedTables, this.currentIndexHits);
     if (mutatorClass.kind === "already") {
-      return jsonResponse({ lastMutationId: mutatorClass.expected - 1, result: null }, 200, this.currentResponseBookmark);
+      return jsonResponse({ lastMutationId: mutatorClass.expected - 1, result: null }, 200, bookmarkHeaders(this.currentResponseBookmark));
     }
     return jsonResponse(
       {
@@ -3250,7 +3446,7 @@ class ShardDO {
         }
       },
       409,
-      this.currentResponseBookmark
+      bookmarkHeaders(this.currentResponseBookmark)
     );
   }
   /**
@@ -3269,7 +3465,11 @@ class ShardDO {
       return this.buildDispatchResponse(mutatorClass, cachedValue);
     }
     const commitCursor = this.mutationCommitCursor();
-    return jsonResponse(commitCursor === void 0 ? { result: cachedValue } : { commitCursor, result: cachedValue }, 200, this.currentResponseBookmark);
+    return jsonResponse(
+      commitCursor === void 0 ? { result: cachedValue } : { commitCursor, result: cachedValue },
+      200,
+      bookmarkHeaders(this.currentResponseBookmark)
+    );
   }
   /**
    * The CDC cursor a just-committed plain mutation landed at — the post-write
@@ -3293,10 +3493,10 @@ class ShardDO {
    */
   buildDispatchResponse(mutatorClass, result) {
     if (mutatorClass?.kind === "next") {
-      return jsonResponse({ lastMutationId: this.currentRequestClientSeq, result }, 200, this.currentResponseBookmark);
+      return jsonResponse({ lastMutationId: this.currentRequestClientSeq, result }, 200, bookmarkHeaders(this.currentResponseBookmark));
     }
     const commitCursor = this.mutationCommitCursor();
-    return jsonResponse(commitCursor === void 0 ? { result } : { commitCursor, result }, 200, this.currentResponseBookmark);
+    return jsonResponse(commitCursor === void 0 ? { result } : { commitCursor, result }, 200, bookmarkHeaders(this.currentResponseBookmark));
   }
   /**
    * Commit a mutation's replay bookkeeping — the `(identity, mutationId)`
@@ -4055,7 +4255,7 @@ class ShardDO {
       }
       results.push({ body: outcome.body, id: outcome.id, status: outcome.status });
     }
-    return jsonResponse({ results }, 200, latestBookmark);
+    return jsonResponse({ results }, 200, bookmarkHeaders(latestBookmark));
   }
   /** Dispatch one batch entry through the single-call `/rpc` path and capture its envelope (plan 088). */
   async dispatchBatchEntry(batchRequest, entry) {
@@ -4063,12 +4263,12 @@ class ShardDO {
       const response = await this.fetch(buildBatchEntryRequest(batchRequest, entry));
       return { body: await response.json(), bookmark: response.headers.get("x-d1-bookmark") ?? void 0, id: entry.id, status: response.status };
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const { body, status } = toErrorBody(error, { fallbackCode: "BATCH_ENTRY_FAILED" });
       return {
-        body: { error: { code: "BATCH_ENTRY_FAILED", message } },
+        body: { error: body },
         bookmark: void 0,
         id: entry?.id,
-        status: 500
+        status
       };
     }
   }
@@ -4186,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);
     }
@@ -4395,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`.
@@ -4816,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
@@ -4846,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"] : "";

package/dist/packem_shared/{SESSION_DO_TTL_DEFAULT-ilPZsVwu.mjs → SESSION_DO_TTL_DEFAULT-D71QAL5h.mjs}

@@ -1,3 +1,5 @@
+import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
+
 const SESSION_DO_TTL_DEFAULT = 7 * 24 * 60 * 60;
 const SESSION_DO_TTL_MAX = 90 * 24 * 60 * 60;
 const SESSION_GC_INTERVAL_MS = 24 * 60 * 60 * 1e3;
@@ -7,10 +9,6 @@ const SESSION_TOKEN_PATTERN = /^[\w-]+$/;
 const MIN_TOKEN_LENGTH = 32;
 const MAX_TOKEN_LENGTH = 256;
 const MAX_USER_ID_LENGTH = 256;
-const jsonResponse = (status, body) => Response.json(body, {
-  headers: { "content-type": "application/json" },
-  status
-});
 const constantTimeEqual = (a, b) => {
   const max = Math.max(a.length, b.length);
   let diff = a.length ^ b.length;
@@ -68,7 +66,7 @@ class SessionDO {
   async fetch(request) {
     const env = this.env ?? {};
     if (!isAuthorized(request, env)) {
-      return jsonResponse(401, { error: { code: "UNAUTHORIZED", message: "missing or invalid SessionDO secret" } });
+      return jsonResponse({ error: { code: "UNAUTHORIZED", message: "missing or invalid SessionDO secret" } }, 401);
     }
     const url = new URL(request.url);
     if (request.method === "POST" && url.pathname === "/create") {
@@ -80,7 +78,7 @@ class SessionDO {
     if (request.method === "DELETE" && url.pathname === "/revoke") {
       return this.handleRevoke(request);
     }
-    return jsonResponse(404, { error: { code: "NOT_FOUND", message: "no such session route" } });
+    return jsonResponse({ error: { code: "NOT_FOUND", message: "no such session route" } }, 404);
   }
   /**
    * Sweep expired session records. Lazy expiry-on-read ({@link handleGet})
@@ -116,25 +114,25 @@ class SessionDO {
     try {
       body = await request.json();
     } catch {
-      return jsonResponse(400, { error: "invalid_request" });
+      return jsonResponse({ error: "invalid_request" }, 400);
     }
     const token = validateToken(body.token);
     if (token === void 0) {
-      return jsonResponse(400, { error: "invalid_request" });
+      return jsonResponse({ error: "invalid_request" }, 400);
     }
     const { userId } = body;
     if (typeof userId !== "string" || userId.length === 0 || userId.length > MAX_USER_ID_LENGTH) {
-      return jsonResponse(400, { error: "invalid_request" });
+      return jsonResponse({ error: "invalid_request" }, 400);
     }
     const ttlSeconds = resolveTtlSeconds(body.ttlSeconds);
     if (ttlSeconds === void 0) {
-      return jsonResponse(400, { error: "invalid_request" });
+      return jsonResponse({ error: "invalid_request" }, 400);
     }
     const now = Date.now();
     const record = { createdAt: now, expiresAt: now + ttlSeconds * 1e3, userId };
     await this.state.storage.put(`s:${token}`, record);
     await this.armGcAlarm();
-    return jsonResponse(201, { token, ...record });
+    return jsonResponse({ token, ...record }, 201);
   }
   /**
    * Ensure a GC alarm is pending. Only sets one when none is currently
@@ -155,25 +153,25 @@ class SessionDO {
   async handleGet(request) {
     const token = request.headers.get(SESSION_TOKEN_HEADER);
     if (!token) {
-      return jsonResponse(400, { error: { code: "INVALID_INPUT", message: "token required" } });
+      return jsonResponse({ error: { code: "INVALID_INPUT", message: "token required" } }, 400);
     }
     const record = await this.state.storage.get(`s:${token}`);
     if (!record) {
-      return jsonResponse(404, { error: { code: "NOT_FOUND", message: "session not found" } });
+      return jsonResponse({ error: { code: "NOT_FOUND", message: "session not found" } }, 404);
     }
     if (record.expiresAt < Date.now()) {
       await this.state.storage.delete(`s:${token}`);
-      return jsonResponse(404, { error: { code: "EXPIRED", message: "session expired" } });
+      return jsonResponse({ error: { code: "EXPIRED", message: "session expired" } }, 404);
     }
-    return jsonResponse(200, { token, ...record });
+    return jsonResponse({ token, ...record }, 200);
   }
   async handleRevoke(request) {
     const token = request.headers.get(SESSION_TOKEN_HEADER);
     if (!token) {
-      return jsonResponse(400, { error: { code: "INVALID_INPUT", message: "token required" } });
+      return jsonResponse({ error: { code: "INVALID_INPUT", message: "token required" } }, 400);
     }
     await this.state.storage.delete(`s:${token}`);
-    return jsonResponse(200, { ok: true });
+    return jsonResponse({ ok: true }, 200);
   }
 }
 

package/dist/packem_shared/{SHARD_REGISTRY_DO_NAME-BsAbi5Mn.mjs → SHARD_REGISTRY_DO_NAME-D99roc-r.mjs}

@@ -1,22 +1,20 @@
+import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
+
 const SHARD_REGISTRY_DO_NAME = "__lunora_shard_registry__";
 const STORAGE_KEY = "__tables__";
-const jsonResponse = (status, body) => Response.json(body, {
-  headers: { "content-type": "application/json" },
-  status
-});
 const readTableShardBody = async (request) => {
   let body;
   try {
     body = await request.json();
   } catch {
-    return { kind: "error", response: jsonResponse(400, { error: { code: "BAD_REQUEST", message: "invalid JSON body" } }) };
+    return { kind: "error", response: jsonResponse({ error: { code: "BAD_REQUEST", message: "invalid JSON body" } }, 400) };
   }
   const table = typeof body.table === "string" ? body.table.trim() : "";
   const shardKey = typeof body.shardKey === "string" ? body.shardKey.trim() : "";
   if (!table || !shardKey) {
     return {
       kind: "error",
-      response: jsonResponse(400, { error: { code: "BAD_REQUEST", message: "table and shardKey required" } })
+      response: jsonResponse({ error: { code: "BAD_REQUEST", message: "table and shardKey required" } }, 400)
     };
   }
   return { kind: "ok", value: { shardKey, table } };
@@ -56,7 +54,7 @@ class ShardRegistryDO {
     if (request.method === "GET" && url.pathname === "/snapshot") {
       return this.handleSnapshot();
     }
-    return jsonResponse(404, { error: { code: "NOT_FOUND", message: `unknown shard-registry route ${request.method} ${url.pathname}` } });
+    return jsonResponse({ error: { code: "NOT_FOUND", message: `unknown shard-registry route ${request.method} ${url.pathname}` } }, 404);
   }
   /**
    * Load the persisted snapshot exactly once. `blockConcurrencyWhile`
@@ -83,9 +81,9 @@ class ShardRegistryDO {
   handleList(url) {
     const table = url.searchParams.get("table");
     if (!table) {
-      return jsonResponse(400, { error: { code: "BAD_REQUEST", message: "missing required query parameter: table" } });
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: "missing required query parameter: table" } }, 400);
     }
-    return jsonResponse(200, { shardKeys: [...this.tables.get(table) ?? []] });
+    return jsonResponse({ shardKeys: [...this.tables.get(table) ?? []] }, 200);
   }
   async handleRegister(request) {
     const parsed = await readTableShardBody(request);
@@ -100,11 +98,11 @@ class ShardRegistryDO {
         this.tables.set(table, set);
       }
       if (set.has(shardKey)) {
-        return jsonResponse(200, { changed: false, ok: true });
+        return jsonResponse({ changed: false, ok: true }, 200);
       }
       set.add(shardKey);
       await this.persist();
-      return jsonResponse(200, { changed: true, ok: true });
+      return jsonResponse({ changed: true, ok: true }, 200);
     });
   }
   handleSnapshot() {
@@ -112,7 +110,7 @@ class ShardRegistryDO {
     for (const [table, set] of this.tables) {
       out[table] = [...set];
     }
-    return jsonResponse(200, { tables: out });
+    return jsonResponse({ tables: out }, 200);
   }
   async handleUnregister(request) {
     const parsed = await readTableShardBody(request);
@@ -123,14 +121,14 @@ class ShardRegistryDO {
     return this.state.blockConcurrencyWhile(async () => {
       const set = this.tables.get(table);
       if (!set?.has(shardKey)) {
-        return jsonResponse(200, { changed: false, ok: true });
+        return jsonResponse({ changed: false, ok: true }, 200);
       }
       set.delete(shardKey);
       if (set.size === 0) {
         this.tables.delete(table);
       }
       await this.persist();
-      return jsonResponse(200, { changed: true, ok: true });
+      return jsonResponse({ changed: true, ok: true }, 200);
     });
   }
   /** Serialize the in-memory map to a single JSON-safe object and put. */

package/dist/packem_shared/{exportShardRows-DZEhUeyI.mjs → exportShardRows-Dy3oFZ26.mjs}

@@ -1,3 +1,5 @@
+import { toErrorBody } from '@lunora/errors';
+
 const DEFAULT_BATCH_SIZE = 200;
 const selectExportTables = (schema, requested) => {
   const isShardLocal = (table) => {
@@ -107,9 +109,8 @@ const importOneRow = async (writer, schema, row, line) => {
     await writer.insert(table, doc, { allowExplicitId: true });
     return { kind: "inserted", table };
   } catch (error) {
-    const code = error.code ?? "INSERT_FAILED";
-    const message = error instanceof Error ? error.message : String(error);
-    return { error: { code, line, message, table }, kind: "error" };
+    const { body } = toErrorBody(error, { fallbackCode: "INSERT_FAILED" });
+    return { error: { code: body.code, line, message: body.message, table }, kind: "error" };
   }
 };
 const importShardRows = async (writer, schema, args) => {

package/dist/packem_shared/json-response-BdbtpOhm.mjs

@@ -0,0 +1,3 @@
+const jsonResponse = (body, status = 200, headers) => Response.json(body, { headers: { "content-type": "application/json", ...headers }, status });
+
+export { jsonResponse as j };

package/dist/packem_shared/{serveRelationFanout-C5axmGDj.mjs → serveRelationFanout-BhZF9AuB.mjs}

@@ -1,4 +1,4 @@
-import { RELATION_FUNCTION_PREFIX } from './ADMIN_FUNCTIONS-DSUQ5fX9.mjs';
+import { RELATION_FUNCTION_PREFIX } from './ADMIN_FUNCTIONS-BbQdj8h1.mjs';
 
 const serveRelationFanout = async (schema, database, functionPath, args) => {
   const table = typeof args["table"] === "string" ? args["table"] : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.24",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.1",
+    "@lunora/errors": "1.0.0-alpha.2",
     "@visulima/redact": "3.0.0-alpha.14",
     "drizzle-orm": "^0.45.2"
   },