@lunora/queue 1.0.0-alpha.11 → 1.0.0-alpha.110

package/README.md

@@ -26,18 +26,36 @@ import { api } from "./_generated/api";
 export const emailQueue = defineQueue<{ to: string }>({
     handler: async (ctx, batch) => {
         for (const message of batch.messages) {
-            await ctx.run(api.email.send, { to: message.body.to });
+            await message.run(api.email.send, { to: message.body.to });
             message.ack();
         }
     },
 });
 ```
 
+`message.run(...)` is `ctx.run(...)` pinned to that message. Call it inside the
+batch loop: when the dispatched function fails deterministically (`400`, `403`,
+`404`, `422`), the consumer acks just that message and retries the rest instead
+of letting one poison message retry — and eventually dead-letter — the whole
+batch.
+
 ```ts
 // inside a mutation/action
 await ctx.queues.emailQueue.send({ to: user.email });
 ```
 
+For one event with several consumers, declare a topic and subscribe to it.
+Each subscription is its own queue, with its own retries and dead-letter queue:
+
+```ts
+// lunora/queues.ts
+export const signups = defineTopic<{ userId: string }>();
+export const welcomeEmail = defineSubscription(signups, { handler: async (ctx, batch) => {} });
+
+// inside a mutation/action
+await ctx.topics.signups.publish({ userId });
+```
+
 Codegen emits the typed `ctx.queues` producer and the worker `queue()` dispatch;
 `@lunora/config` reconciles the wrangler `queues.producers[]` /
 `queues.consumers[]` entries from the same definition. Scaffold a new queue with

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { QueueBindingLike, MessageBatchLike, MessageLike, QueueSendOptions, MessageSendRequestLike, QueueSendBatchOptions } from '@lunora/platform';
+export type { MessageBatchLike, MessageLike, MessageSendRequestLike, QueueBindingLike, QueueContentType, QueueRetryOptions, QueueSendBatchOptions, QueueSendOptions } from '@lunora/platform';
 /**
  * Shared types for dispatching a Lunora function back into the worker from a
  * server-initiated context (a workflow body, a queue handler, a scheduled job).
@@ -12,8 +14,45 @@ interface FunctionReference {
 type ArgsOf<F> = F extends FunctionReference ? Record<string, unknown> : never;
 /** Options for a function call made via a dispatch runner. */
 interface RunFunctionOptions {
+  /**
+   * The at-least-once dedup key for THIS ONE CALL, sent to the dispatch
+   * endpoint as the body's `id` and forwarded to the shard as the
+   * replay-dedup `mutationId` — so a redelivery that re-runs the same call
+   * applies it exactly once instead of twice.
+   *
+   * Must be unique per call and stable across redeliveries. It is NOT
+   * {@link RunFunctionOptions.messageId}: the shard's dedup table is keyed
+   * `(identity, mutationId)` with no function path in it, and every
+   * server-initiated dispatch shares the `"system:"` identity, so reusing
+   * one id across two calls makes the second return the FIRST call's cached
+   * result without ever executing. A per-message id is 1:N with the calls a
+   * handler makes; this is 1:1.
+   *
+   * `@lunora/queue`'s `message.run` derives one automatically as
+   * `<messageId>#<n>`, `n` counting that message's calls in order. That is
+   * stable across redeliveries because the handler replays from the start —
+   * it relies on the handler issuing its `run` calls in a DETERMINISTIC
+   * order, which at-least-once replay already assumes. A handler whose call
+   * order varies per attempt (branching on `Date.now()`, `Math.random()`,
+   * or unordered concurrent settles) must pass its own stable ids instead.
+   *
+   * Optional; when omitted the dispatch is at-least-once.
+   */
+  dedupId?: string;
+  /**
+   * Correlate this call with a caller-defined message/item id (e.g. a queue
+   * message's `id`), for failure attribution only — never sent to the
+   * dispatch endpoint. Carried onto the `LunoraError` a deterministic
+   * dispatch failure throws, so a batching consumer (`@lunora/queue`'s push
+   * handler) can read it back and attribute the failure to the one item that
+   * caused it instead of the whole batch. Deliberately NOT the dedup key —
+   * see {@link RunFunctionOptions.dedupId}. Optional and inert when omitted.
+   */
+  messageId?: string;
   /** Route the call to a specific shard (defaults to the worker's root shard). */
   shardKey?: string;
+  /** Abort the dispatch after this many ms; the abort is retryable. Overrides the runner's default. */
+  timeoutMs?: number;
 }
 /** Invoke a Lunora function (query/mutation/action) by reference. The shape of `ctx.run`. */
 type DispatchRunFunction = <F extends FunctionReference>(function_: F, args?: ArgsOf<F>, options?: RunFunctionOptions) => Promise<unknown>;
@@ -24,62 +63,8 @@ interface DispatchLogger {
   info: (message: unknown, ...rest: unknown[]) => void;
   warn: (message: unknown, ...rest: unknown[]) => void;
 }
-/** How a queue message body is serialized on the wire (Cloudflare default `"json"`). */
-type QueueContentType = "bytes" | "json" | "text" | "v8";
-/** Options for a single `producer.send(body, options?)`. */
-interface QueueSendOptions {
-  /** Wire serialization for this message (defaults to the queue's content type). */
-  contentType?: QueueContentType;
-  /** Per-message delivery delay in seconds (0–43200, i.e. up to 12 hours). */
-  delaySeconds?: number;
-}
-/** Options for a `producer.sendBatch(messages, options?)`. */
-interface QueueSendBatchOptions {
-  /** Delivery delay applied to the whole batch, in seconds. */
-  delaySeconds?: number;
-}
-/** One entry in a `sendBatch` call — a body plus optional per-message overrides. */
-interface MessageSendRequestLike<Body = unknown> {
-  body: Body;
-  contentType?: QueueContentType;
-  delaySeconds?: number;
-}
-/**
- * Minimal structural projection of workers-types' `Queue&lt;Body>` (the producer
- * binding). The real binding's `send`/`sendBatch` resolve to a metadata object;
- * we widen the return to `Promise&lt;unknown>` so a plain-object fake satisfies it.
- */
-interface QueueBindingLike<Body = unknown> {
-  send: (message: Body, options?: QueueSendOptions) => Promise<unknown>;
-  sendBatch: (messages: Iterable<MessageSendRequestLike<Body>>, options?: QueueSendBatchOptions) => Promise<unknown>;
-}
-/** Options for retrying a message / batch (`message.retry({ delaySeconds })`). */
-interface QueueRetryOptions {
-  delaySeconds?: number;
-}
-/** Structural mirror of workers-types' `Message&lt;Body>` (one delivered message). */
-interface MessageLike<Body = unknown> {
-  /** Acknowledge this message so it is not redelivered. */
-  ack: () => void;
-  readonly attempts: number;
-  readonly body: Body;
-  readonly id: string;
-  /** Explicitly retry this message (optionally after a delay). */
-  retry: (options?: QueueRetryOptions) => void;
-  readonly timestamp: Date;
-}
-/** Structural mirror of workers-types' `MessageBatch&lt;Body>` handed to a consumer. */
-interface MessageBatchLike<Body = unknown> {
-  /** Acknowledge every message in the batch. */
-  ackAll: () => void;
-  readonly messages: ReadonlyArray<MessageLike<Body>>;
-  /** The queue name this batch was delivered from (`batch.queue`), used to route. */
-  readonly queue: string;
-  /** Retry every message in the batch (optionally after a delay). */
-  retryAll: (options?: QueueRetryOptions) => void;
-}
 /**
- * The typed producer bound to `ctx.queues.&lt;name>`. Sending is a side effect, so
+ * The typed producer bound to `ctx.queues.<name>`. Sending is a side effect, so
  * the generated context exposes this only on `MutationCtx` / `ActionCtx` (never
  * the deterministic `QueryCtx`), mirroring `ctx.scheduler` / `ctx.workflows`.
  */
@@ -91,16 +76,16 @@ interface QueueProducer<Body = unknown> {
 }
 /**
  * `ctx.queues` — the map of declared queue export names → typed producers.
- * Codegen narrows this to the exact export names; the package keeps it open so
- * `createQueues` stays schema-agnostic.
+ * Keyed by the exact export names `createQueueContext` / `createQueues` are
+ * handed, so `queues.jobs` is a `QueueProducer` rather than `QueueProducer |
+ * undefined` under `noUncheckedIndexedAccess`. `Name` defaults to `string`
+ * (an open map) for schema-agnostic callers.
  */
-interface Queues {
-  [exportName: string]: QueueProducer;
-}
+type Queues<Name extends string = string> = Readonly<Record<Name, QueueProducer>>;
 /** Options the package-level `createQueues` factory takes. */
-interface LunoraQueuesOptions {
+interface LunoraQueuesOptions<Name extends string = string> {
   /** Map of `lunora/queues.ts` export name → Cloudflare `Queue` producer binding. */
-  bindings: Record<string, QueueBindingLike>;
+  bindings: Record<Name, QueueBindingLike>;
 }
 /**
  * The context handed to a `defineQueue` handler. Decoupled from `@lunora/server`
@@ -113,13 +98,39 @@ interface QueueRunContext {
   readonly env: Record<string, unknown>;
   /** Queue-name-prefixed logger. */
   readonly log: DispatchLogger;
-  /** Invoke a Lunora function (query/mutation/action) by reference. */
+  /**
+   * Invoke a Lunora function (query/mutation/action) by reference.
+   *
+   * Batch-unaware: a failure it throws is attributed to nothing, so a
+   * deterministic failure retries the whole batch. Inside the `batch.messages`
+   * loop, prefer {@link QueueMessage.run}, which pins the call to its message.
+   */
   readonly run: DispatchRunFunction;
 }
+/**
+ * One delivered message as the push handler sees it: the Cloudflare `Message`
+ * plus `run` — a {@link QueueRunContext.run} pinned to THIS message.
+ *
+ * Prefer `message.run(api.x.y, args)` over `ctx.run(...)` inside the batch
+ * loop. The pin is what lets the dispatcher attribute a deterministic dispatch
+ * failure (400/403/404/422) to the one message that caused it: that message is
+ * acked and every other one is retried, instead of the whole batch being
+ * re-delivered because of a single poison message. A plain `ctx.run` call
+ * carries no message id, so its failure stays unattributed and the whole batch
+ * retries.
+ */
+interface QueueMessage<Body = unknown> extends MessageLike<Body> {
+  /** {@link QueueRunContext.run}, pinned to this message for failure attribution. */
+  readonly run: DispatchRunFunction;
+}
+/** The delivered batch as the push handler sees it — {@link QueueMessage}s rather than bare `Message`s. */
+interface QueueMessageBatch<Body = unknown> extends Omit<MessageBatchLike<Body>, "messages"> {
+  readonly messages: ReadonlyArray<QueueMessage<Body>>;
+}
 /** Whether a declared queue is consumed by this worker (push) or polled externally (pull). */
 type QueueConsumerMode = "pull" | "push";
 /** The handler body run for each delivered batch (push consumers only). */
