@pikku/queue-nats 0.12.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @pikku/queue-nats
+
+## 0.12.1
+
+### Patch Changes
+
+- 427c4fe: **`@pikku/queue-nats`** — NATS JetStream queue, worker and scheduler services, alongside the pg-boss and bullmq adapters. Jobs publish to a work-queue stream, each queue gets its own durable pull consumer, and `max_ack_pending` is real per-message concurrency rather than a batch size, so a slow job occupies one slot instead of holding its batch siblings. The per-job retry policy travels in headers because JetStream's `max_deliver` is per-consumer and cannot express a step marked "never retry", and `ack_wait` is always set to pg-boss's 900s parity rather than left to the server's 30s default — unset, any job running longer than 30s is redelivered while it is still running and executed twice. Cron and one-shot delays use the server's own message scheduler, so a schedule is a retained message on a reserved subject: publishing registers it, republishing replaces it, purging cancels it. That needs a server on 2.14+, and `NatsServiceFactory` refuses to start against anything older rather than silently not scheduling. `supportsResults` is `false`, deliberately — a work-queue stream deletes a message on ack, so there is nowhere for a job result or any job history to live, and per-job outcomes come from telemetry instead.
+- Updated dependencies [1ab831e]
+  - @pikku/core@0.12.105

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 - present Yasser Fadl and Pikku contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @pikku/queue-nats
+
+NATS JetStream queue, worker and scheduler services for Pikku. Backed by a
+JetStream work-queue stream, with the schedules living in the broker rather
+than in a database.
+
+Requires a NATS server on 2.14 or newer — that is the release that added
+repeating cron schedules, and `NatsServiceFactory` refuses to start against
+anything older rather than silently not scheduling.
+
+## Install
+
+```bash
+npm install @pikku/queue-nats
+```
+
+## Usage
+
+```typescript
+import { NatsServiceFactory } from '@pikku/queue-nats'
+
+const factory = new NatsServiceFactory({
+  servers: 'nats://localhost:4222',
+  streamName: 'pikku',
+  subjectPrefix: 'pikku',
+})
+await factory.init()
+
+const queue = factory.getQueueService()
+const workers = factory.getQueueWorkers()
+
+await workers.registerQueues()
+```
+
+Use `NatsSchedulerService` for cron wirings. For a Postgres-backed alternative
+see `@pikku/queue-pg-boss`, and for a Redis-backed one `@pikku/queue-bullmq`.
+
+## Job results
+
+`supportsResults` is `false`. A work-queue stream deletes a message the moment
+it is acked, so there is nowhere for a job result — or any job history — to
+live. Per-job outcomes come from telemetry, not from the broker; producers that
+need a return value should use an RPC rather than a queue.
+
+## Docs
+
+https://pikku.dev/docs

package/dist/consume.d.ts

@@ -0,0 +1,54 @@
+import type { ConsumerConfig, JetStreamClient, JetStreamManager, JsMsg } from '@nats-io/jetstream';
+import type { Logger } from '@pikku/core/services';
+export interface ConsumeOptions {
+    js: JetStreamClient;
+    jsm: JetStreamManager;
+    streamName: string;
+    subjectPrefix: string;
+    queueName: string;
+    /** Merged over the defaults produced by `mapPikkuWorkerToNats`. */
+    config?: Partial<ConsumerConfig>;
+    /**
+     * Handles one message. It owns the message's terminal call — exactly one of
+     * `ack`/`nak`/`term` — because only the caller knows whether a failure is
+     * retryable. A handler that returns without acking leaves the message to be
+     * redelivered after `ack_wait`.
+     */
+    handler: (msg: JsMsg) => Promise<void>;
+    /**
+     * Used to report a pull session that ended and had to be re-established.
+     * Optional only so existing callers and tests keep compiling — pass it in
+     * production, because a silent re-attach loop is the failure this guards.
+     */
+    logger?: Pick<Logger, 'error' | 'info'>;
+}
+export interface ConsumeHandle {
+    /** Stop pulling. In-flight handlers are left to settle their own acks. */
+    stop: () => void;
+    /** Handlers currently running — messages delivered but not yet settled. */
+    readonly inFlight: number;
+    /**
+     * Stop pulling, then wait for in-flight handlers to settle their acks.
+     *
+     * Resolves `true` if everything drained, `false` if the timeout expired
+     * first. Timing out is safe rather than lossy — whatever is still unacked is
+     * redelivered after `ack_wait`. Draining just avoids paying that redelivery
+     * latency on every deploy, and avoids re-running side effects a handler had
+     * already performed before it was killed.
+     */
+    drain: (timeoutMs: number) => Promise<boolean>;
+}
+/**
+ * Start a durable pull consumer and dispatch its messages to `handler`.
+ *
+ * The one thing that must never change here: `handler` is launched, not
+ * awaited. Awaiting inside the `for await` would serialise processing no matter
+ * what `max_ack_pending` says, so a single slow job would stall every message
+ * behind it — the same head-of-line blocking as a pg-boss batch handler, just
+ * moved client-side. In-flight work stays bounded anyway, because the server
+ * will not deliver more than `max_ack_pending` unacked messages at once.
+ *
+ * This exists as a shared function precisely so that invariant is written down
+ * once and every consumer inherits it, rather than being re-derived per caller.
+ */
+export declare const consumeQueue: (options: ConsumeOptions) => Promise<ConsumeHandle>;

