@owlmeans/queue 0.1.18-rc.2 → 0.1.18-rc.20

package/build/types.d.ts

@@ -0,0 +1,248 @@
+import type { BasicConfig, BasicContext, InitializedService } from '@owlmeans/context';
+import type { PubSubResource, Resource, ResourceRecord } from '@owlmeans/resource';
+import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint';
+import type { JobEventType, JobState } from './consts.js';
+/**
+ * Everything the monorepo knows about its queues, declared in the shared backend package so that
+ * producer and consumer read the same list. A process becomes a worker by naming queues in
+ * `listen` — nothing in a declaration decides where it runs.
+ */
+export interface QueueConfig {
+    queues?: QueueDeclaration[];
+    /** The queues THIS process consumes. Absent or empty means producer only. */
+    listen?: string[];
+    /** Which db service carries the queues. Defaults to the queue service's own alias. */
+    db?: string;
+    defaults?: JobOptions;
+    /**
+     * How long a signed job envelope stays acceptable, in seconds. It bounds both the freshness
+     * check and the nonce cache, so a job delayed behind a long backlog is still admitted.
+     */
+    envelopeTtl?: number;
+}
+export interface QueueDeclaration {
+    name: string;
+    /**
+     * The job names this queue accepts. A job the queue does not declare is refused at enqueue
+     * time rather than becoming a job nothing can process.
+     */
+    jobs: string[];
+    worker?: QueueWorkerOptions;
+    defaults?: JobOptions;
+}
+export interface QueueWorkerOptions {
+    concurrency?: number;
+    /**
+     * How long a job may hold its lock without reporting progress. A processor that runs longer
+     * than this between `touch()` calls is treated as stalled and its job is handed to someone else.
+     */
+    lockDuration?: number;
+    stalledInterval?: number;
+    maxStalledCount?: number;
+}
+export interface JobOptions {
+    attempts?: number;
+    backoff?: {
+        type: 'fixed' | 'exponential';
+        delay: number;
+    };
+    delay?: number;
+    priority?: number;
+    /**
+     * A caller-chosen identity for the job. Enqueueing the same id twice while the first is still
+     * around is a no-op, which is what makes an admission step safe to retry.
+     */
+    id?: string;
+    removeOnComplete?: boolean | number;
+    removeOnFail?: boolean | number;
+}
+/**
+ * A job as a RECORD — the same shape the resource contract reads and writes, so inspecting a
+ * queue is `list`/`get`/`count` rather than a broker-specific API.
+ */
+export interface JobRecord<D = unknown, R = unknown> extends ResourceRecord {
+    queue: string;
+    name: string;
+    data: D;
+    state?: JobState;
+    result?: R;
+    error?: string;
+    attempts?: number;
+    progress?: unknown;
+    parentId?: string;
+    createdAt?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    opts?: JobOptions;
+}
+export interface JobEvent<R = unknown> {
+    type: JobEventType;
+    id: string;
+    queue: string;
+    /**
+     * Empty when the job is already gone. A broker's completion event carries only an id, so the
+     * name is read back from the job — and a queue that removes jobs on completion has nothing left
+     * to read. Subscribe for the id and the outcome; do not branch on the name.
+     */
+    name: string;
+    result?: R;
+    error?: string;
+    progress?: unknown;
+}
+/** A node of a job graph: children run first, siblings run together. */
+export interface FlowSpec<D = unknown> {
+    name: string;
+    queue?: string;
+    data: D;
+    opts?: JobOptions;
+    children?: FlowSpec[];
+}
+/**
+ * One queue, addressed as a resource.
+ *
+ * `create` enqueues, `get`/`load`/`list`/`count` inspect, `delete`/`take` cancel. What the base
+ * contract cannot express — waiting for an answer, submitting a graph, releasing the connection —
+ * is added here.
+ *
+ * Three places where the base `Resource` contract reads differently against a broker, because a
+ * job is not a row:
+ * - `create` does NOT throw `RecordExists` for a repeated `opts.id`. Re-enqueueing an id that is
+ *   still around returns the existing job, which is the idempotency that makes an admission step
+ *   safe to retry.
+ * - `WriteOptions.ttl` is refused. A job's lifetime is `removeOnComplete`/`removeOnFail` —
+ *   explicit deletion once it has finished, not expiry while it waits.
+ * - `update`/`save` reach only the job's `data`. Everything else about a job belongs to the
+ *   broker, and an implementation refuses rather than pretending to write it.
+ */
+export interface QueueResource<D = unknown, R = unknown> extends Resource<JobRecord<D, R>>, PubSubResource<JobEvent<R>> {
+    queue: string;
+    /**
+     * Release the connections this queue holds.
+     *
+     * Watching for completions means a blocking connection, and a process that never releases it
+     * does not exit. Nothing else in the resource contract can express that, so it lives here and a
+     * producer calls it on shutdown.
+     */
+    close: () => Promise<void>;
+    /**
+     * Wait for a job's return value.
+     * @throws {QueueTimeout} when the wait elapses — the job itself is left alone.
+     * @throws the processor's own error, rebuilt as its original class.
+     */
+    wait: (id: string, opts?: {
+        timeout?: number;
+    }) => Promise<R>;
+    /** Submit a graph and get its root back. Children complete before their parent starts. */
+    flow: (root: FlowSpec<D>) => Promise<JobRecord<D, R>>;
+    counts: () => Promise<Record<JobState, number>>;
+}
+/**
+ * What a processor is handed. `data` is the job's payload; everything else is the means to stay
+ * alive and to read what the children reported.
+ */
+export interface JobContext<D = unknown> {
+    id: string;
+    name: string;
+    queue: string;
+    attempt: number;
+    data: D;
+    signal: AbortSignal;
+    /**
+     * Renew the lock. A processor that runs a long loop MUST call it as it goes: the broker judges
+     * liveness by the lock, so silence for longer than `lockDuration` is indistinguishable from a
+     * dead worker, and the job is re-run somewhere else while this one is still working on it.
+     */
+    touch: () => Promise<void>;
+    progress: (value: unknown) => Promise<void>;
+    /**
+     * What the children returned, keyed by child job id.
+     *
+     * A broker keys them by its own fully qualified job key; an implementation re-keys to the bare
+     * id, so two children of one parent that live in DIFFERENT queues and happen to share an id
+     * collide here. Give the children of a cross-queue flow distinct ids.
+     */
+    children: <T = unknown>() => Promise<Record<string, T>>;
+    failedChildren: () => Promise<Record<string, string>>;
+}
+export interface JobProcessor<D = unknown, R = unknown> {
+    (job: JobContext<D>): Promise<R>;
+}
+/**
+ * The consuming half. It is registered only in processes that consume: `start()` binds the
+ * queues named in `cfg.listen` and dispatches by job name, to a processor registered here or to
+ * an entrypoint served in this process.
+ */
+export interface QueueWorkerService extends InitializedService {
+    process: <D, R>(queue: string, name: string, processor: JobProcessor<D, R>) => void;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    /** The queues this process actually consumes. Empty in a producer. */
+    listening: () => string[];
+    /**
+     * Bind the application's reactions to job lifecycle events. Registering more than once merges,
+     * so an application composed of several parts can each contribute what it cares about.
+     *
+     * It belongs on the contract rather than on a driver because `onJobDead` is where an
+     * application COMPENSATES — releases the lock the admission step took, marks the record failed —
+     * and that behaviour must not have to be rewritten when the broker changes.
+     */
+    hooks: (hooks: QueueHooks) => void;
+}
+/**
+ * The envelope a queued entrypoint call travels in. It is the request, minus everything that only
+ * means something to HTTP — the transport rebuilds a request from it on the far side.
+ */
+export interface JobEnvelope {
+    alias: string;
+    params?: Record<string, unknown>;
+    body?: unknown;
+    query?: Record<string, unknown>;
+    headers?: Record<string, string | undefined>;
+    /** When the producer enqueued it — freshness is judged here, not at processing time. */
+    enqueuedAt?: string;
+}
+export interface QueueJobMeta {
+    id: string;
+    name: string;
+    queue: string;
+    attempt: number;
+    /** Renew the broker lock for protocol handlers whose work can outlive one lock duration. */
+    touch: () => Promise<void>;
+}
+/** What a processor returns for an entrypoint job, so the caller can rebuild the reply. */
+export interface JobReply<T = unknown> {
+    value?: T;
+    outcome?: string;
+    error?: unknown;
+}
+export interface QueueHooks {
+    wrapHandler?: (job: JobContext, next: () => Promise<unknown>) => Promise<unknown>;
+    onJobResult?: (event: JobEvent) => void | Promise<void>;
+    onJobStalled?: (meta: {
+        id: string;
+        queue: string;
+        name: string;
+    }, phase: 'stalled' | 'failed') => void | Promise<void>;
+    /**
+     * The job is finished for good — retries exhausted, or it was dropped. This is where an
+     * application compensates: release the lock the admission step took, mark the record failed.
+     */
+    onJobDead?: (job: JobRecord, reason: string) => void | Promise<void>;
+}
+export interface QueueDriver {
+    resource: <D, R>(queue: string) => QueueResource<D, R>;
+    worker: () => QueueWorkerService;
+}
+export interface Config extends BasicConfig {
+    queue?: QueueConfig;
+}
+export interface Context<C extends Config = Config> extends BasicContext<C> {
+}
+export interface QueueAppend {
+    jobs: <D = unknown, R = unknown>(queue?: string) => QueueResource<D, R>;
+}
+export interface QueueTransportRequest extends AbstractRequest {
+}
+export interface QueueTransportResponse extends AbstractResponse<unknown> {
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/worker.d.ts

@@ -0,0 +1,27 @@
+import type { Middleware } from '@owlmeans/context';
+import type { CommonEntrypoint } from '@owlmeans/entrypoint';
+import type { Config, Context, JobEnvelope, JobProcessor } from './types.js';
+/**
+ * Every queued entrypoint this process both SERVES and LISTENS to, grouped by queue.
+ *
+ * Both halves are required and they answer different questions. Serving is about code — the alias
+ * was bound here, so a handler exists. Listening is about deployment — this process was
+ * configured to consume that queue. A worker that bound queues by what it can serve would make
+ * every deployment of the same binary a worker for everything it happens to import.
+ */
+export declare const servedJobs: <C extends Config, T extends Context<C>>(context: T) => Map<string, CommonEntrypoint[]>;
+/**
+ * A processor that runs a queued entrypoint call. The driver dispatches by job name, and an
+ * entrypoint job's name IS its alias — which is what lets one worker carry both entrypoint jobs
+ * and the internal steps an application registers with `process()`.
+ */
+export declare const entrypointProcessor: <C extends Config, T extends Context<C>>(context: T) => JobProcessor<JobEnvelope, unknown>;
+/**
+ * Start the worker once the context is ready.
+ *
+ * Ready stage, not Loading: processors are registered while the application wires itself up, and
+ * binding the queues before that finished would take jobs this process cannot yet run. A process
+ * that listens to nothing registers no worker at all, so a producer pays nothing for this.
+ */
+export declare const queueWorkerMiddleware: (alias?: string) => Middleware;
+//# sourceMappingURL=worker.d.ts.map

package/build/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAc,WAAW,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAA;AAI5G;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WACtD,CAAC,KACT,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAoBhC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WAC/D,CAAC,KACT,YAAY,CAAC,WAAW,EAAE,OAAO,CACmC,CAAA;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,WAAW,MAAM,KAAmB,UAcpE,CAAA"}

package/build/worker.js

@@ -0,0 +1,58 @@
+import { MiddlewareStage, MiddlewareType, AppType } from '@owlmeans/context';
+import { RouteProtocols } from '@owlmeans/route';
+import { handleJob } from './bridge.js';
+import { DEFAULT_ALIAS } from './consts.js';
+/**
+ * Every queued entrypoint this process both SERVES and LISTENS to, grouped by queue.
+ *
+ * Both halves are required and they answer different questions. Serving is about code — the alias
+ * was bound here, so a handler exists. Listening is about deployment — this process was
+ * configured to consume that queue. A worker that bound queues by what it can serve would make
+ * every deployment of the same binary a worker for everything it happens to import.
+ */
+export const servedJobs = (context) => {
+    const listen = context.cfg.queue?.listen ?? [];
+    const served = new Map();
+    context.entrypoints().forEach(entrypoint => {
+        const route = entrypoint.route.route;
+        if (route.type !== AppType.Backend || route.protocol !== RouteProtocols.QUEUE) {
+            return;
+        }
+        if (route.service != null && route.service !== context.cfg.service) {
+            return;
+        }
+        if (entrypoint.handle == null || route.queue == null || !listen.includes(route.queue)) {
+            return;
+        }
+        served.set(route.queue, [...(served.get(route.queue) ?? []), entrypoint]);
+    });
+    return served;
+};
+/**
+ * A processor that runs a queued entrypoint call. The driver dispatches by job name, and an
+ * entrypoint job's name IS its alias — which is what lets one worker carry both entrypoint jobs
+ * and the internal steps an application registers with `process()`.
+ */
+export const entrypointProcessor = (context) => async (job) => await handleJob(context, job);
+/**
+ * Start the worker once the context is ready.
+ *
+ * Ready stage, not Loading: processors are registered while the application wires itself up, and
+ * binding the queues before that finished would take jobs this process cannot yet run. A process
+ * that listens to nothing registers no worker at all, so a producer pays nothing for this.
+ */
+export const queueWorkerMiddleware = (alias = DEFAULT_ALIAS) => ({
+    type: MiddlewareType.Context,
+    stage: MiddlewareStage.Ready,
+    apply: async (context) => {
+        const ctx = context;
+        if ((ctx.cfg.queue?.listen ?? []).length === 0) {
+            return;
+        }
+        if (!ctx.hasService(alias)) {
+            return;
+        }
+        await ctx.service(alias).start();
+    }
+});
+//# sourceMappingURL=worker.js.map

package/build/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAE5E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,OAAU,EACuB,EAAE;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAA;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAA;IAEpD,OAAO,CAAC,WAAW,EAAoB,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE;QAC3D,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAA;QACpC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC,QAAQ,KAAK,cAAc,CAAC,KAAK,EAAE,CAAC;YAC9E,OAAM;QACR,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACnE,OAAM;QACR,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACtF,OAAM;QACR,CAAC;QAED,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC,CAAA;IAC3E,CAAC,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,OAAU,EAC0B,EAAE,CACtC,KAAK,EAAE,GAA4B,EAAE,EAAE,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;AAEvE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAK,GAAW,aAAa,EAAc,EAAE,CAAC,CAAC;IACnF,IAAI,EAAE,cAAc,CAAC,OAAO;IAC5B,KAAK,EAAE,eAAe,CAAC,KAAK;IAC5B,KAAK,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;QACrB,MAAM,GAAG,GAAG,OAAqC,CAAA;QACjD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/C,OAAM;QACR,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAM;QACR,CAAC;QAED,MAAM,GAAG,CAAC,OAAO,CAAqB,KAAK,CAAC,CAAC,KAAK,EAAE,CAAA;IACtD,CAAC;CACF,CAAC,CAAA"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/queue",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.20",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 234 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -28,5 +29,14 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@owlmeans/auth": "^0.1.18-rc.20",
+    "@owlmeans/auth-common": "^0.1.18-rc.24",
+    "@owlmeans/context": "^0.1.18-rc.19",
+    "@owlmeans/entrypoint": "^0.1.18-rc.22",
+    "@owlmeans/error": "^0.1.18-rc.19",
+    "@owlmeans/resource": "^0.1.18-rc.20",
+    "@owlmeans/route": "^0.1.18-rc.20"
   }
 }

