@owlmeans/queue 0.1.18-rc.4 → 0.1.18-rc.40

package/agent-meta/skills/scheduled-jobs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: scheduled-jobs
+description: Recurring background work on OwlMeans queues — declareSchedule in @owlmeans/queue, reconciled into BullMQ job schedulers by @owlmeans/redis-queue when a listening worker starts. Covers interval vs cron schedules, the processor a sweep runs, overlap and restart semantics, renaming and removing a schedule, multi-replica and rolling-deploy behaviour, and testing. Use when adding a nightly or periodic job, replacing a platform CronJob or a setInterval with a schedule, or diagnosing a schedule that does not run.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Scheduled jobs
+
+**Layer:** Infra · **Packages:** `@owlmeans/queue` (lead — the declaration), `@owlmeans/redis-queue`
+(the reconciliation)
+
+A schedule is a declaration that makes the broker produce an ordinary job on an interval or a cron
+pattern. A worker that consumes the queue runs it with a processor. There is no second scheduler
+process, no cron table and no timer in application code.
+
+## When a schedule is the answer
+
+| Situation | Answer |
+|---|---|
+| Periodic sweep, reconciliation, digest, retention delete, rollup | A schedule on a queue a worker consumes |
+| "Remind this user in 20 minutes" | `JobOptions.delay` on one job — a schedule is not per record |
+| A far-future or cancellable per-record deadline | A row with a due date, swept by one schedule |
+| A deployment that runs no worker | A platform `CronJob` calling a guarded entrypoint |
+| A `setInterval` inside a request handler or a long-lived service | A schedule — the interval dies with the process and runs once per replica |
+
+Whether the work belongs on a queue at all is `resource-choice`.
+
+## Declaring
+
+In the SHARED package every process loads, after the queue:
+
+```typescript
+declareQueue(cfg, APP_MAINTENANCE, ['app:maintenance:reconcile', 'app:maintenance:purge'], {
+  worker: { concurrency: 1, lockDuration: 60_000 }
+})
+declareSchedule(cfg, {
+  id: 'app-nightly-reconcile', queue: APP_MAINTENANCE, name: 'app:maintenance:reconcile',
+  pattern: '17 3 * * *', tz: 'UTC', data: {},
+})
+declareSchedule(cfg, {
+  id: 'app-purge-expired', queue: APP_MAINTENANCE, name: 'app:maintenance:purge', every: 15 * 60_000,
+})
+```
+
+And only in the process that runs them: `listenQueues(cfg, APP_MAINTENANCE)` plus a processor per
+job name, registered while the context is wired.
+
+- **`pattern` for the calendar, `every` for a frequency.** A nightly job is a pattern with an
+  explicit `tz`; "every quarter hour, whenever" is `every`. Pick an odd minute (`17 3 * * *`) so
+  many applications' sweeps do not stampede one Redis at the top of the hour.
+- **`every` runs at once** when the scheduler is created (unless `startDate` says otherwise); a
+  pattern waits for its next match unless `immediately: true`, which fires only when the scheduler
+  is created or its declaration changes — never on an unchanged restart.
+- **The id is permanent.** It is the scheduler's identity in the broker: any other field changes in
+  place, a renamed id is a removed schedule plus a new one. Prefix it with the application
+  (`app-…`) — ids share one namespace per queue.
+- **Declaration errors surface at boot.** `declareSchedule` throws `UnknownQueue`,
+  `UnknownJobName` or `ScheduleMisdeclared` (`<id>:<reason>`) rather than letting the broker fail
+  on every tick.
+- **`opts` sets retries and retention for every run; `id` and `delay` are refused** — the broker
+  names each run and places it on the schedule.
+
+## Writing the processor
+
+```typescript
+const log = logger('maintenance') // from '@owlmeans/log'
+
+worker.process<Record<string, never>, SweepReport>(APP_MAINTENANCE, 'app:maintenance:reconcile',
+  async job => {
+    const report = { scanned: 0, repaired: 0, failed: 0 }
+    for await (const page of organizations({ size: 200 })) {
+      await job.touch()
+      for (const organization of page) {
+        try {
+          report.repaired += await reconcile(organization.entityId) ? 1 : 0
+        } catch (error) {
+          report.failed++
+          log.error('Reconcile failed', { entityId: organization.entityId, error })
+        }
+        report.scanned++
+      }
+    }
+    log.info('Maintenance run finished', { scheduled: job.scheduled, ...report }, { event: 'job.stop' })
+    return report
+  })
+```
+
+- **A scheduled run has no caller.** No credentials, no entity, no request: it is a processor job,
+  never a guarded entrypoint. A step that must go through another service's guard calls that
+  service with service credentials.
+- **Idempotent per item, not per run.** A worker rolled out mid-sweep, a stalled lock or a manual
+  re-run repeats the whole sweep; each item's repair must be a no-op the second time.
+- **One item's failure is logged and counted, never thrown.** A thrown sweep is retried from the
+  start, or dropped after its attempts — either way the other items pay for one bad record.
+- **`touch()` per page.** A sweep over every organization outlives `lockDuration` easily; silence
+  hands the job to another worker while this one is still going.
+- **Return a small report.** It lands on the completed job, where an operator reads it.
+
+## Overlap, replicas and deploys
+
+- **One job per tick, whatever the replica count.** The broker produces one job; one worker takes
+  it. Several replicas listening to the queue do not multiply runs.
+- **Runs can overlap on a concurrent queue.** The next run is produced when the previous one
+  starts, so a run that outlasts the interval meets its successor. Put sweeps on their own queue
+  with `concurrency: 1`, apart from interactive lanes.
+- **A schedule needs a consumer.** Only a listening worker creates the scheduler, and the next run
+  is produced only when the previous one starts processing. A queue nothing consumes stops.
+- **Every listener reconciles at start, from its own configuration.** It creates or updates what it
+  declares and removes the schedules it owns (`owlmeans:` scheduler ids) that it does not. Every
+  process listening to one queue must load the same schedule list; during a rolling deploy the
+  newest process to start wins, and the old pods leave the broker alone after their own start.
+- **Removing a schedule is deleting its declaration.** The next worker start removes the scheduler.
+  So is a declaration whose job name the queue no longer accepts, or whose `endDate` has passed.
+- **Scheduling never costs consumption.** A refused declaration or a broker failure while
+  reconciling is logged and skipped; the worker keeps consuming. Look for
+  `redis-queue-schedules:<queue>` in the worker's log when a schedule does not appear.
+
+## Diagnosing "it never ran"
+
+1. Is some process listening to the queue (`listenQueues`) and is its worker up?
+2. Did that process's start log a `redis-queue-schedules:<queue>` refusal?
+3. Does `new Queue(queue, { connection, prefix }).getJobSchedulers()` list `owlmeans:<id>` with the
+   expected `pattern`/`every`, `tz` and `next`?
+4. Is a processor registered for the job name? A run without one fails once as `UnknownJobName`
+   and shows in the failed state.
+5. Is a previous run still active on a `concurrency: 1` queue?
+
+## Testing
+
+- **The declaration** is category A in the application's own shared package: build the config,
+  `assertSchedules(cfg)`, and pin ids and job names against the queue declaration.
+- **The processor** is tested as a function over a fake `JobContext` or a real context — it is
+  ordinary code with a `touch`.
+- **Against a broker** (Redis-gated): the worker's Ready-stage start is not awaited by
+  `context.init()`, so poll the broker (`getJobSchedulers`) or wait for the first run instead of
+  asserting straight after boot. A queue's schedulers go with `obliterate()`.
+
+## External docs
+
+- https://docs.bullmq.io/guide/job-schedulers — `upsertJobScheduler(id, { every | pattern, tz,
+  startDate, endDate, limit, immediately }, { name, data, opts })` creates or updates one scheduler
+  per id and replaces its pending run; `getJobSchedulers()` / `removeJobScheduler(id)`. The next job
+  is added when the previous one starts processing, so a worker must be consuming. Produced jobs
+  carry `repeatJobKey` = the scheduler id.
+
+## Related
+
+- `queue` — `declareSchedule`, `JobContext.scheduled`, processor rules
+- `redis-queue` — `syncSchedules`, the `owlmeans:` ownership prefix, the reconciliation rules
+- `resource-choice` — whether recurring work belongs on a queue at all

package/build/bridge.d.ts

@@ -0,0 +1,30 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { BasicContext } from '@owlmeans/context';
+import type { Config, Context, JobContext, JobEnvelope, JobReply, QueueJobMeta } 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, context?: BasicContext<any>, job?: QueueJobMeta) => AbstractRequest;
+/** Read broker identity only where an entrypoint truly needs to bind work to an admission claim. */
+export declare const queueJobOf: (request: unknown) => QueueJobMeta | 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 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;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAMrD,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAGlG;;;GAGG;AACH,eAAO,MAAM,SAAS,aACV,WAAW,QAAQ,MAAM,YAAY,YAAY,CAAC,GAAG,CAAC,QAAQ,YAAY,KACnF,eAWD,CAAA;AAEF,oGAAoG;AACpG,eAAO,MAAM,UAAU,YAAa,OAAO,KAAG,YAAY,GAAG,IAK5D,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,aAAc,WAAW,QAAQ,MAAM,KAAG,IAQjE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WAC3D,CAAC,OAAO,UAAU,CAAC,WAAW,CAAC,KACvC,OAAO,CAAC,QAAQ,CA2DlB,CAAA"}

package/build/bridge.js

@@ -0,0 +1,108 @@
+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, context, job) => ({
+    alias: envelope.alias,
+    params: (envelope.params ?? {}),
+    body: envelope.body,
+    headers: (envelope.headers ?? {}),
+    query: (envelope.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) => {
+    if (request == null || typeof request !== 'object' || !('original' in request))
+        return null;
+    const original = request.original;
+    if (original == null || typeof original !== 'object' || !('_job' in original))
+        return null;
+    return original._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, 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(), context, {
+            id: job.id, name: job.name, queue: job.queue, attempt: job.attempt, touch: job.touch,
+        });
+        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,50 @@
+import type { Config, JobOptions, QueueDeclaration, QueueWorkerOptions, ScheduleDeclaration } 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;
+/**
+ * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
+ *
+ * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
+ * @throws {UnknownQueue} when the schedule's queue is not declared.
+ * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
+ * run of a name nothing declares would fail on every tick instead of once, at declaration.
+ */
+export declare const assertSchedule: <C extends Config>(cfg: C, schedule: ScheduleDeclaration) => void;
+/**
+ * Add a recurring job to the shared configuration. Declare the queue first — a schedule is checked
+ * against it here. Declaring an id twice replaces, like `declareQueue`.
+ *
+ * Declaring is all this does: the driver creates, updates and removes the broker's schedulers when
+ * a worker that listens to the queue starts.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
+ */
+export declare const declareSchedule: <C extends Config>(cfg: C, schedule: ScheduleDeclaration) => C;
+/** The declared schedules, of one queue when it is named. */
+export declare const schedulesOf: <C extends Config>(cfg: C, queue?: string) => ScheduleDeclaration[];
+/**
+ * Check every declared schedule, including any written into the configuration without
+ * `declareSchedule`, and refuse two under one id.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
+ */
+export declare const assertSchedules: <C extends Config>(cfg: C) => void;
+//# 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,EACV,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAC9E,MAAM,YAAY,CAAA;AAGnB;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,OACtC,CAAC,QAAQ,MAAM,QAAQ,MAAM,EAAE,SAAS;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,OAAO,CAAC,YAAY,MAAM,EAAE,KAAG,CAM3E,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,QAAQ,MAAM,KAAG,gBAQhE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,OAAO,MAAM,KAAG,gBAAgB,GAAG,SACpB,CAAA;AAElE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,QAAQ,MAAM,KAAG,OACzB,CAAA;AAM5C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,YAAY,mBAAmB,KAAG,IAoDxF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,YAAY,mBAAmB,KAAG,CAezF,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,UAAU,MAAM,KAAG,mBAAmB,EACE,CAAA;AAE5F;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,KAAG,IAS1D,CAAA"}

package/build/config.js

@@ -0,0 +1,141 @@
+import { ScheduleMisdeclared, UnknownJobName, 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;
+/** A date option the broker can read — a `Date`, epoch milliseconds or a parsable string. */
+const isInstant = (value) => Number.isFinite((value instanceof Date ? value : new Date(value)).getTime());
+/**
+ * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
+ *
+ * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
+ * @throws {UnknownQueue} when the schedule's queue is not declared.
+ * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
+ * run of a name nothing declares would fail on every tick instead of once, at declaration.
+ */
+export const assertSchedule = (cfg, schedule) => {
+    const { id } = schedule;
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new ScheduleMisdeclared('(empty):id');
+    }
+    const queue = queueOf(cfg, schedule.queue);
+    if (!queue.jobs.includes(schedule.name)) {
+        throw new UnknownJobName(`${schedule.queue}:${schedule.name}`);
+    }
+    const every = schedule.every != null;
+    const pattern = schedule.pattern != null;
+    if (every === pattern) {
+        throw new ScheduleMisdeclared(`${id}:every-or-pattern`);
+    }
+    if (every && !(Number.isSafeInteger(schedule.every) && schedule.every > 0)) {
+        throw new ScheduleMisdeclared(`${id}:every`);
+    }
+    if (pattern && (typeof schedule.pattern !== 'string' || schedule.pattern.trim() === '')) {
+        throw new ScheduleMisdeclared(`${id}:pattern`);
+    }
+    // Both only mean something to a cron pattern: an interval has no wall clock to read in a time
+    // zone, and its first run is immediate already.
+    if (!pattern && schedule.tz != null) {
+        throw new ScheduleMisdeclared(`${id}:tz`);
+    }
+    if (!pattern && schedule.immediately === true) {
+        throw new ScheduleMisdeclared(`${id}:immediately`);
+    }
+    if (schedule.immediately === true && schedule.startDate != null) {
+        throw new ScheduleMisdeclared(`${id}:immediately-start-date`);
+    }
+    if (schedule.limit != null && !(Number.isSafeInteger(schedule.limit) && schedule.limit > 0)) {
+        throw new ScheduleMisdeclared(`${id}:limit`);
+    }
+    if (schedule.startDate != null && !isInstant(schedule.startDate)) {
+        throw new ScheduleMisdeclared(`${id}:start-date`);
+    }
+    if (schedule.endDate != null && !isInstant(schedule.endDate)) {
+        throw new ScheduleMisdeclared(`${id}:end-date`);
+    }
+    // The type already omits both; a declaration assembled at runtime still reaches this check. The
+    // broker names every run itself and places it on the schedule, so either would be overridden.
+    const opts = schedule.opts;
+    if (opts?.id != null) {
+        throw new ScheduleMisdeclared(`${id}:opts-id`);
+    }
+    if (opts?.delay != null) {
+        throw new ScheduleMisdeclared(`${id}:opts-delay`);
+    }
+};
+/**
+ * Add a recurring job to the shared configuration. Declare the queue first — a schedule is checked
+ * against it here. Declaring an id twice replaces, like `declareQueue`.
+ *
+ * Declaring is all this does: the driver creates, updates and removes the broker's schedulers when
+ * a worker that listens to the queue starts.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
+ */
+export const declareSchedule = (cfg, schedule) => {
+    assertSchedule(cfg, schedule);
+    const schedules = cfg.queue?.schedules ?? [];
+    const existing = schedules.findIndex(declared => declared.id === schedule.id);
+    if (existing < 0) {
+        schedules.push(schedule);
+    }
+    else {
+        schedules[existing] = schedule;
+    }
+    cfg.queue = { ...cfg.queue, schedules };
+    return cfg;
+};
+/** The declared schedules, of one queue when it is named. */
+export const schedulesOf = (cfg, queue) => (cfg.queue?.schedules ?? []).filter(schedule => queue == null || schedule.queue === queue);
+/**
+ * Check every declared schedule, including any written into the configuration without
+ * `declareSchedule`, and refuse two under one id.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
+ */
+export const assertSchedules = (cfg) => {
+    const seen = new Set();
+    for (const schedule of schedulesOf(cfg)) {
+        assertSchedule(cfg, schedule);
+        if (seen.has(schedule.id)) {
+            throw new ScheduleMisdeclared(`${schedule.id}:duplicate`);
+        }
+        seen.add(schedule.id);
+    }
+};
+//# sourceMappingURL=config.js.map

package/build/config.js.map

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

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"
+}
+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;
+/** The transport identifier owned by the queue package. */
+export declare const QUEUE_PROTOCOL: 'queue';
+//# 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,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;AAEjC,2DAA2D;AAC3D,eAAO,MAAM,cAAc,EAAG,OAAgB,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 = {}));
+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;
+/** The transport identifier owned by the queue package. */
+export const QUEUE_PROTOCOL = 'queue';
+//# 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,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;AAEjC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAG,OAAgB,CAAA"}