package/dist/consume.js

@@ -0,0 +1,213 @@
+import { consumerNameForQueue, subjectForQueue } from './utils.js';
+/** Backoff bounds for re-establishing a pull session that ended under us. */
+const REATTACH_MIN_DELAY_MS = 250;
+const REATTACH_MAX_DELAY_MS = 30_000;
+/**
+ * How many consecutive "can't reach it" notifications count as dead rather than
+ * transient. Missed heartbeats and a not-found consumer both occur harmlessly
+ * during a reconnect, so a single one must not tear down a healthy session.
+ */
+const REATTACH_NOTIFICATION_THRESHOLD = 3;
+/**
+ * Decide whether a notification means this pull session is permanently dead,
+ * returning the reason to log if so.
+ *
+ * This exists because of a trap documented in the client's own types: for a
+ * durable pull consumer these conditions do NOT end the message iterator. On
+ * `consumer_deleted` the docs say outright that "the client will continue to
+ * attempt to pull messages" — only an *ordered* consumer recreates itself. So
+ * the session sits there issuing pulls that can never be answered, the
+ * `for await` never returns, and no error is ever thrown. Watching `status()`
+ * is the only way to find out, which is why the supervisor below cannot rely on
+ * the iterator ending on its own.
+ */
+const fatalNotificationReason = (notification) => {
+    switch (notification.type) {
+        case 'consumer_deleted':
+            return `consumer deleted server-side (${notification.code} ${notification.description})`;
+        case 'stream_not_found':
+            return `stream ${notification.name} not found`;
+        case 'consumer_not_found':
+            return notification.count >= REATTACH_NOTIFICATION_THRESHOLD
+                ? `consumer not found on ${notification.count} consecutive pulls`
+                : null;
+        case 'heartbeats_missed':
+            return notification.count >= REATTACH_NOTIFICATION_THRESHOLD
+                ? `${notification.count} consecutive heartbeats missed`
+                : null;
+        default:
+            return null;
+    }
+};
+/**
+ * Start a durable pull consumer and dispatch its messages to `handler`.
+ *
+ * The one thing that must never change here: `handler` is launched, not
+ * awaited. Awaiting inside the `for await` would serialise processing no matter
+ * what `max_ack_pending` says, so a single slow job would stall every message
+ * behind it — the same head-of-line blocking as a pg-boss batch handler, just
+ * moved client-side. In-flight work stays bounded anyway, because the server
+ * will not deliver more than `max_ack_pending` unacked messages at once.
+ *
+ * This exists as a shared function precisely so that invariant is written down
+ * once and every consumer inherits it, rather than being re-derived per caller.
+ */
+export const consumeQueue = async (options) => {
+    const { js, jsm, streamName, subjectPrefix, queueName, config, handler, logger, } = options;
+    const durable = consumerNameForQueue(subjectPrefix, queueName);
+    // `add` is CONSUMER.CREATE: a no-op when the existing durable matches, but it
+    // THROWS "consumer already exists" when any setting differs. So create first,
+    // then fall back to update — otherwise the first deploy after changing a
+    // queue's batchSize or lockDuration would fail at boot, on the second deploy
+    // rather than the one that introduced the change. Same failure shape as
+    // STREAM.CREATE vs STREAM.UPDATE in nats-service-factory.
+    const consumerConfig = {
+        durable_name: durable,
+        filter_subject: subjectForQueue(subjectPrefix, queueName),
+        ...config,
+    };
+    const attach = async () => {
+        try {
+            await jsm.consumers.add(streamName, consumerConfig);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!/already exists|already in use/i.test(message))
+                throw err;
+            await jsm.consumers.update(streamName, durable, consumerConfig);
+        }
+        const consumer = await js.consumers.get(streamName, durable);
+        return await consumer.consume();
+    };
+    let stopped = false;
+    let inFlight = 0;
+    // Bumped on every re-attach so a watcher left over from a previous session
+    // can never stop the session that replaced it.
+    let generation = 0;
+    const describe = (err) => err instanceof Error ? err.message : String(err);
+    // Turns a silently-dead session into an ended one, which is the single shape
+    // the supervisor below knows how to recover from.
+    const watchStatus = (session, sessionGeneration) => {
+        void (async () => {
+            try {
+                for await (const notification of session.status()) {
+                    if (stopped || generation !== sessionGeneration)
+                        return;
+                    const reason = fatalNotificationReason(notification);
+                    if (reason === null)
+                        continue;
+                    logger?.error(`NATS consumer ${durable} on ${streamName}: ${reason} — dropping the pull session so it can re-attach`);
+                    session.stop();
+                    return;
+                }
+            }
+            catch {
+                // The status stream itself ending or failing is not the failure we are
+                // guarding: the message iterator reports its own end, and the supervisor
+                // acts on that. Swallowed so this never surfaces as an unhandled
+                // rejection during shutdown.
+            }
+        })();
+    };
+    // The first attach is awaited and NOT retried: a failure here is a bad stream
+    // or consumer config, and boot must fail loudly on it rather than spin.
+    let messages = await attach();
+    watchStatus(messages, generation);
+    // Not awaited: this supervisor runs for the lifetime of the consumer.
+    //
+    // The inner `for await` is a pull SESSION, not the consumer itself, and the
+    // session can die while the consumer lives on. Before this loop existed the
+    // iterator simply ran off the end: the IIFE resolved, nothing pulled ever
+    // again, and nothing said so. The durable consumer still existed server-side
+    // with its backlog growing, every health check stayed green, and the only
+    // symptom was work silently not happening. That is exactly how the
+    // orchestrator queue reached 1681 undelivered messages while the backend
+    // looked healthy — see knowledge/stability.md. So: re-attach, with backoff,
+    // and say so at error level every time.
+    //
+    // Note this loop alone is not enough, which is why `watchStatus` exists: the
+    // iterator ending is only one of the two ways a session dies, and it is the
+    // less common one. The other is the session staying open forever while the
+    // server has nothing to answer it with, and only `status()` reveals that.
+    void (async () => {
+        let backoffMs = REATTACH_MIN_DELAY_MS;
+        for (;;) {
+            try {
+                for await (const msg of messages) {
+                    if (stopped)
+                        break;
+                    // Deliberately NOT awaited — see the note above. The counter is what
+                    // lets shutdown wait for these without serialising them; `finally` is
+                    // chained rather than `catch`ed so a rejecting handler still surfaces
+                    // as an unhandled rejection exactly as it did before.
+                    //
+                    // Started through a resolved promise so that a handler which throws
+                    // SYNCHRONOUSLY rejects like any other failure instead of unwinding
+                    // into the catch below, which would diagnose a handler bug as a dead
+                    // pull session and re-attach for no reason.
+                    const settled = Promise.resolve().then(() => handler(msg));
+                    inFlight++;
+                    void settled.finally(() => {
+                        inFlight--;
+                    });
+                }
+                if (stopped)
+                    return;
+                logger?.error(`NATS consumer ${durable} on ${streamName}: pull session ended unexpectedly — re-attaching`);
+            }
+            catch (err) {
+                if (stopped)
+                    return;
+                logger?.error(`NATS consumer ${durable} on ${streamName}: pull session threw (${describe(err)}) — re-attaching`);
+            }
+            // Re-attach until it takes. `stop()` is checked on both sides of the wait
+            // so a shutdown during backoff exits instead of reviving the consumer.
+            for (;;) {
+                if (stopped)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+                if (stopped)
+                    return;
+                try {
+                    messages = await attach();
+                    // `stop()` only stops the session it can see, so one that arrives
+                    // after shutdown began has to stop itself. Without this the loop
+                    // below would enter `for await` on a live session whose only exit is
+                    // a message arriving — on an idle queue, never — leaving a pull
+                    // consumer on the connection after `drain()` reported it settled.
+                    if (stopped) {
+                        messages.stop();
+                        return;
+                    }
+                    generation++;
+                    watchStatus(messages, generation);
+                    logger?.info(`NATS consumer ${durable} on ${streamName}: re-attached`);
+                    backoffMs = REATTACH_MIN_DELAY_MS;
+                    break;
+                }
+                catch (err) {
+                    logger?.error(`NATS consumer ${durable} on ${streamName}: re-attach failed (${describe(err)}), retrying in ${backoffMs}ms`);
+                    backoffMs = Math.min(backoffMs * 2, REATTACH_MAX_DELAY_MS);
+                }
+            }
+        }
+    })();
+    const stop = () => {
+        stopped = true;
+        messages.stop();
+    };
+    return {
+        stop,
+        get inFlight() {
+            return inFlight;
+        },
+        drain: async (timeoutMs) => {
+            stop();
+            const deadline = Date.now() + timeoutMs;
+            while (inFlight > 0 && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            return inFlight === 0;
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module @pikku/queue-nats
+ *
+ * NATS JetStream queue service for Pikku.
+ *
+ * Mirrors `@pikku/queue-pg-boss` / `@pikku/queue-bullmq`, with one deliberate
+ * difference:
+ *
+ *  - `supportsResults` is false. A work-queue stream deletes a message on ack,
+ *    so there is nowhere for a job result — or any job history — to live.
+ *    Success rates and per-job outcomes come from telemetry, not the broker.
+ *
+ * This package used to carry a second difference: no scheduler service, because
+ * JetStream had no delayed or scheduled message primitive, so cron and delayed
+ * work had to stay on a database-backed queue under the rule "Postgres owns
+ * time, NATS owns delivery". That stopped being true — server 2.12 added
+ * one-shot `@at` delays and 2.14 added repeating cron schedules — so NATS now
+ * owns both. Requires a server on 2.14+; `NatsServiceFactory` refuses to start
+ * against anything older rather than silently not scheduling.
+ *
+ * A database has not left the picture entirely, and shouldn't: the broker has
+ * no API to list schedules and no record of whether a fire succeeded, so a
+ * schedule registry and a last-fired ledger belong in one. NATS owns *when*,
+ * the database owns *what is registered* and *what happened*.
+ */
+export { NatsServiceFactory } from './nats-service-factory.js';
+export type { NatsServiceFactoryOptions } from './nats-service-factory.js';
+export { NatsQueueService } from './nats-queue-service.js';
+export type { DelayedPublisher } from './nats-queue-service.js';
+export { NatsDelayedPublisher } from './nats-delayed-publisher.js';
+export { NatsSchedulerService, toNatsCron, parseNatsSchedule, } from './nats-scheduler-service.js';
+export { NatsQueueWorkers, mapPikkuWorkerToNats } from './nats-queue-worker.js';
+export { consumeQueue } from './consume.js';
+export type { ConsumeHandle, ConsumeOptions } from './consume.js';
+export { consumerNameForQueue, queueNameToToken, subjectForQueue, backoffDelayMs, attemptsFor, backoffFor, scheduleSubjectFor, PIKKU_USER_ID_HEADER, NATS_MSG_ID_HEADER, ATTEMPTS_HEADER, BACKOFF_TYPE_HEADER, BACKOFF_DELAY_HEADER, SCHEDULE_HEADER, SCHEDULE_TARGET_HEADER, SCHEDULE_TIMEZONE_HEADER, SCHEDULE_NEXT_HEADER, SCHEDULER_HEADER, SCHEDULE_SUBJECT_SEGMENT, } from './utils.js';
+export { headers as natsHeaders } from '@nats-io/nats-core';
+export type { QueueService, PikkuWorkerConfig, PikkuJobConfig, QueueJob, JobOptions, } from '@pikku/core/queue';

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * @module @pikku/queue-nats
+ *
+ * NATS JetStream queue service for Pikku.
+ *
+ * Mirrors `@pikku/queue-pg-boss` / `@pikku/queue-bullmq`, with one deliberate
+ * difference:
+ *
+ *  - `supportsResults` is false. A work-queue stream deletes a message on ack,
+ *    so there is nowhere for a job result — or any job history — to live.
+ *    Success rates and per-job outcomes come from telemetry, not the broker.
+ *
+ * This package used to carry a second difference: no scheduler service, because
+ * JetStream had no delayed or scheduled message primitive, so cron and delayed
+ * work had to stay on a database-backed queue under the rule "Postgres owns
+ * time, NATS owns delivery". That stopped being true — server 2.12 added
+ * one-shot `@at` delays and 2.14 added repeating cron schedules — so NATS now
+ * owns both. Requires a server on 2.14+; `NatsServiceFactory` refuses to start
+ * against anything older rather than silently not scheduling.
+ *
+ * A database has not left the picture entirely, and shouldn't: the broker has
+ * no API to list schedules and no record of whether a fire succeeded, so a
+ * schedule registry and a last-fired ledger belong in one. NATS owns *when*,
+ * the database owns *what is registered* and *what happened*.
+ */
+export { NatsServiceFactory } from './nats-service-factory.js';
+export { NatsQueueService } from './nats-queue-service.js';
+// Backs workflow.sleep() and backoff retries, using the server's own scheduler.
+// Wired automatically by NatsServiceFactory; exported for tests and for callers
+// building a queue service by hand.
+export { NatsDelayedPublisher } from './nats-delayed-publisher.js';
+export { NatsSchedulerService, toNatsCron, parseNatsSchedule, } from './nats-scheduler-service.js';
+export { NatsQueueWorkers, mapPikkuWorkerToNats } from './nats-queue-worker.js';
+// For consumers that need their own dispatch loop rather than pikku's queue
+// registry — e.g. a dispatcher whose queues are shared across tenants and must
+// not collide with the registry's global queue names.
+export { consumeQueue } from './consume.js';
+export { consumerNameForQueue, queueNameToToken, subjectForQueue, backoffDelayMs, attemptsFor, backoffFor, scheduleSubjectFor, PIKKU_USER_ID_HEADER, NATS_MSG_ID_HEADER, ATTEMPTS_HEADER, BACKOFF_TYPE_HEADER, BACKOFF_DELAY_HEADER, SCHEDULE_HEADER, SCHEDULE_TARGET_HEADER, SCHEDULE_TIMEZONE_HEADER, SCHEDULE_NEXT_HEADER, SCHEDULER_HEADER, SCHEDULE_SUBJECT_SEGMENT, } from './utils.js';
+// Re-exported so callers that publish their own messages (a dispatcher parking
+// a job on a DLQ, say) can build headers without taking a direct dependency on
+// nats-core — this package is the NATS boundary.
+export { headers as natsHeaders } from '@nats-io/nats-core';

package/dist/nats-delayed-publisher.d.ts

@@ -0,0 +1,35 @@
+import type { JetStreamClient } from '@nats-io/jetstream';
+import type { JobOptions } from '@pikku/core/queue';
+import type { DelayedPublisher } from './nats-queue-service.js';
+/**
+ * Delayed delivery using JetStream's own message scheduler (server 2.12+).
+ *
+ * Replaces the pg-boss republisher this package used to need. A message is
+ * published to a reserved schedule subject carrying `Nats-Schedule: @at <ts>`
+ * and `Nats-Schedule-Target: <the real queue subject>`; the server holds it and
+ * publishes the body verbatim onto the target when it comes due. Nothing polls,
+ * and no second store owns time.
+ *
+ * Two constraints shape the subject layout, both enforced by the server at
+ * publish time (error 10190, `message schedules target is invalid`):
+ *
+ *  - The target must be a subject captured by the SAME stream as the schedule.
+ *    Cross-stream scheduling does not exist; it would need a sourcing topology.
+ *  - The target must not be the schedule's own subject, which would make the
+ *    schedule reproduce itself forever.
+ *
+ * So schedules live inside the queue stream, under a subject prefix that no
+ * consumer filters on. That matters more than it looks: this is a WorkQueue
+ * stream, where a message is deleted the instant a consumer acks it, and a
+ * schedule that gets acked is a schedule that silently stops firing. No
+ * consumer subscribes to `<prefix>._schedule.>`, so nothing can ack one.
+ *
+ * One-shot `@at` schedules are purged by the server once they fire, so this
+ * leaves nothing behind to clean up.
+ */
+export declare class NatsDelayedPublisher implements DelayedPublisher {
+    private readonly js;
+    private readonly subjectPrefix;
+    constructor(js: JetStreamClient, subjectPrefix: string);
+    publishAfter<T>(queueName: string, data: T, delayMs: number, options?: JobOptions): Promise<string>;
+}

package/dist/nats-delayed-publisher.js

@@ -0,0 +1,85 @@
+import { headers } from '@nats-io/nats-core';
+import { ATTEMPTS_HEADER, BACKOFF_DELAY_HEADER, BACKOFF_TYPE_HEADER, PIKKU_USER_ID_HEADER, SCHEDULE_HEADER, SCHEDULE_TARGET_HEADER, attemptsHeaderValue, scheduleSubjectFor, subjectForQueue, } from './utils.js';
+/**
+ * Delayed delivery using JetStream's own message scheduler (server 2.12+).
+ *
+ * Replaces the pg-boss republisher this package used to need. A message is
+ * published to a reserved schedule subject carrying `Nats-Schedule: @at <ts>`
+ * and `Nats-Schedule-Target: <the real queue subject>`; the server holds it and
+ * publishes the body verbatim onto the target when it comes due. Nothing polls,
+ * and no second store owns time.
+ *
+ * Two constraints shape the subject layout, both enforced by the server at
+ * publish time (error 10190, `message schedules target is invalid`):
+ *
+ *  - The target must be a subject captured by the SAME stream as the schedule.
+ *    Cross-stream scheduling does not exist; it would need a sourcing topology.
+ *  - The target must not be the schedule's own subject, which would make the
+ *    schedule reproduce itself forever.
+ *
+ * So schedules live inside the queue stream, under a subject prefix that no
+ * consumer filters on. That matters more than it looks: this is a WorkQueue
+ * stream, where a message is deleted the instant a consumer acks it, and a
+ * schedule that gets acked is a schedule that silently stops firing. No
+ * consumer subscribes to `<prefix>._schedule.>`, so nothing can ack one.
+ *
+ * One-shot `@at` schedules are purged by the server once they fire, so this
+ * leaves nothing behind to clean up.
+ */
+export class NatsDelayedPublisher {
+    js;
+    subjectPrefix;
+    constructor(js, subjectPrefix) {
+        this.js = js;
+        this.subjectPrefix = subjectPrefix;
+    }
+    async publishAfter(queueName, data, delayMs, options) {
+        const hdrs = headers();
+        // RFC3339, which is what the server parses. A timestamp already in the past
+        // fires immediately rather than erroring — the same shape as pg-boss's
+        // `startAfter` with an elapsed date, so a delay that races the clock still
+        // delivers instead of being dropped.
+        hdrs.set(SCHEDULE_HEADER, `@at ${new Date(Date.now() + delayMs).toISOString()}`);
+        hdrs.set(SCHEDULE_TARGET_HEADER, subjectForQueue(this.subjectPrefix, queueName));
+        // Every non-schedule header is copied onto the produced message verbatim,
+        // so the job's retry policy survives the delay. `jobId` is deliberately not
+        // one of them, in either direction:
+        //
+        //  - As `Nats-Msg-Id` it would be pointless — the server strips that header
+        //    when producing, so it could never reach the stream's dedupe window.
+        //  - As the schedule's subject it would be actively wrong. Republishing to
+        //    a schedule subject REPLACES the schedule, so two delayed jobs sharing
+        //    a jobId would silently cancel each other. The pg-boss publisher this
+        //    replaces passed only `startAfter` and no singleton key, so delayed
+        //    publishes have never deduped; making them dedupe now would be a
+        //    behaviour change disguised as a port.
+        //
+        // Hence: no key, and every delayed publish gets its own subject.
+        const { delay: _delay, jobId: _jobId, ...rest } = options ?? {};
+        applyJobHeaders(hdrs, rest, queueName);
+        const ack = await this.js.publish(scheduleSubjectFor(this.subjectPrefix, queueName), JSON.stringify(data), { headers: hdrs });
+        return String(ack.seq);
+    }
+}
+/**
+ * Copy the queue-level job options that must survive the delay onto the
+ * schedule message. Kept here rather than shared with `NatsQueueService.add`
+ * because the two disagree deliberately about `jobId` — see above.
+ */
+const applyJobHeaders = (hdrs, options, queueName) => {
+    if (options.pikkuUserId) {
+        hdrs.set(PIKKU_USER_ID_HEADER, options.pikkuUserId);
+    }
+    if (options.attempts !== undefined) {
+        hdrs.set(ATTEMPTS_HEADER, attemptsHeaderValue(options.attempts, queueName));
+    }
+    if (options.backoff !== undefined) {
+        const backoff = typeof options.backoff === 'string'
+            ? { type: options.backoff }
+            : options.backoff;
+        hdrs.set(BACKOFF_TYPE_HEADER, backoff.type);
+        if (backoff.delay !== undefined) {
+            hdrs.set(BACKOFF_DELAY_HEADER, String(backoff.delay));
+        }
+    }
+};

package/dist/nats-queue-service.d.ts

@@ -0,0 +1,44 @@
+import type { JetStreamClient } from '@nats-io/jetstream';
+import type { JobOptions, QueueJob, QueueService } from '@pikku/core/queue';
+/**
+ * Delayed delivery. Implemented by `NatsDelayedPublisher` against the server's
+ * own message scheduler (2.12+); it used to be implemented against a store that
+ * owned time, because JetStream had no such primitive.
+ */
+export interface DelayedPublisher {
+    publishAfter<T>(queueName: string, data: T, delayMs: number, options?: JobOptions): Promise<string>;
+}
+/**
+ * JetStream queue service for publishing jobs.
+ *
+ * Deliberately narrower than the pg-boss and bullmq services in two ways, both
+ * forced by the broker rather than by choice — see `supportsResults` and
+ * `getJob` below.
+ */
+export declare class NatsQueueService implements QueueService {
+    private readonly js;
+    private readonly subjectPrefix;
+    /**
+     * A work-queue stream deletes a message the moment it is acked, so there is
+     * nowhere for a result to live and nothing to read it back from. Producers
+     * that need a return value should use an RPC, not a queue.
+     */
+    readonly supportsResults = false;
+    private delayedPublisher?;
+    constructor(js: JetStreamClient, subjectPrefix: string, delayedPublisher?: DelayedPublisher);
+    /**
+     * Attach the delayed publisher after construction. Needed because the pg-boss
+     * publisher republishes *through* this service, so the two reference each
+     * other and one of them has to be wired second.
+     */
+    setDelayedPublisher(publisher: DelayedPublisher): void;
+    add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>;
+    /**
+     * Not supported. A message in a work-queue stream is only reachable through a
+     * consumer, and only while it is being delivered — there is no lookup by id,
+     * and an acked message no longer exists. Returning null (rather than throwing)
+     * keeps callers that poll for optional status working; callers that genuinely
+     * need per-job state should read it from telemetry.
+     */
+    getJob<T, R>(_queueName: string, _jobId: string): Promise<QueueJob<T, R> | null>;
+}