package/src/bridge.ts

@@ -0,0 +1,126 @@
+import type { AbstractRequest, CommonEntrypoint, GuardService } from '@owlmeans/entrypoint'
+import type { BasicContext } from '@owlmeans/context'
+import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint'
+import type { Auth } from '@owlmeans/auth'
+import { AuthorizationError } from '@owlmeans/auth'
+import { attachEntity } from '@owlmeans/auth-common'
+import { ResilientError } from '@owlmeans/error'
+import type { Config, Context, JobContext, JobEnvelope, JobReply, QueueJobMeta } from './types.js'
+import { EnvelopeExpired, JobNotServed } from './errors.js'
+
+/**
+ * Rebuild the request the producer described. A queued call is still a call: the same guards, the
+ * same filter, the same handler run against it — only the wire is different.
+ */
+export const requestOf = (
+  envelope: JobEnvelope, path: string, context?: BasicContext<any>, job?: QueueJobMeta,
+): AbstractRequest => ({
+  alias: envelope.alias,
+  params: (envelope.params ?? {}) as AbstractRequest['params'],
+  body: envelope.body as AbstractRequest['body'],
+  headers: (envelope.headers ?? {}) as AbstractRequest['headers'],
+  query: (envelope.query ?? {}) as AbstractRequest['query'],
+  path,
+  // Handlers reach their context through `original._ctx`, which the HTTP boundary sets on the raw
+  // Fastify request. There is no raw request here, so the shape is supplied deliberately — a
+  // handler must not have to know which transport delivered it.
+  original: context != null || job != null ? { _ctx: context, _job: job } : undefined,
+})
+
+/** Read broker identity only where an entrypoint truly needs to bind work to an admission claim. */
+export const queueJobOf = (request: unknown): QueueJobMeta | null => {
+  if (request == null || typeof request !== 'object' || !('original' in request)) return null
+  const original = (request as { original?: unknown }).original
+  if (original == null || typeof original !== 'object' || !('_job' in original)) return null
+  return (original as { _job?: QueueJobMeta })._job ?? null
+}
+
+/**
+ * Freshness is judged from when the job was ENQUEUED, not from now.
+ *
+ * A signed envelope proves who produced it, and a replay window keeps a captured one from being
+ * useful forever. But a job can legitimately sit behind a long backlog, and judging it on pickup
+ * would reject exactly the work that a busy queue delayed — so the producer's timestamp is what
+ * the window applies to.
+ *
+ * @throws {EnvelopeExpired}
+ */
+export const assertFresh = (envelope: JobEnvelope, ttl?: number): void => {
+  if (ttl == null || envelope.enqueuedAt == null) {
+    return
+  }
+  const age = (Date.now() - new Date(envelope.enqueuedAt).getTime()) / 1000
+  if (age > ttl) {
+    throw new EnvelopeExpired(`${envelope.alias}: ${Math.round(age)}s > ${ttl}s`)
+  }
+}
+
+/**
+ * Run one queued entrypoint call and describe the outcome.
+ *
+ * It never throws for a DOMAIN failure — the error is marshalled into the returned reply so the
+ * producer can rebuild it as its own class, and so the broker does not count a legitimate refusal
+ * as a job to retry. Infrastructure failures are left to propagate: those are what retries are for.
+ */
+export const handleJob = async <C extends Config, T extends Context<C>>(
+  context: T, job: JobContext<JobEnvelope>
+): Promise<JobReply> => {
+  const envelope = job.data
+
+  try {
+    assertFresh(envelope, context.cfg.queue?.envelopeTtl)
+
+    const entrypoint = context.entrypoint<CommonEntrypoint>(envelope.alias)
+    if (entrypoint.handle == null) {
+      throw new JobNotServed(envelope.alias)
+    }
+
+    const request = requestOf(envelope, entrypoint.path(), context, {
+      id: job.id, name: job.name, queue: job.queue, attempt: job.attempt, touch: job.touch,
+    })
+    const response = provideResponse<unknown>()
+
+    const guards = entrypoint.getGuards()
+    if (guards.length > 0) {
+      let matched: GuardService | undefined
+      for (const alias of guards) {
+        const guard: GuardService = context.service(alias)
+        if (await guard.match(request, response)) {
+          matched = guard
+          break
+        }
+      }
+      if (matched == null) {
+        throw new AuthorizationError(`queue:${envelope.alias}`)
+      }
+
+      const auth = provideResponse<Auth>()
+      if (!await matched.handle<boolean>(request, auth)) {
+        throw new AuthorizationError(`queue:${envelope.alias}:${matched.alias}`)
+      }
+      request.auth = auth.value
+
+      const entity = await attachEntity(context, request)
+      if (entity != null) {
+        request.entity = entity
+      }
+    }
+
+    await entrypoint.handle(request, response)
+
+    if (response.error != null) {
+      return { error: ResilientError.marshal(response.error).message }
+    }
+
+    return { value: response.value, outcome: response.outcome ?? EntrypointOutcome.Ok }
+  } catch (e) {
+    // A refusal the caller must see as its own class — `ContentRefused`, `AgentLocked` — travels
+    // in the reply. Only a broker- or connection-level fault should ever reach the retry logic:
+    // retrying a refusal just spends the work again to be refused identically.
+    if (e instanceof ResilientError) {
+      return { error: ResilientError.marshal(e).message }
+    }
+
+    throw e
+  }
+}

