@owlmeans/queue 0.1.18-rc.6 → 0.1.18-rc.8

package/README.md

@@ -1,10 +1,17 @@
 # @owlmeans/queue
 
-Reserved namespace for queue management. Currently a stub with no exports.
+Job queues as resources, and the route protocol that lets a queued call look like any other call.
 
 ## Overview
 
-This package is a placeholder for future queue/task processing functionality within the OwlMeans framework.
+This package is contracts only — it carries no broker code. A driver implements them
+(`@owlmeans/redis-queue` does, over BullMQ); depend on this package from a shared contract
+package, and on the driver only where the application wires itself up.
+
+The point of it: a route that names `RouteProtocols.QUEUE` is taken by the queue transport, so the
+caller writes `ep.call(...)` exactly as it would for HTTP. Moving a service-to-service call onto
+the broker is a change to one declaration rather than to every call site, and a call that used to
+die with the process survives a restart.
 
 ## Installation
 
@@ -12,9 +19,110 @@ This package is a placeholder for future queue/task processing functionality wit
 bun add @owlmeans/queue
 ```
 
+## Declaring queues
+
+Queues and the job names they accept belong in the shared backend package, so producer and
+consumer read the same list:
+
+```typescript
+import { declareQueue, listenQueues } from '@owlmeans/queue'
+
+declareQueue(cfg, AGENT_WORK, ['agent:story:develop', 'agent:story:code'], {
+  worker: { concurrency: 3, lockDuration: 60_000 }
+})
+```
+
+Which queues a given process consumes is a separate, process-local statement:
+
+```typescript
+listenQueues(cfg, AGENT_WORK, AGENT_OPS)   // absent ⇒ this process only produces
+```
+
+A declaration is an address; `listen` is a deployment fact. Keeping them apart is what lets the
+same binary run as a producer in one deployment and a worker in another.
+
+## Declaring a queued entrypoint
+
+```typescript
+import { job } from '@owlmeans/route'
+
+entrypoint(
+  route(agent.story.develop, '/:id/develop',
+    job({ parent: agent.story.base, service: AGENT, queue: AGENT_WORK, timeout: 30_000 })),
+  filter(params(StoryParamsSchema))
+)
+```
+
+It is served with `elevate(...)` and called with `call()` like any backend entrypoint. Add
+`reply: false` to return as soon as the job is accepted — the call resolves `Accepted` with
+`{ id, queue }`, which is what a long pipeline wants.
+
+## Jobs are records
+
+```typescript
+const jobs = ctx.jobs<DevelopInput, DevelopResult>(AGENT_WORK)
+
+const queued = await jobs.create({ queue: AGENT_WORK, name: 'agent:story:code', data: input })
+const result = await jobs.wait(queued.id, { timeout: 120_000 })
+
+const failed = await jobs.list({ state: JobState.Failed })
+await jobs.take(queued.id)          // cancel and return
+```
+
+`QueueResource<D, R>` is a `Resource<JobRecord<D, R>>` composed with `PubSubResource<JobEvent<R>>`,
+so criteria, sorting and paging behave as they do for every other backend. Only what the base
+contract cannot express is added: `wait`, `flow` and `counts`.
+
+Deriving `JobOptions.id` from what the job is about (`develop:<storyId>`) makes a duplicate
+enqueue a no-op, which is what makes an admission step safe to retry.
+
+## Processors
+
+```typescript
+worker.process(AGENT_WORK, 'agent:story:code', async job => {
+  for (const screen of screens) {
+    await job.touch()
+    await develop(screen)
+  }
+  return { ok: true }
+})
+```
+
+`touch()` is not optional in a long loop. The broker judges liveness by the lock, so going quiet
+for longer than `lockDuration` is indistinguishable from a dead worker and the job is re-run
+elsewhere while this one is still going.
+
+A child job reports a domain failure by RETURNING `{ ok: false, error }`. Throwing means
+"infrastructure broke, retry me". Parents read `children()` and decide — children never fail
+their parent directly.
+
+Retries default to a single attempt: this work mostly talks to a model, and a blind retry
+re-spends the tokens that just failed.
+
+## Job graphs
+
+```typescript
+await jobs.flow({
+  name: 'story:finalize', data: ref, children: [
+    { name: 'story:gate', data: ref, children: [{ name: 'story:code', data: ref }] }
+  ]
+})
+```
+
+Nesting is sequence, siblings are parallel, and a parent reading `children()` is the join.
+
+## Errors
+
+A refusal the caller must recognise travels in the reply and is rebuilt on the producing side as
+its own class, so `instanceof` keeps working across the broker. `QueueTimeout` means the WAIT
+ended, not the job — read the job back to learn what became of it.
+
 ## Related Packages
 
-- [`@owlmeans/redis-resource`](../redis-resource) — Redis Streams provide queue-like semantics today
+- [`@owlmeans/redis-queue`](../redis-queue) — the BullMQ driver, and where queue integration tests live
+- [`@owlmeans/route`](../route) — `RouteProtocols.QUEUE` and the `job()` builder
+- [`@owlmeans/entrypoint`](../entrypoint) — declarations and the transport seam
+- [`@owlmeans/resource`](../resource) — the `Resource` contract jobs are read through
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/queue",
-  "version": "0.1.18-rc.6",
-  "generatedAt": "2026-08-18T14:48:00.554Z",
+  "version": "0.1.18-rc.8",
+  "generatedAt": "2026-09-01T17:39:40.768Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/queue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: queue
-description: How to use @owlmeans/queue — abstract job-queue interface (currently a stub) to be implemented by transport-specific queue services. Auto-invoked when importing queue types.
+description: How to use @owlmeans/queue — job queues as resources, the QUEUE route protocol that makes a queued call indistinguishable from an HTTP one, declaring queues and job names, the producer/consumer split, job graphs, and the rules a processor must follow. Auto-invoked when importing queue types or declaring a job route.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,24 +8,137 @@ user-invocable: false
 # @owlmeans/queue
 
 **Layer:** Infra
-**Install:** `"@owlmeans/queue": "^0.1.18-rc.6"` in `dependencies`
+**Install:** `"@owlmeans/queue": "^0.1.18-rc.8"` in `dependencies`
 
-## Key Exports
+Contracts only. It carries no broker code — a driver package (`@owlmeans/redis-queue`) implements
+them. Depend on this one from a shared contract package; depend on the driver only where the
+application wires itself up.
 
-This package is currently a stub that defines the queue interface. Concrete implementations (Redis BullMQ, RabbitMQ, etc.) will register a service that satisfies this interface.
+## The one idea
 
-| Export | Description |
-|--------|-------------|
-| Queue types (placeholder) | Abstract queue interface |
+A queued call is an ordinary entrypoint call. The route names `RouteProtocols.QUEUE`, the
+transport registered under that protocol takes it, and the caller writes `ep.call(...)` exactly as
+for HTTP. Nothing at a call site says "queue".
+
+That is what makes it worth having: moving a service-to-service call onto the broker is a change
+to a declaration, not to the ~100 places that call it, and a call that used to die with the
+process now survives a restart.
+
+## Declaring
+
+Queues and the jobs they accept live in the SHARED backend package, so producers and consumers
+read one list:
+
+```typescript
+declareQueue(cfg, AGENT_WORK, ['agent:story:develop', 'agent:story:code'], {
+  worker: { concurrency: 3, lockDuration: 60_000 }
+})
+```
+
+Which queues a process CONSUMES is separate, and lives in that process's own config:
+
+```typescript
+listenQueues(cfg, AGENT_WORK, AGENT_OPS)   // absent ⇒ producer only
+```
+
+Keep them apart. A declaration is an address; `listen` is a deployment fact. If a worker bound
+whatever it could serve, every deployment of the same binary would consume everything it imports.
+
+A queued entrypoint is declared like any other, with `job()` in place of `backend()`:
+
+```typescript
+entrypoint(
+  route(agent.story.develop, '/:id/develop',
+    job({ parent: agent.story.base, service: AGENT, queue: AGENT_WORK, timeout: 30_000 })),
+  filter(params(StoryParamsSchema))
+)
+```
+
+`reply: false` makes it fire-and-forget: the call resolves `Accepted` with `{ id, queue }` as soon
+as the job is taken, which is what a long pipeline wants. The default is to wait for the value.
 
-## Usage
+## Jobs are records
+
+`ctx.jobs<D, R>(queue)` returns a `QueueResource<D, R>` — a `Resource<JobRecord<D, R>>` plus
+pub/sub. So inspecting a queue is the resource contract you already know: `create` enqueues,
+`get`/`load`/`list`/`count` inspect, `delete`/`take` cancel, `purge` bulk-cancels. Only what the
+base contract cannot express is added: `wait(id, { timeout })`, `flow(root)`, `counts()`.
+
+Give `JobOptions.id` a value derived from what the job is ABOUT (`develop:<storyId>`) and a
+duplicate enqueue becomes a no-op. That is what makes an admission step safe to retry.
+
+## Writing a processor
 
 ```typescript