-type QueueHandler<Body = unknown> = (context: QueueRunContext, batch: MessageBatchLike<Body>) => Promise<void> | void;
+type QueueHandler<Body = unknown> = (context: QueueRunContext, batch: QueueMessageBatch<Body>) => Promise<void> | void;
 /** Push-consumer batch/retry tuning, mirrored onto the wrangler `queues.consumers[]` entry. */
 interface QueueConsumerTuning {
   /** Name of the dead-letter queue messages land in after `maxRetries`. */
@@ -128,7 +139,9 @@ interface QueueConsumerTuning {
   maxBatchSize?: number;
   /** Max seconds to wait before delivering a partial batch (0–60, default 5). */
   maxBatchTimeout?: number;
-  /** Max delivery attempts before a message is dropped / dead-lettered (default 3). */
+  /** Max concurrent consumer invocations (1–250). Unset lets Cloudflare autoscale. Not emulated by Miniflare in dev. */
+  maxConcurrency?: number;
+  /** Retries **after** the initial delivery, before a message is dropped / dead-lettered. Default 3, so up to 4 deliveries in total. */
   maxRetries?: number;
   /** Delay in seconds before a failed batch is retried. */
   retryDelay?: number;
@@ -152,29 +165,92 @@ interface QueueConfig<Body = unknown> extends QueueConsumerTuning {
 interface QueueDefinition<Body = unknown> extends QueueConfig<Body> {
   /**
    * Phantom carrier for the message body type, so codegen can type the
-   * generated `ctx.queues.&lt;name>` producer as `QueueProducer&lt;Body>` from
-   * `typeof &lt;export>`. Never assigned at runtime (type-only).
+   * generated `ctx.queues.<name>` producer as `QueueProducer<Body>` from
+   * `typeof <export>`. Never assigned at runtime (type-only).
    */
   readonly __lunoraBody?: Body;
   /** Runtime brand identifying a `defineQueue` result. */
   isLunoraQueue: true;
 }
+/**
+ * The typed publisher bound to `ctx.topics.<name>`. A publish is one send to
+ * **each** subscription's queue, in parallel, so it is not atomic: when one send
+ * fails the call rejects, and a retry re-delivers to the subscriptions whose send
+ * already succeeded. Delivery is at-least-once per subscription — make handlers
+ * idempotent. A topic with no subscriptions publishes to nobody.
+ */
+interface TopicPublisher<Payload = unknown> {
+  /** Publish one message to every subscription. */
+  publish: (payload: Payload, options?: QueueSendOptions) => Promise<void>;
+  /** Publish a batch (at most 100) to every subscription in one send per subscription. */
+  publishBatch: (messages: Iterable<MessageSendRequestLike<Payload>>, options?: QueueSendBatchOptions) => Promise<void>;
+}
+/** `ctx.topics` — declared topic export names → typed publishers, keyed like {@link Queues}. */
+type Topics<Name extends string = string> = Readonly<Record<Name, TopicPublisher>>;
+/** The branded result of `defineTopic`, discovered by codegen. Carries no deploy config of its own. */
+interface TopicDefinition<Payload = unknown> {
+  /**
+   * Phantom carrier for the payload type, so codegen can type `ctx.topics.<name>`.
+   * Named like {@link QueueDefinition}'s so one emitted helper reads both. Never
+   * assigned at runtime.
+   */
+  readonly __lunoraBody?: Payload;
+  /** Runtime brand identifying a `defineTopic` result. */
+  isLunoraTopic: true;
+}
+/** The config passed to `defineSubscription`: a push consumer's handler plus its own retry/DLQ tuning. */
+interface SubscriptionConfig<Payload = unknown> extends QueueConsumerTuning {
+  handler: QueueHandler<Payload>;
+  /**
+   * Stable wrangler queue name for this subscription. Defaults to the
+   * kebab-cased export name, exactly like a `defineQueue` export.
+   */
+  name?: string;
+}
+/**
+ * The branded result of `defineSubscription`: a push {@link QueueDefinition}
+ * (so dispatch, retries, the DLQ, wrangler reconcile and the studio treat it as
+ * the queue it is) tagged with the topic it consumes.
+ */
+interface SubscriptionDefinition<Payload = unknown> extends QueueDefinition<Payload> {
+  handler: QueueHandler<Payload>;
+  mode: "push";
+  /** The topic this subscription consumes. */
+  topic: TopicDefinition<Payload>;
+}
+/** Wiring info for one declared topic, emitted by codegen into the generated shard. */
+interface TopicBindingSpec<Name extends string = string> {
+  /** The `lunora/queues.ts` topic export name, e.g. `signups`. */
+  exportName: Name;
+  /** One entry per subscription: its export name and its `Queue` producer binding. */
+  subscriptions: ReadonlyArray<{
+    binding: string;
+    exportName: string;
+  }>;
+}
 /** Wiring info for one declared queue, emitted by codegen into the generated shard/handler. */
-interface QueueBindingSpec {
+interface QueueBindingSpec<Name extends string = string> {
   /** The Cloudflare `Queue` producer binding name, e.g. `QUEUE_EMAIL`. */
   binding: string;
   /** The `lunora/queues.ts` export name, e.g. `emailQueue`. */
-  exportName: string;
+  exportName: Name;
   /** The stable wrangler queue name, e.g. `email-queue`. */
   name: string;
 }
 /** One declared queue, keyed for batch routing by its stable wrangler name. */
 interface QueueRegistryEntry {
+  /**
+   * The queue's own producer binding on `env` (`QUEUE_*`). A message whose
+   * dispatch is declined on its last delivery is re-enqueued through it (see
+   * {@link resolveDeclinedBatch}); without it that message is dead-lettered or
+   * dropped, and logged. Codegen always emits it.
+   */
+  binding?: string;
   /**
    * The `defineQueue` result (carries the push handler). The body type is
    * erased to `any` here because the registry is heterogeneous — different
    * queues carry different message bodies, and the handler param is
-   * contravariant, so a precise `QueueDefinition&lt;Body>` would not be assignable
+   * contravariant, so a precise `QueueDefinition<Body>` would not be assignable
    * to a shared `unknown`-bodied slot. Runtime dispatch passes the delivered
    * batch straight through, so the erasure is type-only.
    */
@@ -197,7 +273,28 @@ interface CapturedQueueMessage {
   attempts: number;
   /** The message body (JSON-encoded + capped by the catcher). */
   body: unknown;
-  /** `true` when this failed delivery was the message's last (its retries are exhausted — the broker dead-letters it). */
+  /**
+   * `true` when this failed delivery was the message's last (its retries are
+   * exhausted) AND the queue declares a `deadLetterQueue` for it to land in.
+   * Stays `false` for a queue with no DLQ, where the broker drops the
+   * exhausted message instead — `attempts > maxRetries` with
+   * `outcome !== "ack"` is what identifies that case.
+   *
+   * Read from the `defineQueue` DECLARATION, because a consumer has no
+   * runtime API that exposes its deployed `queues.consumers[]` settings. It is
+   * true of the deployed broker only as far as Lunora's binding reconcile (run
+   * by `lunora dev`, `deploy` and `prepare`) keeps the two in step: it writes
+   * every declared tuning field onto the consumer, including onto one that
+   * already exists, and takes a field back out once `defineQueue` drops it
+   * (it records what `defineQueue` declared in `package.json`
+   * `lunora.queueTuning`). The gaps that remain: a field changed by hand to
+   * another value than the declared one is
+   * kept when the declaration drops it, so a hand-set DLQ still reads
+   * `false` here; a `--env` deploy retunes the `env.<name>` consumers but
+   * never writes their `dead_letter_queue`, which that block names itself;
+   * and a bare `wrangler deploy` over a hand-edited consumer can disagree
+   * too. Nothing on this side can see any of it.
+   */
   deadLettered: boolean;
   /** Handler error message when `outcome` is `error`; absent otherwise. */
   error?: string;
@@ -221,22 +318,33 @@ interface CapturedQueueMessage {
 type QueueCaptureSink = (messages: CapturedQueueMessage[]) => Promise<void> | void;
 interface DispatchOptions {
   /**
-   * Optional capture sink. When set, the batch is instrumented and every
-   * message's final disposition is recorded and handed to this sink after the
-   * handler runs. Omitted in production unless queue capture is enabled, so a
-   * consumer pays no instrumentation cost by default.
+   * Optional capture sink. When set, every message's final disposition is
+   * turned into a record and handed to this sink after the handler runs.
+   * Omitted in production unless queue capture is enabled, so a consumer pays
+   * no record-building or sink cost by default. Delivery semantics — including
+   * poison-message isolation — do not depend on it.
    */
   capture?: QueueCaptureSink;
   /** Worker `env`, forwarded to the queue run context. */
   env: Record<string, unknown>;
   /** Injectable fetch for the `ctx.run` dispatcher (tests). */
   fetchImpl?: typeof fetch;
+  /**
+   * W3C `traceparent` of the consumer invocation's own trace, supplied by the
+   * runtime's `queue()` entry. Forwarded on every `ctx.run` dispatch so the
+   * functions a handler calls are CHILDREN of the queue span instead of a set of
+   * unrelated root traces. Absent (a hand-built dispatch, a unit test) keeps the
+   * prior behaviour: the callee mints its own trace.
+   */
+  traceparent?: string;
 }
 /**
  * Look up the handler for `batch.queue` and invoke it with a fresh
  * `QueueRunContext`. Throws a directed error when no push handler is registered
  * for the delivered queue (a misconfiguration — the consumer was declared
- * `pull`, or the queue name drifted from the `defineQueue` export).
+ * `pull`, or the queue name drifted from the `defineQueue` export). The
+ * registry already carries every per-environment name wrangler.jsonc maps to a
+ * declared producer binding (see codegen's `emitQueues`), so the lookup stays exact.
  */
 declare const dispatchQueueBatch: (batch: MessageBatchLike, registry: QueueRegistry, options: DispatchOptions) => Promise<void>;
 /** A Worker `env` projected as a plain record (vars, secrets, and bindings are `unknown`-valued). */
@@ -268,21 +376,21 @@ declare const createQueueCaptureSink: (env: QueueEnv, options?: QueueCaptureOpti
  * Build the `ctx.queues` map for a request: resolve every spec's `env[binding]`
  * into the `exportName → Queue binding` map and wrap it in {@link createQueues}.
  * A spec whose binding is absent from `env` is skipped here — the helpful "no
- * queue named …" error is raised lazily by `ctx.queues.&lt;name>.send(...)` when
+ * queue named …" error is raised lazily by `ctx.queues.<name>.send(...)` when
  * the missing queue is actually used.
  */
-declare const createQueueContext: (env: Record<string, unknown>, specs: ReadonlyArray<QueueBindingSpec>) => Queues;
+declare const createQueueContext: <Name extends string>(env: Record<string, unknown>, specs: ReadonlyArray<QueueBindingSpec<Name>>) => Queues<Name>;
 /**
  * Build the `ctx.queues` map from `lunora/queues.ts` export name → Cloudflare
  * `Queue` binding. Each property is a typed {@link QueueProducer}; accessing an
  * export whose binding is absent throws a directed error naming the declared
  * queues (raised lazily on first use).
  */
-declare const createQueues: (options: LunoraQueuesOptions) => Queues;
+declare const createQueues: <Name extends string>(options: LunoraQueuesOptions<Name>) => Queues<Name>;
 /**
  * The wrangler producer binding name for a queue export: `emailQueue` →
  * `QUEUE_EMAIL_QUEUE`, `email` → `QUEUE_EMAIL`. The `QUEUE_` prefix namespaces
- * these away from `SHARD`/`SESSION`/`SCHEDULER`/`WORKFLOW_*`/`CONTAINER_*` so a
+ * these away from `SHARD`/`SESSION`/`SCHEDULER`/`CONTAINER_*` so a
  * queue export can never collide with the built-in bindings.
  */
 declare const queueBindingName: (exportName: string) => string;
@@ -294,7 +402,7 @@ declare const queueBindingName: (exportName: string) => string;
 declare const queueDefaultName: (exportName: string) => string;
 /**
  * Declare a Cloudflare Queue deployed alongside the app. Pure validation +
- * branding: codegen discovers the export, emits the typed `ctx.queues.&lt;name>`
+ * branding: codegen discovers the export, emits the typed `ctx.queues.<name>`
  * producer and (for push consumers) the worker `queue()` dispatch; the config
  * layer reconciles the wrangler `queues.producers[]` / `queues.consumers[]`
  * entries from the same definition.
@@ -304,10 +412,10 @@ declare const queueDefaultName: (exportName: string) => string;
  * import { defineQueue } from "@lunora/queue";
  * import { api } from "./_generated/api";
  *
- * export const emailQueue = defineQueue&lt;{ to: string }>({
+ * export const emailQueue = defineQueue<{ to: string }>({
  *     handler: async (ctx, batch) => {
  *         for (const message of batch.messages) {
- *             await ctx.run(api.email.send, { to: message.body.to });
+ *             await message.run(api.email.send, { to: message.body.to });
  *             message.ack();
  *         }
  *     },
@@ -316,6 +424,12 @@ declare const queueDefaultName: (exportName: string) => string;
  *
  * Enqueue from a mutation or action: `await ctx.queues.emailQueue.send({ to })`.
  *
+ * `message.run(...)` is `ctx.run(...)` pinned to that message — prefer it inside
+ * the batch loop. A deterministic failure (400/403/404/422) from a pinned call
+ * is attributed to its message: that one is acked and the rest are retried,
+ * instead of one poison message re-delivering (and eventually dead-lettering)
+ * the whole batch.
+ *
  * ⚠️ **Privileged dispatch.** A push handler's `ctx.run(...)` calls back into
  * Lunora functions over the admin-authenticated dispatch endpoint (the same
  * trusted path the scheduler and workflows use), so those calls run with the
@@ -331,7 +445,29 @@ interface RunContextOptions {
   env: Record<string, unknown>;
   exportName: string;
   fetchImpl?: typeof fetch;
+  /** The consumer invocation's `traceparent`, so `ctx.run` joins the queue's trace. */
+  traceparent?: string;
 }
 /** Assemble the {@link QueueRunContext} passed to a `defineQueue` handler. */
 declare const createQueueRunContext: (options: RunContextOptions) => QueueRunContext;
-export { type ArgsOf, type CapturedQueueMessage, type FunctionReference, type LunoraQueuesOptions, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, type QueueBindingLike, type QueueBindingSpec, type QueueCaptureOptions, type QueueCaptureSink, type QueueConfig, type QueueConsumerMode, type QueueConsumerTuning, type QueueContentType, type QueueDefinition, type QueueEnv, type QueueHandler, type DispatchLogger as QueueLogger, type QueueProducer, type QueueRegistry, type QueueRegistryEntry, type QueueRetryOptions, type QueueRunContext, type DispatchRunFunction as QueueRunFunction, type QueueSendBatchOptions, type QueueSendOptions, type Queues, type RunFunctionOptions, createQueueCaptureSink, createQueueContext, createQueueRunContext, createQueues, defineQueue, dispatchQueueBatch, isQueueDefinition, queueBindingName, queueDefaultName, shouldCaptureQueue };
+/**
+ * Declare a topic in `lunora/queues.ts`. The payload type is the only thing a
+ * topic carries; delivery config lives on each subscription.
+ */
+declare const defineTopic: <Payload = unknown>() => TopicDefinition<Payload>;
+/**
+ * Subscribe to a topic. The result is a push queue definition — export it from
+ * `lunora/queues.ts` and it deploys, retries and dead-letters exactly like a
+ * `defineQueue` export of the same name.
+ *
+ * ⚠️ Same trust model as a queue handler: `message.run(...)` dispatches with the
+ * system identity, so validate `message.body` before acting on it.
+ */
+declare const defineSubscription: <Payload>(topic: TopicDefinition<Payload>, config: SubscriptionConfig<Payload>) => SubscriptionDefinition<Payload>;
+/**
+ * Build `ctx.topics` for a request from the Worker `env` and the codegen-emitted
+ * specs. A topic with no subscriptions publishes to nobody; a topic with an
+ * unbound subscription rejects every publish (see {@link unboundPublisher}).
+ */
+declare const createTopicContext: <Name extends string>(env: Record<string, unknown>, specs: ReadonlyArray<TopicBindingSpec<Name>>) => Topics<Name>;
+export { type ArgsOf, type CapturedQueueMessage, type FunctionReference, type LunoraQueuesOptions, type QueueBindingSpec, type QueueCaptureOptions, type QueueCaptureSink, type QueueConfig, type QueueConsumerMode, type QueueConsumerTuning, type QueueDefinition, type QueueEnv, type QueueHandler, type DispatchLogger as QueueLogger, type QueueMessage, type QueueMessageBatch, type QueueProducer, type QueueRegistry, type QueueRegistryEntry, type QueueRunContext, type DispatchRunFunction as QueueRunFunction, type Queues, type RunFunctionOptions, type SubscriptionConfig, type SubscriptionDefinition, type TopicBindingSpec, type TopicDefinition, type TopicPublisher, type Topics, createQueueCaptureSink, createQueueContext, createQueueRunContext, createQueues, createTopicContext, defineQueue, defineSubscription, defineTopic, dispatchQueueBatch, isQueueDefinition, queueBindingName, queueDefaultName, shouldCaptureQueue };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { QueueBindingLike, MessageBatchLike, MessageLike, QueueSendOptions, MessageSendRequestLike, QueueSendBatchOptions } from '@lunora/platform';
+export type { MessageBatchLike, MessageLike, MessageSendRequestLike, QueueBindingLike, QueueContentType, QueueRetryOptions, QueueSendBatchOptions, QueueSendOptions } from '@lunora/platform';
 /**
  * Shared types for dispatching a Lunora function back into the worker from a
  * server-initiated context (a workflow body, a queue handler, a scheduled job).
@@ -12,8 +14,45 @@ interface FunctionReference {
 type ArgsOf<F> = F extends FunctionReference ? Record<string, unknown> : never;
 /** Options for a function call made via a dispatch runner. */
 interface RunFunctionOptions {
+  /**
+   * The at-least-once dedup key for THIS ONE CALL, sent to the dispatch
+   * endpoint as the body's `id` and forwarded to the shard as the
+   * replay-dedup `mutationId` — so a redelivery that re-runs the same call
+   * applies it exactly once instead of twice.
+   *
+   * Must be unique per call and stable across redeliveries. It is NOT
+   * {@link RunFunctionOptions.messageId}: the shard's dedup table is keyed
+   * `(identity, mutationId)` with no function path in it, and every
+   * server-initiated dispatch shares the `"system:"` identity, so reusing
+   * one id across two calls makes the second return the FIRST call's cached
+   * result without ever executing. A per-message id is 1:N with the calls a
+   * handler makes; this is 1:1.
+   *
+   * `@lunora/queue`'s `message.run` derives one automatically as
+   * `<messageId>#<n>`, `n` counting that message's calls in order. That is
+   * stable across redeliveries because the handler replays from the start —
+   * it relies on the handler issuing its `run` calls in a DETERMINISTIC
+   * order, which at-least-once replay already assumes. A handler whose call
+   * order varies per attempt (branching on `Date.now()`, `Math.random()`,
+   * or unordered concurrent settles) must pass its own stable ids instead.
+   *
+   * Optional; when omitted the dispatch is at-least-once.
+   */
+  dedupId?: string;
+  /**
+   * Correlate this call with a caller-defined message/item id (e.g. a queue
+   * message's `id`), for failure attribution only — never sent to the
+   * dispatch endpoint. Carried onto the `LunoraError` a deterministic
+   * dispatch failure throws, so a batching consumer (`@lunora/queue`'s push
+   * handler) can read it back and attribute the failure to the one item that
+   * caused it instead of the whole batch. Deliberately NOT the dedup key —
+   * see {@link RunFunctionOptions.dedupId}. Optional and inert when omitted.
+   */
+  messageId?: string;
   /** Route the call to a specific shard (defaults to the worker's root shard). */
   shardKey?: string;
+  /** Abort the dispatch after this many ms; the abort is retryable. Overrides the runner's default. */
+  timeoutMs?: number;
 }
 /** Invoke a Lunora function (query/mutation/action) by reference. The shape of `ctx.run`. */
 type DispatchRunFunction = <F extends FunctionReference>(function_: F, args?: ArgsOf<F>, options?: RunFunctionOptions) => Promise<unknown>;
@@ -24,62 +63,8 @@ interface DispatchLogger {
   info: (message: unknown, ...rest: unknown[]) => void;
   warn: (message: unknown, ...rest: unknown[]) => void;
 }
-/** How a queue message body is serialized on the wire (Cloudflare default `"json"`). */
-type QueueContentType = "bytes" | "json" | "text" | "v8";
-/** Options for a single `producer.send(body, options?)`. */
-interface QueueSendOptions {
-  /** Wire serialization for this message (defaults to the queue's content type). */
-  contentType?: QueueContentType;
-  /** Per-message delivery delay in seconds (0–43200, i.e. up to 12 hours). */
-  delaySeconds?: number;
-}
-/** Options for a `producer.sendBatch(messages, options?)`. */
-interface QueueSendBatchOptions {
-  /** Delivery delay applied to the whole batch, in seconds. */
-  delaySeconds?: number;
-}
-/** One entry in a `sendBatch` call — a body plus optional per-message overrides. */
-interface MessageSendRequestLike<Body = unknown> {
-  body: Body;
-  contentType?: QueueContentType;
-  delaySeconds?: number;
-}
-/**
- * Minimal structural projection of workers-types' `Queue&lt;Body>` (the producer
- * binding). The real binding's `send`/`sendBatch` resolve to a metadata object;
- * we widen the return to `Promise&lt;unknown>` so a plain-object fake satisfies it.
- */
-interface QueueBindingLike<Body = unknown> {
-  send: (message: Body, options?: QueueSendOptions) => Promise<unknown>;
-  sendBatch: (messages: Iterable<MessageSendRequestLike<Body>>, options?: QueueSendBatchOptions) => Promise<unknown>;
-}
-/** Options for retrying a message / batch (`message.retry({ delaySeconds })`). */
-interface QueueRetryOptions {
-  delaySeconds?: number;
-}
-/** Structural mirror of workers-types' `Message&lt;Body>` (one delivered message). */
-interface MessageLike<Body = unknown> {
-  /** Acknowledge this message so it is not redelivered. */
-  ack: () => void;
-  readonly attempts: number;
-  readonly body: Body;
-  readonly id: string;
-  /** Explicitly retry this message (optionally after a delay). */
-  retry: (options?: QueueRetryOptions) => void;
-  readonly timestamp: Date;
-}
-/** Structural mirror of workers-types' `MessageBatch&lt;Body>` handed to a consumer. */
-interface MessageBatchLike<Body = unknown> {
-  /** Acknowledge every message in the batch. */
-  ackAll: () => void;
-  readonly messages: ReadonlyArray<MessageLike<Body>>;
-  /** The queue name this batch was delivered from (`batch.queue`), used to route. */
-  readonly queue: string;
-  /** Retry every message in the batch (optionally after a delay). */
-  retryAll: (options?: QueueRetryOptions) => void;
-}
 /**
- * The typed producer bound to `ctx.queues.&lt;name>`. Sending is a side effect, so
+ * The typed producer bound to `ctx.queues.<name>`. Sending is a side effect, so
  * the generated context exposes this only on `MutationCtx` / `ActionCtx` (never
  * the deterministic `QueryCtx`), mirroring `ctx.scheduler` / `ctx.workflows`.
  */
@@ -91,16 +76,16 @@ interface QueueProducer<Body = unknown> {
 }
 /**
  * `ctx.queues` — the map of declared queue export names → typed producers.
- * Codegen narrows this to the exact export names; the package keeps it open so
- * `createQueues` stays schema-agnostic.
+ * Keyed by the exact export names `createQueueContext` / `createQueues` are
+ * handed, so `queues.jobs` is a `QueueProducer` rather than `QueueProducer |
+ * undefined` under `noUncheckedIndexedAccess`. `Name` defaults to `string`
+ * (an open map) for schema-agnostic callers.
  */
-interface Queues {
-  [exportName: string]: QueueProducer;
-}
+type Queues<Name extends string = string> = Readonly<Record<Name, QueueProducer>>;
 /** Options the package-level `createQueues` factory takes. */
-interface LunoraQueuesOptions {
+interface LunoraQueuesOptions<Name extends string = string> {
   /** Map of `lunora/queues.ts` export name → Cloudflare `Queue` producer binding. */
-  bindings: Record<string, QueueBindingLike>;
+  bindings: Record<Name, QueueBindingLike>;
 }
 /**
  * The context handed to a `defineQueue` handler. Decoupled from `@lunora/server`
@@ -113,13 +98,39 @@ interface QueueRunContext {
   readonly env: Record<string, unknown>;
   /** Queue-name-prefixed logger. */
   readonly log: DispatchLogger;
-  /** Invoke a Lunora function (query/mutation/action) by reference. */
+  /**
+   * Invoke a Lunora function (query/mutation/action) by reference.
+   *
+   * Batch-unaware: a failure it throws is attributed to nothing, so a
+   * deterministic failure retries the whole batch. Inside the `batch.messages`
+   * loop, prefer {@link QueueMessage.run}, which pins the call to its message.
+   */
   readonly run: DispatchRunFunction;
 }
+/**
+ * One delivered message as the push handler sees it: the Cloudflare `Message`
+ * plus `run` — a {@link QueueRunContext.run} pinned to THIS message.
+ *
+ * Prefer `message.run(api.x.y, args)` over `ctx.run(...)` inside the batch
+ * loop. The pin is what lets the dispatcher attribute a deterministic dispatch
+ * failure (400/403/404/422) to the one message that caused it: that message is
+ * acked and every other one is retried, instead of the whole batch being
+ * re-delivered because of a single poison message. A plain `ctx.run` call
+ * carries no message id, so its failure stays unattributed and the whole batch
+ * retries.
+ */
+interface QueueMessage<Body = unknown> extends MessageLike<Body> {
+  /** {@link QueueRunContext.run}, pinned to this message for failure attribution. */
+  readonly run: DispatchRunFunction;
+}
+/** The delivered batch as the push handler sees it — {@link QueueMessage}s rather than bare `Message`s. */
+interface QueueMessageBatch<Body = unknown> extends Omit<MessageBatchLike<Body>, "messages"> {
+  readonly messages: ReadonlyArray<QueueMessage<Body>>;
+}
 /** Whether a declared queue is consumed by this worker (push) or polled externally (pull). */
 type QueueConsumerMode = "pull" | "push";
 /** The handler body run for each delivered batch (push consumers only). */
-type QueueHandler<Body = unknown> = (context: QueueRunContext, batch: MessageBatchLike<Body>) => Promise<void> | void;
+type QueueHandler<Body = unknown> = (context: QueueRunContext, batch: QueueMessageBatch<Body>) => Promise<void> | void;
 /** Push-consumer batch/retry tuning, mirrored onto the wrangler `queues.consumers[]` entry. */
 interface QueueConsumerTuning {
   /** Name of the dead-letter queue messages land in after `maxRetries`. */
@@ -128,7 +139,9 @@ interface QueueConsumerTuning {
   maxBatchSize?: number;
   /** Max seconds to wait before delivering a partial batch (0–60, default 5). */
   maxBatchTimeout?: number;
-  /** Max delivery attempts before a message is dropped / dead-lettered (default 3). */
+  /** Max concurrent consumer invocations (1–250). Unset lets Cloudflare autoscale. Not emulated by Miniflare in dev. */
+  maxConcurrency?: number;
+  /** Retries **after** the initial delivery, before a message is dropped / dead-lettered. Default 3, so up to 4 deliveries in total. */
   maxRetries?: number;
   /** Delay in seconds before a failed batch is retried. */
   retryDelay?: number;
@@ -152,29 +165,92 @@ interface QueueConfig<Body = unknown> extends QueueConsumerTuning {
 interface QueueDefinition<Body = unknown> extends QueueConfig<Body> {
   /**
    * Phantom carrier for the message body type, so codegen can type the
-   * generated `ctx.queues.&lt;name>` producer as `QueueProducer&lt;Body>` from
-   * `typeof &lt;export>`. Never assigned at runtime (type-only).
+   * generated `ctx.queues.<name>` producer as `QueueProducer<Body>` from
+   * `typeof <export>`. Never assigned at runtime (type-only).
    */
   readonly __lunoraBody?: Body;
   /** Runtime brand identifying a `defineQueue` result. */
   isLunoraQueue: true;
 }
+/**
+ * The typed publisher bound to `ctx.topics.<name>`. A publish is one send to
+ * **each** subscription's queue, in parallel, so it is not atomic: when one send
+ * fails the call rejects, and a retry re-delivers to the subscriptions whose send
+ * already succeeded. Delivery is at-least-once per subscription — make handlers
+ * idempotent. A topic with no subscriptions publishes to nobody.
+ */
+interface TopicPublisher<Payload = unknown> {
+  /** Publish one message to every subscription. */
+  publish: (payload: Payload, options?: QueueSendOptions) => Promise<void>;
+  /** Publish a batch (at most 100) to every subscription in one send per subscription. */
+  publishBatch: (messages: Iterable<MessageSendRequestLike<Payload>>, options?: QueueSendBatchOptions) => Promise<void>;
+}
+/** `ctx.topics` — declared topic export names → typed publishers, keyed like {@link Queues}. */
+type Topics<Name extends string = string> = Readonly<Record<Name, TopicPublisher>>;
+/** The branded result of `defineTopic`, discovered by codegen. Carries no deploy config of its own. */
+interface TopicDefinition<Payload = unknown> {
+  /**
+   * Phantom carrier for the payload type, so codegen can type `ctx.topics.<name>`.
+   * Named like {@link QueueDefinition}'s so one emitted helper reads both. Never
+   * assigned at runtime.
+   */
+  readonly __lunoraBody?: Payload;
+  /** Runtime brand identifying a `defineTopic` result. */
+  isLunoraTopic: true;
+}
+/** The config passed to `defineSubscription`: a push consumer's handler plus its own retry/DLQ tuning. */
+interface SubscriptionConfig<Payload = unknown> extends QueueConsumerTuning {
+  handler: QueueHandler<Payload>;
+  /**
+   * Stable wrangler queue name for this subscription. Defaults to the
+   * kebab-cased export name, exactly like a `defineQueue` export.
+   */
+  name?: string;
+}
+/**
+ * The branded result of `defineSubscription`: a push {@link QueueDefinition}
+ * (so dispatch, retries, the DLQ, wrangler reconcile and the studio treat it as
+ * the queue it is) tagged with the topic it consumes.
+ */
+interface SubscriptionDefinition<Payload = unknown> extends QueueDefinition<Payload> {
+  handler: QueueHandler<Payload>;
+  mode: "push";
+  /** The topic this subscription consumes. */
+  topic: TopicDefinition<Payload>;
+}
+/** Wiring info for one declared topic, emitted by codegen into the generated shard. */
+interface TopicBindingSpec<Name extends string = string> {
+  /** The `lunora/queues.ts` topic export name, e.g. `signups`. */
+  exportName: Name;
+  /** One entry per subscription: its export name and its `Queue` producer binding. */
+  subscriptions: ReadonlyArray<{
+    binding: string;
+    exportName: string;
+  }>;
+}
 /** Wiring info for one declared queue, emitted by codegen into the generated shard/handler. */
-interface QueueBindingSpec {
+interface QueueBindingSpec<Name extends string = string> {
   /** The Cloudflare `Queue` producer binding name, e.g. `QUEUE_EMAIL`. */
   binding: string;
   /** The `lunora/queues.ts` export name, e.g. `emailQueue`. */
-  exportName: string;
+  exportName: Name;
   /** The stable wrangler queue name, e.g. `email-queue`. */
   name: string;
 }
 /** One declared queue, keyed for batch routing by its stable wrangler name. */
 interface QueueRegistryEntry {
+  /**
+   * The queue's own producer binding on `env` (`QUEUE_*`). A message whose
+   * dispatch is declined on its last delivery is re-enqueued through it (see
+   * {@link resolveDeclinedBatch}); without it that message is dead-lettered or
+   * dropped, and logged. Codegen always emits it.
+   */
+  binding?: string;
   /**
    * The `defineQueue` result (carries the push handler). The body type is
    * erased to `any` here because the registry is heterogeneous — different
    * queues carry different message bodies, and the handler param is
-   * contravariant, so a precise `QueueDefinition&lt;Body>` would not be assignable
+   * contravariant, so a precise `QueueDefinition<Body>` would not be assignable
    * to a shared `unknown`-bodied slot. Runtime dispatch passes the delivered
    * batch straight through, so the erasure is type-only.
    */
@@ -197,7 +273,28 @@ interface CapturedQueueMessage {
   attempts: number;
   /** The message body (JSON-encoded + capped by the catcher). */
   body: unknown;
-  /** `true` when this failed delivery was the message's last (its retries are exhausted — the broker dead-letters it). */
+  /**
+   * `true` when this failed delivery was the message's last (its retries are
+   * exhausted) AND the queue declares a `deadLetterQueue` for it to land in.
+   * Stays `false` for a queue with no DLQ, where the broker drops the
+   * exhausted message instead — `attempts > maxRetries` with
+   * `outcome !== "ack"` is what identifies that case.
+   *
+   * Read from the `defineQueue` DECLARATION, because a consumer has no
+   * runtime API that exposes its deployed `queues.consumers[]` settings. It is
+   * true of the deployed broker only as far as Lunora's binding reconcile (run
+   * by `lunora dev`, `deploy` and `prepare`) keeps the two in step: it writes
+   * every declared tuning field onto the consumer, including onto one that
+   * already exists, and takes a field back out once `defineQueue` drops it
+   * (it records what `defineQueue` declared in `package.json`
+   * `lunora.queueTuning`). The gaps that remain: a field changed by hand to
+   * another value than the declared one is
+   * kept when the declaration drops it, so a hand-set DLQ still reads
+   * `false` here; a `--env` deploy retunes the `env.<name>` consumers but
+   * never writes their `dead_letter_queue`, which that block names itself;
+   * and a bare `wrangler deploy` over a hand-edited consumer can disagree
+   * too. Nothing on this side can see any of it.
+   */
   deadLettered: boolean;
   /** Handler error message when `outcome` is `error`; absent otherwise. */
   error?: string;
@@ -221,22 +318,33 @@ interface CapturedQueueMessage {
 type QueueCaptureSink = (messages: CapturedQueueMessage[]) => Promise<void> | void;
 interface DispatchOptions {
   /**
-   * Optional capture sink. When set, the batch is instrumented and every
-   * message's final disposition is recorded and handed to this sink after the
-   * handler runs. Omitted in production unless queue capture is enabled, so a
-   * consumer pays no instrumentation cost by default.
+   * Optional capture sink. When set, every message's final disposition is
+   * turned into a record and handed to this sink after the handler runs.
+   * Omitted in production unless queue capture is enabled, so a consumer pays
+   * no record-building or sink cost by default. Delivery semantics — including
+   * poison-message isolation — do not depend on it.
    */
   capture?: QueueCaptureSink;
   /** Worker `env`, forwarded to the queue run context. */
   env: Record<string, unknown>;
   /** Injectable fetch for the `ctx.run` dispatcher (tests). */
   fetchImpl?: typeof fetch;
+  /**
+   * W3C `traceparent` of the consumer invocation's own trace, supplied by the
+   * runtime's `queue()` entry. Forwarded on every `ctx.run` dispatch so the
+   * functions a handler calls are CHILDREN of the queue span instead of a set of
+   * unrelated root traces. Absent (a hand-built dispatch, a unit test) keeps the
+   * prior behaviour: the callee mints its own trace.
+   */
+  traceparent?: string;
 }
 /**
  * Look up the handler for `batch.queue` and invoke it with a fresh
  * `QueueRunContext`. Throws a directed error when no push handler is registered
  * for the delivered queue (a misconfiguration — the consumer was declared
- * `pull`, or the queue name drifted from the `defineQueue` export).
+ * `pull`, or the queue name drifted from the `defineQueue` export). The
+ * registry already carries every per-environment name wrangler.jsonc maps to a
+ * declared producer binding (see codegen's `emitQueues`), so the lookup stays exact.
  */
 declare const dispatchQueueBatch: (batch: MessageBatchLike, registry: QueueRegistry, options: DispatchOptions) => Promise<void>;
 /** A Worker `env` projected as a plain record (vars, secrets, and bindings are `unknown`-valued). */
@@ -268,21 +376,21 @@ declare const createQueueCaptureSink: (env: QueueEnv, options?: QueueCaptureOpti
  * Build the `ctx.queues` map for a request: resolve every spec's `env[binding]`
  * into the `exportName → Queue binding` map and wrap it in {@link createQueues}.
  * A spec whose binding is absent from `env` is skipped here — the helpful "no
- * queue named …" error is raised lazily by `ctx.queues.&lt;name>.send(...)` when
+ * queue named …" error is raised lazily by `ctx.queues.<name>.send(...)` when
  * the missing queue is actually used.
  */
-declare const createQueueContext: (env: Record<string, unknown>, specs: ReadonlyArray<QueueBindingSpec>) => Queues;
+declare const createQueueContext: <Name extends string>(env: Record<string, unknown>, specs: ReadonlyArray<QueueBindingSpec<Name>>) => Queues<Name>;
 /**
  * Build the `ctx.queues` map from `lunora/queues.ts` export name → Cloudflare
  * `Queue` binding. Each property is a typed {@link QueueProducer}; accessing an
  * export whose binding is absent throws a directed error naming the declared
  * queues (raised lazily on first use).
  */
-declare const createQueues: (options: LunoraQueuesOptions) => Queues;
+declare const createQueues: <Name extends string>(options: LunoraQueuesOptions<Name>) => Queues<Name>;
 /**
  * The wrangler producer binding name for a queue export: `emailQueue` →
  * `QUEUE_EMAIL_QUEUE`, `email` → `QUEUE_EMAIL`. The `QUEUE_` prefix namespaces
- * these away from `SHARD`/`SESSION`/`SCHEDULER`/`WORKFLOW_*`/`CONTAINER_*` so a
+ * these away from `SHARD`/`SESSION`/`SCHEDULER`/`CONTAINER_*` so a
  * queue export can never collide with the built-in bindings.
  */
 declare const queueBindingName: (exportName: string) => string;
@@ -294,7 +402,7 @@ declare const queueBindingName: (exportName: string) => string;
 declare const queueDefaultName: (exportName: string) => string;
 /**
  * Declare a Cloudflare Queue deployed alongside the app. Pure validation +
- * branding: codegen discovers the export, emits the typed `ctx.queues.&lt;name>`
+ * branding: codegen discovers the export, emits the typed `ctx.queues.<name>`
  * producer and (for push consumers) the worker `queue()` dispatch; the config
  * layer reconciles the wrangler `queues.producers[]` / `queues.consumers[]`
  * entries from the same definition.
@@ -304,10 +412,10 @@ declare const queueDefaultName: (exportName: string) => string;
  * import { defineQueue } from "@lunora/queue";
  * import { api } from "./_generated/api";
  *
- * export const emailQueue = defineQueue&lt;{ to: string }>({
+ * export const emailQueue = defineQueue<{ to: string }>({
  *     handler: async (ctx, batch) => {
  *         for (const message of batch.messages) {
- *             await ctx.run(api.email.send, { to: message.body.to });
+ *             await message.run(api.email.send, { to: message.body.to });
  *             message.ack();
  *         }
  *     },
@@ -316,6 +424,12 @@ declare const queueDefaultName: (exportName: string) => string;
  *
  * Enqueue from a mutation or action: `await ctx.queues.emailQueue.send({ to })`.
  *
+ * `message.run(...)` is `ctx.run(...)` pinned to that message — prefer it inside
+ * the batch loop. A deterministic failure (400/403/404/422) from a pinned call
+ * is attributed to its message: that one is acked and the rest are retried,
+ * instead of one poison message re-delivering (and eventually dead-lettering)
+ * the whole batch.
+ *
  * ⚠️ **Privileged dispatch.** A push handler's `ctx.run(...)` calls back into
  * Lunora functions over the admin-authenticated dispatch endpoint (the same
  * trusted path the scheduler and workflows use), so those calls run with the
@@ -331,7 +445,29 @@ interface RunContextOptions {
   env: Record<string, unknown>;
   exportName: string;
   fetchImpl?: typeof fetch;
+  /** The consumer invocation's `traceparent`, so `ctx.run` joins the queue's trace. */
+  traceparent?: string;
 }
 /** Assemble the {@link QueueRunContext} passed to a `defineQueue` handler. */
 declare const createQueueRunContext: (options: RunContextOptions) => QueueRunContext;
-export { type ArgsOf, type CapturedQueueMessage, type FunctionReference, type LunoraQueuesOptions, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, type QueueBindingLike, type QueueBindingSpec, type QueueCaptureOptions, type QueueCaptureSink, type QueueConfig, type QueueConsumerMode, type QueueConsumerTuning, type QueueContentType, type QueueDefinition, type QueueEnv, type QueueHandler, type DispatchLogger as QueueLogger, type QueueProducer, type QueueRegistry, type QueueRegistryEntry, type QueueRetryOptions, type QueueRunContext, type DispatchRunFunction as QueueRunFunction, type QueueSendBatchOptions, type QueueSendOptions, type Queues, type RunFunctionOptions, createQueueCaptureSink, createQueueContext, createQueueRunContext, createQueues, defineQueue, dispatchQueueBatch, isQueueDefinition, queueBindingName, queueDefaultName, shouldCaptureQueue };
+/**
+ * Declare a topic in `lunora/queues.ts`. The payload type is the only thing a
+ * topic carries; delivery config lives on each subscription.
+ */
+declare const defineTopic: <Payload = unknown>() => TopicDefinition<Payload>;
+/**
+ * Subscribe to a topic. The result is a push queue definition — export it from
+ * `lunora/queues.ts` and it deploys, retries and dead-letters exactly like a
+ * `defineQueue` export of the same name.
+ *
+ * ⚠️ Same trust model as a queue handler: `message.run(...)` dispatches with the
+ * system identity, so validate `message.body` before acting on it.
+ */
+declare const defineSubscription: <Payload>(topic: TopicDefinition<Payload>, config: SubscriptionConfig<Payload>) => SubscriptionDefinition<Payload>;
+/**
+ * Build `ctx.topics` for a request from the Worker `env` and the codegen-emitted
+ * specs. A topic with no subscriptions publishes to nobody; a topic with an
+ * unbound subscription rejects every publish (see {@link unboundPublisher}).
+ */
+declare const createTopicContext: <Name extends string>(env: Record<string, unknown>, specs: ReadonlyArray<TopicBindingSpec<Name>>) => Topics<Name>;
+export { type ArgsOf, type CapturedQueueMessage, type FunctionReference, type LunoraQueuesOptions, type QueueBindingSpec, type QueueCaptureOptions, type QueueCaptureSink, type QueueConfig, type QueueConsumerMode, type QueueConsumerTuning, type QueueDefinition, type QueueEnv, type QueueHandler, type DispatchLogger as QueueLogger, type QueueMessage, type QueueMessageBatch, type QueueProducer, type QueueRegistry, type QueueRegistryEntry, type QueueRunContext, type DispatchRunFunction as QueueRunFunction, type Queues, type RunFunctionOptions, type SubscriptionConfig, type SubscriptionDefinition, type TopicBindingSpec, type TopicDefinition, type TopicPublisher, type Topics, createQueueCaptureSink, createQueueContext, createQueueRunContext, createQueues, createTopicContext, defineQueue, defineSubscription, defineTopic, dispatchQueueBatch, isQueueDefinition, queueBindingName, queueDefaultName, shouldCaptureQueue };

package/dist/index.mjs

@@ -1 +1 @@
-import{createQueueCaptureSink as t,shouldCaptureQueue as r}from"./packem_shared/createQueueCaptureSink-saac8Ywl.mjs";import{createQueueContext as a}from"./packem_shared/createQueueContext-BuXG9VQI.mjs";import{default as i}from"./packem_shared/createQueues-BZBGfWI4.mjs";import{defineQueue as p,isQueueDefinition as m,queueBindingName as x,queueDefaultName as Q}from"./packem_shared/defineQueue-DJYVNfQY.mjs";import{dispatchQueueBatch as d}from"./packem_shared/dispatchQueueBatch-GZMtLZNW.mjs";import{createQueueRunContext as C}from"./packem_shared/createQueueRunContext-B-TpEaZa.mjs";export{t as createQueueCaptureSink,a as createQueueContext,C as createQueueRunContext,i as createQueues,p as defineQueue,d as dispatchQueueBatch,m as isQueueDefinition,x as queueBindingName,Q as queueDefaultName,r as shouldCaptureQueue};
+import{createQueueCaptureSink as t,shouldCaptureQueue as o}from"./packem_shared/createQueueCaptureSink-CSOPftvj.mjs";import{createQueueContext as i}from"./packem_shared/createQueueContext-1r-Qo49i.mjs";import{createQueues as n}from"./packem_shared/createQueues-wa7A7lnf.mjs";import{defineQueue as f,isQueueDefinition as c,queueBindingName as x,queueDefaultName as m}from"./packem_shared/defineQueue-TY4-i3nG.mjs";import{dispatchQueueBatch as d}from"./packem_shared/dispatchQueueBatch-Ch0Yy8TN.mjs";import{c as C}from"./packem_shared/run-context-9CCDiINF.mjs";import{createTopicContext as l,defineSubscription as q,defineTopic as B}from"./packem_shared/createTopicContext-NB6VdRGc.mjs";export{t as createQueueCaptureSink,i as createQueueContext,C as createQueueRunContext,n as createQueues,l as createTopicContext,f as defineQueue,q as defineSubscription,B as defineTopic,d as dispatchQueueBatch,c as isQueueDefinition,x as queueBindingName,m as queueDefaultName,o as shouldCaptureQueue};

package/dist/packem_shared/createQueueCaptureSink-CSOPftvj.mjs

@@ -0,0 +1 @@
+import{LunoraError as E}from"@lunora/errors";const _="__lunora_admin__:recordQueueMessage",N="__root__",f=/^(?:dev(?:elopment)?|local(?:host)?|test)$/iu,p=["CF_ENV","ENVIRONMENT","NODE_ENV","WORKER_ENV"],T=5e3,O=o=>{const t=o.LUNORA_QUEUE_CAPTURE;if(typeof t=="string"){const e=t.toLowerCase();if(e==="1"||e==="true")return!0;if(e==="0"||e==="false")return!1;console.warn(`@lunora/queue: unrecognized LUNORA_QUEUE_CAPTURE value "${t}" — expected "1"/"true" or "0"/"false"; falling back to environment detection.`)}return p.some(e=>{const r=o[e];return typeof r=="string"&&f.test(r)})},h=(o,t={})=>{const e=t.rootShard??N;return async r=>{if(r.length===0)return;const i=o.SHARD,s=typeof o.LUNORA_ADMIN_TOKEN=="string"?o.LUNORA_ADMIN_TOKEN:void 0;if(i===void 0||s===void 0)return;let a=i;if(t.jurisdiction!==void 0){if(typeof i.jurisdiction!="function")throw new TypeError(`@lunora/queue: Durable Object namespace does not support jurisdiction("${t.jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`);a=i.jurisdiction(t.jurisdiction)}const l=a.get(a.idFromName(e)),u=new AbortController,d=setTimeout(()=>{u.abort()},T);try{const n=await l.fetch("https://shard.internal/rpc",{body:JSON.stringify({args:{messages:r},functionPath:_}),headers:{authorization:`Bearer ${s}`,"content-type":"application/json"},method:"POST",signal:u.signal});if(!n.ok){const c=await n.text().catch(()=>"");throw new E("INTERNAL",`@lunora/queue: capture write to the root shard failed (${String(n.status)} ${n.statusText})${c===""?"":`: ${c}`}`)}await n.body?.cancel()}finally{clearTimeout(d)}}};export{h as createQueueCaptureSink,O as shouldCaptureQueue};

package/dist/packem_shared/createQueueContext-1r-Qo49i.mjs

@@ -0,0 +1 @@
+import{resolveQueueBinding as r,createQueues as s}from"./createQueues-wa7A7lnf.mjs";const u=(t,i)=>{const e={};for(const n of i){const o=r(t,n.binding);o&&(e[n.exportName]=o)}return s({bindings:e})};export{u as createQueueContext};

package/dist/packem_shared/createQueueRunContext-Bkl9aN1l.mjs

@@ -0,0 +1 @@
+import{c as o}from"./run-context-9CCDiINF.mjs";export{o as createQueueRunContext};

package/dist/packem_shared/createQueues-wa7A7lnf.mjs

@@ -0,0 +1 @@
+import{LunoraError as a}from"@lunora/errors";import{h as g,R as h}from"./requeue-envelope-CSyxsn47.mjs";const i=100,d=43200,l=(t,n)=>{if(t!==void 0&&t>d)throw new a("VALIDATION_ERROR",`@lunora/queue: ${n} delaySeconds is ${String(t)}, over the Cloudflare Queues ceiling of ${String(d)} (12 hours) — use @lunora/scheduler for longer schedules`)},$=(t,n)=>{if(g(t))throw new a("VALIDATION_ERROR",`@lunora/queue: ${n} body may not contain the reserved key "${h}"`)},f=(t,n,e)=>{l(n?.delaySeconds,e),$(t,e)},E=(t,n,e)=>{l(n?.delaySeconds,e);const s=[...t];if(s.length>i)throw new a("VALIDATION_ERROR",`@lunora/queue: ${e} exceeds ${String(i)} (got ${String(s.length)}) — split across calls`);for(const[r,o]of s.entries())f(o.body,o,`${e} message ${String(r)}`);return s},O=t=>({send:async(n,e)=>{f(n,e,"send"),await t.send(n,e)},sendBatch:async(n,e)=>{await t.sendBatch(E(n,e,"sendBatch"),e)}}),y=(t,n)=>{const e=t[n];return e&&typeof e.send=="function"&&typeof e.sendBatch=="function"?e:void 0},R=(t,n,e)=>{const s=Object.assign(Object.create(null),t),r=Object.keys(s),o=r.length===0?`no ${n}s are declared`:`known ${n}s: ${r.join(", ")}`;return new Proxy(s,{get(u,c){if(typeof c=="string")return Object.hasOwn(u,c)?u[c]:e(()=>Promise.reject(new Error(`@lunora/queue: no ${n} named "${c}" (${o})`)))}})},w=t=>{const n=t.bindings??{},e={};for(const[s,r]of Object.entries(n))e[s]=O(r);return R(e,"queue",s=>({send:s,sendBatch:s}))};export{f as assertSendable,w as createQueues,R as namedLookup,E as prepareBatch,y as resolveQueueBinding};

package/dist/packem_shared/createTopicContext-NB6VdRGc.mjs

@@ -0,0 +1 @@
+import{resolveQueueBinding as c,namedLookup as p,prepareBatch as a,assertSendable as h}from"./createQueues-wa7A7lnf.mjs";const f=()=>({isLunoraTopic:!0}),b=n=>typeof n=="object"&&n!==null&&n.isLunoraTopic===!0,w=(n,e)=>{if(!b(n))throw new TypeError("defineSubscription: the first argument must be a `defineTopic()` result");if(typeof e.handler!="function")throw new TypeError("defineSubscription: `handler` must be a function");if(e.name!==void 0&&(typeof e.name!="string"||e.name.length===0))throw new TypeError("defineSubscription: `name` must be a non-empty string when provided");return{...e,isLunoraQueue:!0,mode:"push",topic:n}},l=n=>({publish:async(e,t)=>{h(e,t,"publish"),await Promise.all(n.map(async r=>r.send(e,t)))},publishBatch:async(e,t)=>{const r=a(e,t,"publishBatch");await Promise.all(n.map(async i=>i.sendBatch(r,t)))}}),d=n=>{const e=()=>Promise.reject(new Error(`@lunora/queue: missing queue binding(s) ${n.join(", ")} — add them to wrangler.jsonc (lunora dev reconciles them); nothing was published`));return{publish:e,publishBatch:e}},y=(n,e)=>{const t={};for(const r of e){const i=[],s=[];for(const o of r.subscriptions){const u=c(n,o.binding);u?i.push(u):s.push(o.binding)}t[r.exportName]=s.length>0?d(s):l(i)}return p(t,"topic",r=>({publish:r,publishBatch:r}))};export{y as createTopicContext,w as defineSubscription,f as defineTopic};

package/dist/packem_shared/{defineQueue-DJYVNfQY.mjs → defineQueue-TY4-i3nG.mjs}

@@ -1 +1 @@
-const n=e=>`QUEUE_${e.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g,"_").toUpperCase()}`,o=e=>e.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g,"-").toLowerCase(),r=e=>{const u=e.mode??"push";if(u!=="push"&&u!=="pull")throw new TypeError(`defineQueue: \`mode\` must be "push" or "pull" (got ${JSON.stringify(e.mode)})`);if(u==="push"&&typeof e.handler!="function")throw new TypeError('defineQueue: `handler` must be a function for a push consumer (omit it only when `mode: "pull"`)');if(e.name!==void 0&&(typeof e.name!="string"||e.name.length===0))throw new TypeError("defineQueue: `name` must be a non-empty string when provided");return{...e,isLunoraQueue:!0,mode:u}},t=e=>typeof e=="object"&&e!==null&&e.isLunoraQueue===!0;export{r as defineQueue,t as isQueueDefinition,n as queueBindingName,o as queueDefaultName};
+const n=e=>`QUEUE_${e.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g,"_").toUpperCase()}`,t=e=>e.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g,"-").toLowerCase(),o=e=>{const u=e.mode??"push";if(u!=="push"&&u!=="pull")throw new TypeError(`defineQueue: \`mode\` must be "push" or "pull" (got ${JSON.stringify(e.mode)})`);if(u==="push"&&typeof e.handler!="function")throw new TypeError('defineQueue: `handler` must be a function for a push consumer (omit it only when `mode: "pull"`)');if(e.name!==void 0&&(typeof e.name!="string"||e.name.length===0))throw new TypeError("defineQueue: `name` must be a non-empty string when provided");return{...e,isLunoraQueue:!0,mode:u}},r=e=>typeof e=="object"&&e!==null&&e.isLunoraQueue===!0;export{o as defineQueue,r as isQueueDefinition,n as queueBindingName,t as queueDefaultName};

package/dist/packem_shared/dispatchQueueBatch-Ch0Yy8TN.mjs

@@ -0,0 +1 @@
+import{c as h,e as x,t as N,Z as q,r as k,Q as R}from"./run-context-9CCDiINF.mjs";import{LunoraError as $,toErrorBody as M}from"@lunora/errors";import{s as A,o as I}from"./requeue-envelope-CSyxsn47.mjs";const b=e=>typeof e.definition.maxRetries=="number"?e.definition.maxRetries:R,O=e=>{if(e instanceof Date)return e.getTime();const t=typeof e=="number"?e:Number(e);return Number.isFinite(t)?t:0},T=async(e,t)=>{const n=await I(t,e.body).catch(()=>{});return n===void 0?{body:e.body,id:e.id,requeued:!1}:{...n,requeued:!0}},g=e=>{const t=e.LUNORA_ADMIN_TOKEN;return typeof t=="string"&&t.length>0?t:void 0},B=(e,t)=>{let n=0;return(o,i,r)=>(n+=1,e(o,i,{...r,dedupId:`${t}#${String(n)}`,messageId:t}))},L=(e,t,n,o)=>{const i=B(o,t.id);return new Proxy(e,{get:(r,s)=>s==="id"?t.id:s==="body"?t.body:s==="ack"?()=>{n.set(r,"ack"),r.ack()}:s==="retry"?f=>{n.set(r,"retry"),r.retry(f)}:s==="run"?i:Reflect.get(r,s,r)})},j=(e,t,n)=>new Proxy(e,{get:(o,i)=>i==="ackAll"?()=>{n("ack"),o.ackAll()}:i==="retryAll"?r=>{n("retry"),o.retryAll(r)}:i==="messages"?t:Reflect.get(o,i,o)}),Q=async(e,t,n)=>{const o=new Map,i=e.messages,r=new Map,s=[];for(const c of i){const u=await T(c,n);r.set(c,u),s.push(L(c,u,o,t))}const l=j(e,s,c=>{for(const u of i)o.has(u)||o.set(u,c)});return{dispositions:o,originals:i,requeued:new Set,views:r,wrappedBatch:l}},m=(e,t)=>e.views.get(t)??{body:t.body,id:t.id,requeued:!1},v=(e,t)=>m(e,t).id,S=e=>{if(e instanceof Error)return e.message;if(typeof e=="string")return e;if(e!==null&&typeof e=="object")try{return JSON.stringify(e)}catch{return"[unserializable thrown value]"}return String(e)},D=(e,t,n,o,i,r)=>{const s=o?S(i):void 0,f=b(t),l=o?"error":"ack",c=typeof t.definition.deadLetterQueue=="string"&&t.definition.deadLetterQueue.length>0;return e.originals.map(u=>{const d=u===r,a=e.dispositions.get(u),p=d?"error":a??l,w=typeof u.attempts=="number"?u.attempts:1,y=m(e,u);return{attempts:w,body:y.body,deadLettered:c&&!d&&!e.requeued.has(u)&&p!=="ack"&&w>f,error:p==="error"?s:void 0,exportName:t.exportName,messageId:y.id,outcome:p,queue:n,timestamp:O(u.timestamp)}})},C=(e,t,n)=>{if(!t||!N(n))return;const o=q(n);if(o===void 0)return;const i=e.originals.find(r=>v(e,r)===o);if(!(i===void 0||e.dispositions.has(i)))return i},P=(e,t)=>{t.ack();for(const n of e.originals)n!==t&&!e.dispositions.has(n)&&(e.dispositions.set(n,"retry"),n.retry())},F=async(e,t,n,o,i)=>{const r=g(i),s=q(t),f=e.originals.find(d=>v(e,d)===s&&!e.dispositions.has(d)),l=`@lunora/queue: queue "${o}" (${n.exportName})`,c=n.binding===void 0?void 0:i[n.binding],u=[];for(const d of e.originals)if(!e.dispositions.has(d)){if(e.dispositions.set(d,"retry"),f!==void 0&&d!==f){d.retry();continue}u.push(d)}await Promise.all(u.map(async d=>{const a=m(e,d),p=typeof c?.send!="function"||a.requeued||r===void 0?void 0:async w=>{await c.send(await A(r,a.id,a.body),{contentType:"json",delaySeconds:w})};await k(d,{maxRetries:b(n),requeue:p,where:l})==="requeued"&&e.requeued.add(d)}))},E=async(e,t,n)=>{const o=Object.hasOwn(t,e.queue)?t[e.queue]:void 0;if(o===void 0){const a=Object.keys(t),p=a.length===0?"no push queues are declared":`known push queues: ${a.join(", ")}`;throw new $("INTERNAL",`@lunora/queue: received a batch for queue "${e.queue}" but no push handler is registered (${p}). Likely causes: the queue is declared \`pull\`, a renamed per-environment queue has no wrangler.jsonc producer with the declared binding, or codegen was not rerun.`)}const{handler:i}=o.definition;if(typeof i!="function")throw new TypeError(`@lunora/queue: queue "${e.queue}" (${o.exportName}) has no push handler — it is declared as a pull consumer`);const r=h({env:n.env,exportName:o.exportName,fetchImpl:n.fetchImpl,...n.traceparent===void 0?{}:{traceparent:n.traceparent}}),s=await Q(e,r.run,g(n.env));let f=!1,l;try{await i(r,s.wrappedBatch)}catch(a){f=!0,l=a}const c=C(s,f,l);if(c!==void 0){P(s,c);const{body:a,status:p}=M(l,{redactedMessage:"internal error"});console.error(`@lunora/queue: dropped message ${v(s,c)} on queue "${e.queue}" (${o.exportName}) — a dispatch it made failed with a deterministic ${String(p)} (${a.code}: ${a.message}), so it was acked, not retried. Its retries are NOT exhausted and it is not dead-lettered — it will never be redelivered.`)}const u=f&&x(l);u&&await F(s,l,o,e.queue,n.env);const d=f&&c===void 0&&!u;if(n.capture!==void 0)try{await n.capture(D(s,o,e.queue,f,l,c))}catch(a){console.warn("@lunora/queue: capture sink failed (delivery unaffected):",a)}if(d)throw l};export{E as dispatchQueueBatch};

package/dist/packem_shared/requeue-envelope-CSyxsn47.mjs

@@ -0,0 +1,4 @@
+import{encodeWire as f,decodeWire as l}from"@lunora/wire";const g="lunora.requeue.v1",u=new TextEncoder,y=async(e,t)=>crypto.subtle.importKey("raw",u.encode(e),{hash:"SHA-256",name:"HMAC"},!1,[t]),d=(e,t,n)=>u.encode(`${g}
+${e}
+${t}
+${n}`),w=e=>[...new Uint8Array(e)].map(t=>t.toString(16).padStart(2,"0")).join(""),b=/^[\da-f]{64}$/u,S=async(e,t,n,s)=>w(await crypto.subtle.sign("HMAC",await y(e,"sign"),d(t,n,s))),h=async(e,t,n,s,o)=>{if(typeof o!="string"||!b.test(o))return!1;const r=Uint8Array.from({length:o.length/2},(E,i)=>Number.parseInt(o.slice(i*2,i*2+2),16));return crypto.subtle.verify("HMAC",await y(e,"verify"),r,d(t,n,s))},a="$lunora.requeued$",p="queue",c=128*1024,m=e=>typeof e=="object"&&e!==null&&Object.hasOwn(e,a),A=async(e,t,n)=>{const s=JSON.stringify(f(n)),o={[a]:{body:s,id:t,mac:await S(e,p,t,s)}},r=new TextEncoder().encode(JSON.stringify(o)).byteLength;if(r>c)throw new RangeError(`the copy would be ${String(r)} bytes, over the ${String(c)}-byte queue message limit`);return o},$=async(e,t)=>{if(e===void 0||!m(t))return;const n=t[a];if(!(typeof n?.id!="string"||typeof n.body!="string")&&await h(e,p,n.id,n.body,n.mac))return{body:l(JSON.parse(n.body)),id:n.id}};export{a as R,m as h,$ as o,A as s};

package/dist/packem_shared/run-context-9CCDiINF.mjs

@@ -0,0 +1 @@
+import{LunoraError as u,isLunoraError as b}from"@lunora/errors";import{decodeWire as D,encodeArgsOrThrow as U}from"@lunora/wire";const q=e=>({debug:(t,...r)=>{console.debug(e,t,...r)},error:(t,...r)=>{console.error(e,t,...r)},info:(t,...r)=>{console.info(e,t,...r)},warn:(t,...r)=>{console.warn(e,t,...r)}}),P=9e5,I="DISPATCH_IN_PROGRESS",j="x-lunora-dispatch-declined",C=(e,t,r)=>{if(t===void 0)return{dispose:()=>{},signal:e};const a=new AbortController,o=setTimeout(()=>{a.abort(r())},t);return{dispose:()=>{clearTimeout(o)},signal:a.signal}},i="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",S=e=>{let t="",r=0;const a=e.length-2;for(;r<a;r+=3){const n=e[r]<<16|e[r+1]<<8|e[r+2];t+=i.charAt(n>>18&63)+i.charAt(n>>12&63)+i.charAt(n>>6&63)+i.charAt(n&63)}const o=e.length-r;if(o===1){const n=e[r]<<16;t+=i.charAt(n>>18&63)+i.charAt(n>>12&63)}else if(o===2){const n=e[r]<<16|e[r+1]<<8;t+=i.charAt(n>>18&63)+i.charAt(n>>12&63)+i.charAt(n>>6&63)}return t};new TextDecoder;const v=new TextEncoder,N="=",J=e=>{for(let t=0;t<e.length;t+=1)if(e.charCodeAt(t)>255)return!1;return!0},k=e=>S(v.encode(JSON.stringify(e))),M=e=>!e.startsWith(N)&&J(e)?e:`${N}${S(v.encode(e))}`,K="/_lunora/scheduler/dispatch",W=3e4,G=e=>{let t=e.length;for(;t>0&&e[t-1]==="/";)t-=1;return e.slice(0,t)},T=Symbol("lunoraDispatchFailure"),R=Symbol("lunoraDispatchDecline"),E=Symbol("lunoraDispatchMessageId"),O=(e,t)=>(t!==void 0&&Object.defineProperty(e,E,{value:t}),e),H=(e,t)=>(Object.defineProperty(e,T,{value:!0}),O(e,t)),ee=e=>b(e)?e[E]:void 0,Q=(e,t,r,a)=>{const{status:o}=t;try{const n=JSON.parse(r)?.error;if(typeof n=="object"&&n!==null&&typeof n.code=="string"){const{code:l,data:g,message:d}=n,h=H(new u(l,typeof d=="string"?d:void 0,{data:g,status:o}),a);return t.headers.get(j)==="1"&&Object.defineProperty(h,R,{value:!0}),h}}catch{}return O(new u("INTERNAL",`${e}: function dispatch failed (${String(o)}): ${r}`,{status:o}),a)},B=new Set([400,403,404,422]),F=new Set([I,"DISPATCH_UNAUTHENTICATED"]),_=e=>b(e)&&e[T]===!0,te=e=>_(e)&&B.has(e.status)&&!F.has(e.code),re=e=>_(e)&&e[R]===!0,$=P/1e3,z=3,ne=async(e,t)=>{const r=t.maxRetries??z,a=typeof e.attempts=="number"&&e.attempts>r;let o="";if(a&&t.requeue!==void 0)try{return await t.requeue($),e.ack(),"requeued"}catch(n){o=` Re-enqueueing a delayed copy failed (${n instanceof Error?n.message:String(n)}).`}return e.retry({delaySeconds:$}),a&&console.error(`${t.where}: message ${e.id} was declined (${I}) on its last delivery (attempt ${String(e.attempts)} of ${String(r+1)}) — its earlier delivery is still running the call.${o} It is retried anyway, but its retries are exhausted, so it will be dead-lettered if the queue has a deadLetterQueue and dropped if not. Raise max_retries so a slow call cannot exhaust it.`),"retried"},X=(e,t,r)=>new u("INTERNAL",`${e}: function dispatch to "${t}" timed out after ${String(r)}ms`,{status:503}),Z=e=>{const{label:t}=e,r=globalThis.fetch,a=e.fetchImpl??(typeof r=="function"?r.bind(globalThis):void 0);return async(o,n,l={})=>{if(typeof a!="function")throw new TypeError(`${t}: no fetch implementation available — pass fetchImpl or run on a platform with global fetch`);const g=()=>e.argsAlreadyEncoded===!0?n??{}:U(t,o.__lunoraRef,n??{}),d=e.env.LUNORA_ORIGIN_URL;if(typeof d!="string"||d.length===0)throw new u("INTERNAL",`${t}: \`LUNORA_ORIGIN_URL\` must be set on the Worker env so a handler can call back into Lunora functions`);const h=e.env.LUNORA_ADMIN_TOKEN;if(typeof h!="string"||h.length===0)throw new u("INTERNAL",`${t}: \`LUNORA_ADMIN_TOKEN\` must be set on the Worker env to authenticate function dispatch`);const L=`${G(d)}${K}`,y={authorization:`Bearer ${h}`,"content-type":"application/json"};e.traceparent!==void 0&&e.traceparent.length>0&&(y.traceparent=e.traceparent),e.identity?.userId!==void 0&&(y["x-lunora-userid"]=M(e.identity.userId)),e.identity?.claims!==void 0&&(y["x-lunora-identity"]=k(e.identity.claims));const m=l.timeoutMs??W,A=C(void 0,m,()=>new DOMException(`dispatch timed out after ${String(m)}ms`,"TimeoutError")),w=c=>{throw c instanceof Error&&c.name==="TimeoutError"?X(t,o.__lunoraRef,m):c};let s;try{try{s=await a(L,{body:JSON.stringify({args:g(),functionPath:o.__lunoraRef,id:l.dedupId,shardKey:l.shardKey}),headers:y,method:"POST",signal:A.signal})}catch(p){return w(p)}if(!s.ok){let p;try{p=await s.text()}catch(x){return w(x)}throw Q(t,s,p,l.messageId)}let c;try{c=await s.text()}catch(p){return w(p)}if(c.length===0)return;let f;try{f=JSON.parse(c)}catch{throw new u("INTERNAL",`${t}: function dispatch returned a non-JSON body (${String(s.status)}): ${c}`,{status:s.status})}if(f===null||typeof f!="object"||Array.isArray(f)||!("result"in f))throw new u("INTERNAL",`${t}: function dispatch returned a JSON body that is not a { result } envelope (${String(s.status)}): ${c}`,{status:s.status});return D(f.result)}finally{A.dispose()}}},oe=e=>({env:e.env,log:q(`[queue:${e.exportName}]`),run:Z({env:e.env,fetchImpl:e.fetchImpl,label:"@lunora/queue",...e.traceparent===void 0?{}:{traceparent:e.traceparent}})});export{z as Q,ee as Z,oe as c,re as e,ne as r,te as t};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/queue",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.110",
   "description": "Cloudflare Queues for Lunora: defineQueue producers + consumers, the ctx.queues surface, and the generated queue() worker handler",
   "keywords": [
     "background-jobs",
@@ -44,7 +44,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.9"
+    "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
+    "@lunora/platform": "1.0.0-alpha.66",
+    "@lunora/wire": "1.0.0-alpha.1"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/createQueueCaptureSink-saac8Ywl.mjs

@@ -1 +0,0 @@
-import{LunoraError as p}from"@lunora/errors";const N="__lunora_admin__:recordQueueMessage",_="__root__",f=/^(?:dev(?:elopment)?|local(?:host)?|test)$/iu,h=["CF_ENV","ENVIRONMENT","NODE_ENV","WORKER_ENV"],E=5e3,y=e=>{const t=e.LUNORA_QUEUE_CAPTURE;return typeof t=="string"?t==="1"||t.toLowerCase()==="true":h.some(n=>{const o=e[n];return typeof o=="string"&&f.test(o)})},g=(e,t={})=>{const n=t.rootShard??_;return async o=>{if(o.length===0)return;const i=e.SHARD,a=typeof e.LUNORA_ADMIN_TOKEN=="string"?e.LUNORA_ADMIN_TOKEN:void 0;if(i===void 0||a===void 0)return;let s=i;if(t.jurisdiction!==void 0){if(typeof i.jurisdiction!="function")throw new TypeError(`@lunora/queue: Durable Object namespace does not support jurisdiction("${t.jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`);s=i.jurisdiction(t.jurisdiction)}const d=s.get(s.idFromName(n)),u=new AbortController,l=setTimeout(()=>{u.abort()},E);try{const r=await d.fetch("https://shard.internal/rpc",{body:JSON.stringify({args:{messages:o},functionPath:N}),headers:{authorization:`Bearer ${a}`,"content-type":"application/json"},method:"POST",signal:u.signal});if(!r.ok){const c=await r.text().catch(()=>"");throw new p("INTERNAL",`@lunora/queue: capture write to the root shard failed (${String(r.status)} ${r.statusText})${c===""?"":`: ${c}`}`)}await r.body?.cancel()}finally{clearTimeout(l)}}};export{g as createQueueCaptureSink,y as shouldCaptureQueue};

package/dist/packem_shared/createQueueContext-BuXG9VQI.mjs

@@ -1 +0,0 @@
-import i from"./createQueues-BZBGfWI4.mjs";const f=(e,c)=>{const t={};for(const o of c){const n=e[o.binding];n&&typeof n.send=="function"&&typeof n.sendBatch=="function"&&(t[o.exportName]=n)}return i({bindings:t})};export{f as createQueueContext};

package/dist/packem_shared/createQueueRunContext-B-TpEaZa.mjs

@@ -1 +0,0 @@
-import{LunoraError as a}from"@lunora/errors";const p=t=>({debug:(e,...n)=>{console.debug(t,e,...n)},error:(e,...n)=>{console.error(t,e,...n)},info:(e,...n)=>{console.info(t,e,...n)},warn:(e,...n)=>{console.warn(t,e,...n)}}),N="/_lunora/scheduler/dispatch",y=t=>{let e=t.length;for(;e>0&&t[e-1]==="/";)e-=1;return t.slice(0,e)},g=(t,e,n)=>{try{const o=JSON.parse(n)?.error;if(typeof o=="object"&&o!==null&&typeof o.code=="string"){const{code:s,data:c,message:i}=o;return new a(s,typeof i=="string"?i:void 0,{data:c,status:e})}}catch{}return new a("INTERNAL",`${t}: function dispatch failed (${String(e)}): ${n}`,{status:e})},w=t=>{const{label:e}=t,n=globalThis.fetch,o=t.fetchImpl??(typeof n=="function"?n.bind(globalThis):void 0);return async(s,c,i={})=>{if(typeof o!="function")throw new TypeError(`${e}: no fetch implementation available — pass fetchImpl or run on a platform with global fetch`);const u=t.env.LUNORA_ORIGIN_URL;if(typeof u!="string"||u.length===0)throw new a("INTERNAL",`${e}: \`LUNORA_ORIGIN_URL\` must be set on the Worker env so a handler can call back into Lunora functions`);const l=t.env.LUNORA_ADMIN_TOKEN;if(typeof l!="string"||l.length===0)throw new a("INTERNAL",`${e}: \`LUNORA_ADMIN_TOKEN\` must be set on the Worker env to authenticate function dispatch`);const d=`${y(u)}${N}`,f={authorization:`Bearer ${l}`,"content-type":"application/json"};t.identity?.userId!==void 0&&(f["x-lunora-userid"]=t.identity.userId),t.identity?.claims!==void 0&&(f["x-lunora-identity"]=JSON.stringify(t.identity.claims));const r=await o(d,{body:JSON.stringify({args:c??{},functionPath:s.__lunoraRef,shardKey:i.shardKey}),headers:f,method:"POST"});if(!r.ok)throw g(e,r.status,await r.text());const h=await r.text();if(h.length!==0)try{return JSON.parse(h)}catch{throw new a("INTERNAL",`${e}: function dispatch returned a non-JSON body (${String(r.status)}): ${h}`,{status:r.status})}}},I=t=>({env:t.env,log:p(`[queue:${t.exportName}]`),run:w({env:t.env,fetchImpl:t.fetchImpl,label:"@lunora/queue"})});export{I as createQueueRunContext};

package/dist/packem_shared/createQueues-BZBGfWI4.mjs

@@ -1 +0,0 @@
-const u=r=>({send:async(s,n)=>{await r.send(s,n)},sendBatch:async(s,n)=>{await r.sendBatch(s,n)}}),d=r=>{const s=r.bindings??{},n=Object.create(null);for(const[t,e]of Object.entries(s))n[t]=u(e);const c=Object.keys(n),a=t=>{const e=c.length===0?"no queues are declared":`known queues: ${c.join(", ")}`,o=()=>Promise.reject(new Error(`@lunora/queue: no queue named "${t}" (${e})`));return{send:o,sendBatch:o}};return new Proxy(n,{get(t,e){if(typeof e=="string")return Object.hasOwn(t,e)?t[e]:a(e)}})};export{d as default};

package/dist/packem_shared/dispatchQueueBatch-GZMtLZNW.mjs

@@ -1 +0,0 @@
-import{LunoraError as m}from"@lunora/errors";import{createQueueRunContext as d}from"./createQueueRunContext-B-TpEaZa.mjs";const l=3,f=e=>{if(e instanceof Date)return e.getTime();const r=typeof e=="number"?e:Number(e);return Number.isFinite(r)?r:0},h=e=>{const r=new Map,o=e.messages,n=o.map(t=>({ack:()=>{r.set(t,"ack"),t.ack()},get attempts(){return t.attempts},get body(){return t.body},get id(){return t.id},retry:a=>{r.set(t,"retry"),t.retry(a)},get timestamp(){return t.timestamp}})),i=t=>{for(const a of o)r.has(a)||r.set(a,t)},c={ackAll:()=>{i("ack"),e.ackAll()},messages:n,queue:e.queue,retryAll:t=>{i("retry"),e.retryAll(t)}};return{dispositions:r,originals:o,wrappedBatch:c}},y=e=>{if(e instanceof Error)return e.message;if(typeof e=="string")return e;if(e!==null&&typeof e=="object")try{return JSON.stringify(e)}catch{return"[unserializable thrown value]"}return String(e)},g=(e,r,o,n,i)=>{const c=n?y(i):void 0,t=typeof r.definition.maxRetries=="number"?r.definition.maxRetries:l;return e.originals.map(a=>{const s=e.dispositions.get(a)??(n?"error":"ack"),u=typeof a.attempts=="number"?a.attempts:1;return{attempts:u,body:a.body,deadLettered:s!=="ack"&&u>t,error:s==="error"?c:void 0,exportName:r.exportName,messageId:a.id,outcome:s,queue:o,timestamp:f(a.timestamp)}})},w=async(e,r,o)=>{const n=Object.hasOwn(r,e.queue)?r[e.queue]:void 0;if(n===void 0){const u=Object.keys(r),p=u.length===0?"no push queues are declared":`known push queues: ${u.join(", ")}`;throw new m("INTERNAL",`@lunora/queue: received a batch for queue "${e.queue}" but no push handler is registered (${p})`)}const{handler:i}=n.definition;if(typeof i!="function")throw new TypeError(`@lunora/queue: queue "${e.queue}" (${n.exportName}) has no push handler — it is declared as a pull consumer`);const c=d({env:o.env,exportName:n.exportName,fetchImpl:o.fetchImpl});if(o.capture===void 0){await i(c,e);return}const t=h(e);let a=!1,s;try{await i(c,t.wrappedBatch)}catch(u){a=!0,s=u}try{const u=g(t,n,e.queue,a,s);await o.capture(u)}catch(u){console.warn("@lunora/queue: capture sink failed (delivery unaffected):",u)}if(a)throw s};export{w as dispatchQueueBatch};