package/src/config.ts

@@ -0,0 +1,56 @@
+import type { Config, JobOptions, QueueDeclaration, QueueWorkerOptions } from './types.js'
+import { UnknownQueue } from './errors.js'
+
+/**
+ * Add a queue to the shared configuration. Every process in the monorepo loads the same
+ * declarations — a producer needs them to know a queue exists and what it accepts, a worker needs
+ * them to bind. Declaring twice replaces, so a helper that runs per app is safe to call.
+ */
+export const declareQueue = <C extends Config>(
+  cfg: C, name: string, jobs: string[], opts?: { worker?: QueueWorkerOptions, defaults?: JobOptions }
+): C => {
+  const queue: QueueDeclaration = { name, jobs, ...opts }
+  const queues = cfg.queue?.queues ?? []
+  const existing = queues.findIndex(declared => declared.name === name)
+
+  if (existing < 0) {
+    queues.push(queue)
+  } else {
+    queues[existing] = queue
+  }
+
+  cfg.queue = { ...cfg.queue, queues }
+
+  return cfg
+}
+
+/**
+ * Name the queues this process consumes. It is what turns an otherwise identical binary into a
+ * worker, which is why it lives in the process's own config and never in a declaration.
+ */
+export const listenQueues = <C extends Config>(cfg: C, ...names: string[]): C => {
+  const listen = new Set([...(cfg.queue?.listen ?? []), ...names])
+
+  cfg.queue = { ...cfg.queue, listen: [...listen] }
+
+  return cfg
+}
+
+/**
+ * @throws {UnknownQueue}
+ */
+export const queueOf = <C extends Config>(cfg: C, name: string): QueueDeclaration => {
+  const queue = cfg.queue?.queues?.find(declared => declared.name === name)
+
+  if (queue == null) {
+    throw new UnknownQueue(name)
+  }
+
+  return queue
+}
+
+export const queueOfJob = <C extends Config>(cfg: C, job: string): QueueDeclaration | undefined =>
+  cfg.queue?.queues?.find(declared => declared.jobs.includes(job))
+
+export const isListening = <C extends Config>(cfg: C, name: string): boolean =>
+  cfg.queue?.listen?.includes(name) === true