-// Reserve the alias for your queue implementation
-import type { Queue } from '@owlmeans/queue'
-const queue = ctx.service<Queue>('queue')
+worker.process(AGENT_WORK, 'agent:story:code', async job => {
+  for (const screen of screens) {
+    await job.touch()        // ← not optional
+    await develop(screen)
+  }
+  return { ok: true }
+})
 ```
 
+Three rules, each of which has a failure mode attached:
+
+- **`touch()` in every long loop.** The broker judges liveness by the lock. Silence for longer
+  than `lockDuration` is indistinguishable from a dead worker, so the job is handed to someone
+  else while this one is still working — you get two runs, not one.
+- **Children report, parents decide.** A child returns `{ ok: false, error }` for a DOMAIN
+  failure; it does not throw. Throwing means "infrastructure broke, retry me". Children never set
+  `failParentOnFailure` — the parent reads `children()` / `failedChildren()` and decides.
+- **Retries default to one attempt.** These jobs mostly talk to a model, and a blind retry
+  re-spends the tokens that just failed. Raise `attempts` per queue only where jobs are cheap and
+  idempotent.
+
+## Being restartable
+
+A worker can die mid-job; the lock expires and the step re-runs. So a processor has to be safe to
+run twice — skip work already recorded, delete the rows a previous attempt created, or accept
+regenerating over a baseline. Decide this per job and say so in a comment; there is no way to make
+it automatic.
+
+## Errors cross the hop as classes
+
+A refusal the caller must recognise — `ContentRefused`, `AgentLocked` — is marshalled into the
+reply and rebuilt on the producer side as its own class, so `catch (e) { if (e instanceof ...) }`
+keeps working across the broker. Only broker- and connection-level faults propagate as throws,
+because those are the only ones a retry can fix.
+
+## What runs where
+
+`queueWorkerMiddleware()` starts the worker at the **Ready** stage — processors register while the
+application wires up, and binding earlier would take jobs the process cannot yet run. A process
+that listens to nothing registers no worker and pays nothing.
+
+`canServe` in `@owlmeans/server-api` excludes QUEUE routes, the same way it excludes sockets: the
+worker takes those jobs off the broker, and mounting them on the HTTP server too would answer
+every call twice.
+
+## Key exports
+
+| Export | Description |
+|--------|-------------|
+| `declareQueue` / `listenQueues` / `queueOf` | Configuration — what exists, what this process consumes |
+| `QueueResource<D, R>` | A queue addressed as a resource, plus `wait` / `flow` / `counts` |
+| `JobRecord<D, R>` / `JobState` / `JobEvent` | The record shape and lifecycle |
+| `QueueWorkerService` | `process(queue, name, fn)`, `start`, `stop`, `listening` |
+| `JobContext<D>` | What a processor gets: `data`, `signal`, `touch`, `progress`, `children` |
+| `appendQueueTransport` | Binds the QUEUE protocol so `call()` routes through the broker |
+| `queueWorkerMiddleware` | Starts the worker at Ready stage |
+| `handleJob` / `servedJobs` / `entrypointProcessor` | The bridge a driver dispatches through |
+| `QueueHooks` | `onJobResult`, `onJobStalled`, `onJobDead` — the compensation seam |
+
 ## Depends On
 
-- `@owlmeans/context` — service registration
+- `@owlmeans/context` — service registration and the middleware stage
+- `@owlmeans/entrypoint` — the transport seam and the served-entrypoint dispatch
+- `@owlmeans/route` — `RouteProtocols.QUEUE` and the `job()` builder
+- `@owlmeans/resource` — the `Resource` contract jobs are read through
+- `@owlmeans/error` — marshalling a refusal across the hop
+
+## Related
+
+- `redis-queue` — the BullMQ driver; integration tests for queue behaviour live there
+- `entrypoint` — declarations, elevation, and the transport lookup
+- `resource` — the criteria and paging semantics `list` follows

package/build/bridge.d.ts

@@ -0,0 +1,27 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { Config, Context, JobContext, JobEnvelope, JobReply } from './types.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 declare const requestOf: (envelope: JobEnvelope, path: string) => AbstractRequest;
+/**
+ * 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 declare const assertFresh: (envelope: JobEnvelope, ttl?: number) => void;
+/**
+ * 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 declare const handleJob: <C extends Config, T extends Context<C>>(context: T, job: JobContext<JobEnvelope>) => Promise<JobReply>;
+//# sourceMappingURL=bridge.d.ts.map

package/build/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkC,MAAM,sBAAsB,CAAA;AAM3F,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGpF;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,WAAW,EAAE,MAAM,MAAM,KAAG,eAO9D,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,WAAW,EAAE,MAAM,MAAM,KAAG,IAQjE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,EACpE,SAAS,CAAC,EAAE,KAAK,UAAU,CAAC,WAAW,CAAC,KACvC,OAAO,CAAC,QAAQ,CAyDlB,CAAA"}

package/build/bridge.js

@@ -0,0 +1,93 @@
+import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint';
+import { AuthorizationError } from '@owlmeans/auth';
+import { attachEntity } from '@owlmeans/auth-common';
+import { ResilientError } from '@owlmeans/error';
+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, path) => ({
+    alias: envelope.alias,
+    params: (envelope.params ?? {}),
+    body: envelope.body,
+    headers: (envelope.headers ?? {}),
+    query: (envelope.query ?? {}),
+    path,
+});
+/**
+ * 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, ttl) => {
+    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 (context, job) => {
+    const envelope = job.data;
+    try {
+        assertFresh(envelope, context.cfg.queue?.envelopeTtl);
+        const entrypoint = context.entrypoint(envelope.alias);
+        if (entrypoint.handle == null) {
+            throw new JobNotServed(envelope.alias);
+        }
+        const request = requestOf(envelope, entrypoint.path());
+        const response = provideResponse();
+        const guards = entrypoint.getGuards();
+        if (guards.length > 0) {
+            let matched;
+            for (const alias of guards) {
+                const guard = context.service(alias);
+                if (await guard.match(request, response)) {
+                    matched = guard;
+                    break;
+                }
+            }
+            if (matched == null) {
+                throw new AuthorizationError(`queue:${envelope.alias}`);
+            }
+            const auth = provideResponse();
+            if (!await matched.handle(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;
+    }
+};
+//# sourceMappingURL=bridge.js.map

package/build/bridge.js.map

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

package/build/config.d.ts

@@ -0,0 +1,22 @@
+import type { Config, JobOptions, QueueDeclaration, QueueWorkerOptions } from './types.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 declare const declareQueue: <C extends Config>(cfg: C, name: string, jobs: string[], opts?: {
+    worker?: QueueWorkerOptions;
+    defaults?: JobOptions;
+}) => C;
+/**
+ * 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 declare const listenQueues: <C extends Config>(cfg: C, ...names: string[]) => C;
+/**
+ * @throws {UnknownQueue}
+ */
+export declare const queueOf: <C extends Config>(cfg: C, name: string) => QueueDeclaration;
+export declare const queueOfJob: <C extends Config>(cfg: C, job: string) => QueueDeclaration | undefined;
+export declare const isListening: <C extends Config>(cfg: C, name: string) => boolean;
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAG1F;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,EAC3C,KAAK,CAAC,EAAE,MAAM,MAAM,EAAE,MAAM,MAAM,EAAE,EAAE,OAAO;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,KAClG,CAcF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,MAAM,EAAE,KAAG,CAM3E,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,MAAM,KAAG,gBAQhE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,MAAM,KAAG,gBAAgB,GAAG,SACpB,CAAA;AAElE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,MAAM,KAAG,OACzB,CAAA"}

package/build/config.js

@@ -0,0 +1,41 @@
+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 = (cfg, name, jobs, opts) => {
+    const queue = { 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 = (cfg, ...names) => {
+    const listen = new Set([...(cfg.queue?.listen ?? []), ...names]);
+    cfg.queue = { ...cfg.queue, listen: [...listen] };
+    return cfg;
+};
+/**
+ * @throws {UnknownQueue}
+ */
+export const queueOf = (cfg, name) => {
+    const queue = cfg.queue?.queues?.find(declared => declared.name === name);
+    if (queue == null) {
+        throw new UnknownQueue(name);
+    }
+    return queue;
+};
+export const queueOfJob = (cfg, job) => cfg.queue?.queues?.find(declared => declared.jobs.includes(job));
+export const isListening = (cfg, name) => cfg.queue?.listen?.includes(name) === true;
+//# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,GAAM,EAAE,IAAY,EAAE,IAAc,EAAE,IAA6D,EAChG,EAAE;IACL,MAAM,KAAK,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAA;IACvD,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAA;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IAErE,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAA;IAC1B,CAAC;IAED,GAAG,CAAC,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,CAAA;IAEpC,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAmB,GAAM,EAAE,GAAG,KAAe,EAAK,EAAE;IAC9E,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAA;IAEhE,GAAG,CAAC,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAA;IAEjD,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAmB,GAAM,EAAE,IAAY,EAAoB,EAAE;IAClF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IAEzE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAmB,GAAM,EAAE,GAAW,EAAgC,EAAE,CAChG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;AAElE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAmB,GAAM,EAAE,IAAY,EAAW,EAAE,CAC7E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA"}

package/build/consts.d.ts

@@ -0,0 +1,33 @@
+export declare 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 declare 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 declare const isSettled: (state?: JobState) => boolean;
+export declare 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 declare const DEFAULT_JOB_TIMEOUT = 60000;
+/**
+ * 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 declare const DEFAULT_ATTEMPTS = 1;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,aAAa,UAAU,CAAA;AAEpC;;;;GAIG;AACH,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,8DAA8D;AAC9D,eAAO,MAAM,SAAS,GAAI,QAAQ,QAAQ,KAAG,OACc,CAAA;AAE3D,oBAAY,YAAY;IACtB,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAA"}

package/build/consts.js

@@ -0,0 +1,35 @@
+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 var JobState;
+(function (JobState) {
+    JobState["Waiting"] = "waiting";
+    JobState["Delayed"] = "delayed";
+    JobState["Active"] = "active";
+    JobState["Completed"] = "completed";
+    JobState["Failed"] = "failed";
+    JobState["Unknown"] = "unknown";
+})(JobState || (JobState = {}));
+/** A job has reached a state it will not leave on its own. */
+export const isSettled = (state) => state === JobState.Completed || state === JobState.Failed;
+export var JobEventType;
+(function (JobEventType) {
+    JobEventType["Completed"] = "completed";
+    JobEventType["Failed"] = "failed";
+    JobEventType["Progress"] = "progress";
+})(JobEventType || (JobEventType = {}));
+/**
+ * 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;
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAA;AAEpC;;;;GAIG;AACH,MAAM,CAAN,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,+BAAmB,CAAA;IACnB,+BAAmB,CAAA;IACnB,6BAAiB,CAAA;IACjB,mCAAuB,CAAA;IACvB,6BAAiB,CAAA;IACjB,+BAAmB,CAAA;AACrB,CAAC,EAPW,QAAQ,KAAR,QAAQ,QAOnB;AAED,8DAA8D;AAC9D,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAgB,EAAW,EAAE,CACrD,KAAK,KAAK,QAAQ,CAAC,SAAS,IAAI,KAAK,KAAK,QAAQ,CAAC,MAAM,CAAA;AAE3D,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,uCAAuB,CAAA;IACvB,iCAAiB,CAAA;IACjB,qCAAqB,CAAA;AACvB,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAA;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,59 @@
+import { ResilientError } from '@owlmeans/error';
+export declare class QueueError extends ResilientError {
+    static typeName: string;
+    constructor(message?: string);
+}
+/**
+ * The caller stopped waiting. The job is untouched — it may still be queued, running, or already
+ * finished; only the wait ended. Read the job back to learn which.
+ */
+export declare class QueueTimeout extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/** No job with that id in this queue — it never existed, or it was removed after completing. */
+export declare class UnknownJob extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/**
+ * A job name the queue does not declare. Declaring every job a queue accepts is what keeps an
+ * enqueue from succeeding into a queue where nothing can ever process it.
+ */
+export declare class UnknownJobName extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/** A queue asked for that no declaration names. */
+export declare class UnknownQueue extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/**
+ * This process was asked to consume a queue it does not listen to. Which queues a process
+ * consumes is configuration (`cfg.queue.listen`), so this is a deployment question, not a code
+ * one — the same binary is a producer or a worker depending on it.
+ */
+export declare class QueueNotListening extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/**
+ * The job named an entrypoint this process does not serve. Unlike a missing queue this is not a
+ * declaration problem: the alias exists, but nothing here elevated it, so the job was taken by a
+ * worker that cannot run it.
+ */
+export declare class JobNotServed extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/**
+ * The signed envelope is older than the configured lifetime. Freshness is judged from when the
+ * producer enqueued the job, not from when a worker picked it up, so a long backlog does not
+ * invalidate work that was legitimate when it was submitted.
+ */
+export declare class EnvelopeExpired extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,UAAW,SAAQ,cAAc;IAC5C,OAAuB,QAAQ,SAAe;gBAElC,OAAO,GAAE,MAAgB;CAGtC;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAkC;gBAErD,GAAG,EAAE,MAAM;CAIxB;AAED,gGAAgG;AAChG,qBAAa,UAAW,SAAQ,UAAU;IACxC,OAAuB,QAAQ,SAAqC;gBAExD,GAAG,EAAE,MAAM;CAIxB;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,OAAuB,QAAQ,SAAyC;gBAE5D,GAAG,EAAE,MAAM;CAIxB;AAED,mDAAmD;AACnD,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAuC;gBAE1D,GAAG,EAAE,MAAM;CAIxB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,OAAuB,QAAQ,SAAuC;gBAE1D,GAAG,EAAE,MAAM;CAIxB;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAuC;gBAE1D,GAAG,EAAE,MAAM;CAIxB;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,OAAuB,QAAQ,SAA0C;gBAE7D,GAAG,EAAE,MAAM;CAIxB"}