package/src/consts.ts

@@ -0,0 +1,39 @@
+
+export const DEFAULT_ALIAS = 'queue'
+
+/**
+ * The state a job is in, as the broker reports it. `Waiting` covers both a job queued normally
+ * and one held by an unfinished parent — the difference matters to the broker, never to a caller
+ * asking whether an answer has arrived.
+ */
+export enum JobState {
+  Waiting = 'waiting',
+  Delayed = 'delayed',
+  Active = 'active',
+  Completed = 'completed',
+  Failed = 'failed',
+  Unknown = 'unknown',
+}
+
+/** A job has reached a state it will not leave on its own. */
+export const isSettled = (state?: JobState): boolean =>
+  state === JobState.Completed || state === JobState.Failed
+
+export enum JobEventType {
+  Completed = 'completed',
+  Failed = 'failed',
+  Progress = 'progress',
+}
+
+/**
+ * How long a caller waits for a reply when neither the route nor the request says. Long enough
+ * for work that talks to a model, short enough that a lost job surfaces as an error rather than a
+ * hung request.
+ */
+export const DEFAULT_JOB_TIMEOUT = 60_000
+
+/**
+ * Retries default to one attempt: the jobs here are mostly LLM work, and a blind retry re-spends
+ * the tokens that just failed. A queue whose jobs are cheap and idempotent raises it per queue.
+ */
+export const DEFAULT_ATTEMPTS = 1