@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/infra/queue/configured-processor.js

@@ -0,0 +1,23 @@
+import { Processor } from "@nestjs/bullmq";
+/**
+ * A `@Processor(queue)` provider whose worker options come from the application's startup config
+ * (`@Processor` reads them from class metadata when the worker is built, at module init, so they
+ * cannot be read from an injected service). Returns `{ provide: base, useClass }` with a subclass
+ * of `base` decorated for this application only, so two applications in one process (tests, the
+ * dual-replica harness) each get their own options. `base` is an `@Injectable` `WorkerHost` without
+ * `@Processor` of its own; inject it by `base`.
+ *
+ * The worker never starts by itself (`autorun: false`): the role that consumes calls
+ * `worker.run()` once the start sequence reached it (the kernel's worker role, after the extension
+ * load), and pauses it on stop.
+ */
+export function configuredProcessor(base, queue, options) {
+    if (queue.includes(":"))
+        throw new Error(`queue name "${queue}" must not contain ":"`);
+    // `base` implements `process`; the cast only lets an anonymous subclass extend the abstract type
+    const Configured = class extends base {
+    };
+    Object.defineProperty(Configured, "name", { value: base.name });
+    Processor(queue, { ...options, autorun: false })(Configured);
+    return { provide: base, useClass: Configured };
+}

package/dist/infra/queue/job-failure.d.ts

@@ -0,0 +1,18 @@
+import type { Job } from "bullmq";
+import type { KernelLogger } from "../../log.js";
+export interface LogJobFailureOptions {
+    /** Extra fields added to the record. */
+    tags?: Record<string, string>;
+    /**
+     * Overrides the "final failure" decision. By default a failure is final when
+     * `attemptsMade >= opts.attempts`; an `UnrecoverableError` fails the job at once with attempts
+     * left, so a caller holding the error instance passes `final: true`.
+     */
+    final?: boolean;
+}
+/**
+ * One log line for a failed BullMQ job, by retry progress: `error` when final, `warn` while
+ * retries remain. Business errors (`ApiError`) are skipped: they are already recorded in the
+ * job's own status or database rows. Use it from `@OnWorkerEvent("failed")`.
+ */
+export declare function logJobFailure(log: KernelLogger, job: Job, error: Error, options?: LogJobFailureOptions): void;

package/dist/infra/queue/job-failure.js

@@ -0,0 +1,26 @@
+import { ApiError } from "../../errors.js";
+/**
+ * One log line for a failed BullMQ job, by retry progress: `error` when final, `warn` while
+ * retries remain. Business errors (`ApiError`) are skipped: they are already recorded in the
+ * job's own status or database rows. Use it from `@OnWorkerEvent("failed")`.
+ */
+export function logJobFailure(log, job, error, options) {
+    if (error instanceof ApiError)
+        return;
+    const maxAttempts = job.opts?.attempts ?? 1;
+    const final = options?.final ?? job.attemptsMade >= maxAttempts;
+    const fields = {
+        queue: job.queueName,
+        jobId: String(job.id ?? ""),
+        attempt: job.attemptsMade,
+        maxAttempts,
+        final,
+        err: error,
+        ...options?.tags,
+    };
+    const msg = `queue job failed [${job.queueName}#${job.id}] attempt=${job.attemptsMade}/${maxAttempts}`;
+    if (final)
+        log.error(msg, fields);
+    else
+        log.warn(msg, fields);
+}

package/dist/infra/queue/queue-shutdown.d.ts

@@ -0,0 +1,27 @@
+import { type BeforeApplicationShutdown } from "@nestjs/common";
+import { DiscoveryService } from "@nestjs/core";
+import type { KernelLogger } from "../../log.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+/** The least time a queue or worker gets to close when the stop budget is used up. */
+export declare const MIN_CLOSE_MS = 1000;
+/** What is kept of the stop budget for the infra closes that follow (bus, Redis, the pool). */
+export declare const INFRA_RESERVE_MS = 2000;
+/**
+ * Closes every BullMQ queue (`registerQueue`) and `@Processor` worker of the application within
+ * what is left of the stop budget (less {@link INFRA_RESERVE_MS}), before `@nestjs/bullmq` closes
+ * them again in `onApplicationShutdown` without a limit. A close waits for Redis, which never
+ * answers while Redis is down:
+ * - a queue is registered with `forceDisconnectOnShutdown` (`QueueModule.registerQueue`), and one
+ *   that does not close in time is disconnected here;
+ * - a worker has no such option, and its close also waits for its main loop, which retries its
+ *   blocked command until Redis answers again: one that does not close in time is disconnected
+ *   and abandoned like the infra closes (`closeWithin`), its later close returning at once (the
+ *   one monkeypatch: otherwise `@nestjs/bullmq`'s own close would hold the application's close).
+ */
+export declare class QueueShutdown implements BeforeApplicationShutdown {
+    private readonly discovery;
+    private readonly log;
+    private readonly shutdown?;
+    constructor(discovery: Pick<DiscoveryService, "getProviders">, log: Pick<KernelLogger, "warn">, shutdown?: Pick<GracefulShutdown, "remainingMs"> | undefined);
+    beforeApplicationShutdown(): Promise<void>;
+}

package/dist/infra/queue/queue-shutdown.js

@@ -0,0 +1,81 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { DiscoveryService } from "@nestjs/core";
+import { Queue } from "bullmq";
+import { closeWithin } from "../close-within.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+/** The least time a queue or worker gets to close when the stop budget is used up. */
+export const MIN_CLOSE_MS = 1_000;
+/** What is kept of the stop budget for the infra closes that follow (bus, Redis, the pool). */
+export const INFRA_RESERVE_MS = 2_000;
+/**
+ * Closes every BullMQ queue (`registerQueue`) and `@Processor` worker of the application within
+ * what is left of the stop budget (less {@link INFRA_RESERVE_MS}), before `@nestjs/bullmq` closes
+ * them again in `onApplicationShutdown` without a limit. A close waits for Redis, which never
+ * answers while Redis is down:
+ * - a queue is registered with `forceDisconnectOnShutdown` (`QueueModule.registerQueue`), and one
+ *   that does not close in time is disconnected here;
+ * - a worker has no such option, and its close also waits for its main loop, which retries its
+ *   blocked command until Redis answers again: one that does not close in time is disconnected
+ *   and abandoned like the infra closes (`closeWithin`), its later close returning at once (the
+ *   one monkeypatch: otherwise `@nestjs/bullmq`'s own close would hold the application's close).
+ */
+let QueueShutdown = class QueueShutdown {
+    discovery;
+    log;
+    shutdown;
+    constructor(discovery, log, shutdown) {
+        this.discovery = discovery;
+        this.log = log;
+        this.shutdown = shutdown;
+    }
+    async beforeApplicationShutdown() {
+        const targets = [];
+        for (const wrapper of this.discovery.getProviders()) {
+            const instance = wrapper.instance;
+            if (instance instanceof Queue) {
+                targets.push({ label: `queue ${instance.name}`, target: instance, worker: false });
+            }
+            else if (instance instanceof WorkerHost) {
+                // a processor whose worker was never built (no registration) has nothing to close
+                let worker;
+                try {
+                    worker = instance.worker;
+                }
+                catch {
+                    worker = undefined;
+                }
+                if (worker)
+                    targets.push({ label: `worker ${worker.name}`, target: worker, worker: true });
+            }
+        }
+        const left = this.shutdown?.remainingMs() ?? MIN_CLOSE_MS + INFRA_RESERVE_MS;
+        const budget = Math.max(MIN_CLOSE_MS, left - INFRA_RESERVE_MS);
+        await Promise.all(targets.map(async ({ label, target, worker }) => {
+            if (await closeWithin(label, target.close(), budget, this.log))
+                return;
+            // not awaited: the disconnect itself waits for the connection
+            void target.disconnect().catch(() => { });
+            if (worker)
+                Object.defineProperty(target, "close", { value: () => Promise.resolve() });
+        }));
+    }
+};
+QueueShutdown = __decorate([
+    Injectable(),
+    __param(0, Inject(DiscoveryService)),
+    __param(1, Inject(KERNEL_LOGGER)),
+    __param(2, Optional()),
+    __param(2, Inject(GracefulShutdown))
+], QueueShutdown);
+export { QueueShutdown };

package/dist/infra/queue/queue.module.d.ts

@@ -0,0 +1,16 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { DefaultJobOptions } from "bullmq";
+/** Defaults of every job a kernel queue adds (the values `ctx.queue` uses today). */
+export declare const QUEUE_JOB_DEFAULTS: DefaultJobOptions;
+/**
+ * Global: the BullMQ root configuration (the kernel's Redis URL, BullMQ's default key prefix, which
+ * the hand-made queues also use, and {@link QUEUE_JOB_DEFAULTS}). A feature module that owns a
+ * queue imports `QueueModule.registerQueue(...names)` and declares a `@Processor(name)` provider;
+ * without the registration the processor has no queue and never consumes. Queue names and job
+ * ids must not contain `:`.
+ */
+export declare class QueueModule {
+    static forRoot(): DynamicModule;
+    /** Registers queues in the importing feature module (names without `:`). */
+    static registerQueue(...names: string[]): DynamicModule;
+}

package/dist/infra/queue/queue.module.js

@@ -0,0 +1,61 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var QueueModule_1;
+import { BullModule } from "@nestjs/bullmq";
+import { Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { QueueShutdown } from "./queue-shutdown.js";
+import { bullConnectionOptions } from "./redis-connection.js";
+/** Defaults of every job a kernel queue adds (the values `ctx.queue` uses today). */
+export const QUEUE_JOB_DEFAULTS = {
+    attempts: 3,
+    backoff: { type: "exponential", delay: 1000 },
+    removeOnComplete: 1000,
+    removeOnFail: 5000,
+};
+/**
+ * Global: the BullMQ root configuration (the kernel's Redis URL, BullMQ's default key prefix, which
+ * the hand-made queues also use, and {@link QUEUE_JOB_DEFAULTS}). A feature module that owns a
+ * queue imports `QueueModule.registerQueue(...names)` and declares a `@Processor(name)` provider;
+ * without the registration the processor has no queue and never consumes. Queue names and job
+ * ids must not contain `:`.
+ */
+let QueueModule = QueueModule_1 = class QueueModule {
+    static forRoot() {
+        return {
+            module: QueueModule_1,
+            global: true,
+            imports: [
+                DiscoveryModule,
+                BullModule.forRootAsync({
+                    inject: [KernelConfigService],
+                    useFactory: (config) => ({
+                        connection: bullConnectionOptions(config.get().redis.url),
+                        defaultJobOptions: QUEUE_JOB_DEFAULTS,
+                    }),
+                }),
+            ],
+            // every queue and worker closes within the stop budget (before @nestjs/bullmq's own close)
+            providers: [QueueShutdown],
+        };
+    }
+    /** Registers queues in the importing feature module (names without `:`). */
+    static registerQueue(...names) {
+        for (const name of names) {
+            if (name.includes(":"))
+                throw new Error(`queue name "${name}" must not contain ":"`);
+        }
+        // forceDisconnectOnShutdown: a queue's connection is dropped after its close at shutdown
+        return BullModule.registerQueue(...names.map((name) => ({ name, forceDisconnectOnShutdown: true })));
+    }
+};
+QueueModule = QueueModule_1 = __decorate([
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], QueueModule);
+export { QueueModule };

package/dist/infra/queue/redis-connection.d.ts

@@ -0,0 +1,7 @@
+import type { RedisOptions } from "bullmq";
+/**
+ * BullMQ connection options from the kernel's Redis URL, the same connection the hand-made
+ * `new Redis(url, { maxRetriesPerRequest: null })` workers use: BullMQ requires
+ * `maxRetriesPerRequest: null` on the blocking connection.
+ */
+export declare function bullConnectionOptions(url: string): RedisOptions;

package/dist/infra/queue/redis-connection.js

@@ -0,0 +1,18 @@
+/**
+ * BullMQ connection options from the kernel's Redis URL, the same connection the hand-made
+ * `new Redis(url, { maxRetriesPerRequest: null })` workers use: BullMQ requires
+ * `maxRetriesPerRequest: null` on the blocking connection.
+ */
+export function bullConnectionOptions(url) {
+    const u = new URL(url);
+    const db = u.pathname.length > 1 ? Number(u.pathname.slice(1)) : undefined;
+    return {
+        host: u.hostname,
+        port: u.port ? Number(u.port) : 6379,
+        ...(u.username && { username: decodeURIComponent(u.username) }),
+        ...(u.password && { password: decodeURIComponent(u.password) }),
+        ...(db !== undefined && Number.isInteger(db) && { db }),
+        ...(u.protocol === "rediss:" && { tls: {} }),
+        maxRetriesPerRequest: null,
+    };
+}

package/dist/infra/queue/retired-schedulers.d.ts

@@ -0,0 +1,7 @@
+import type { Queue } from "bullmq";
+/**
+ * Removes job schedulers that no job uses any more (fixed-period jobs that became `@LockedCron` /
+ * `@LockedInterval` jobs leave their old BullMQ schedulers in Redis on an upgraded deployment).
+ * Idempotent; replicas may race.
+ */
+export declare function removeRetiredSchedulers(queue: Pick<Queue, "removeJobScheduler">, ids: readonly string[]): Promise<void>;

package/dist/infra/queue/retired-schedulers.js

@@ -0,0 +1,9 @@
+/**
+ * Removes job schedulers that no job uses any more (fixed-period jobs that became `@LockedCron` /
+ * `@LockedInterval` jobs leave their old BullMQ schedulers in Redis on an upgraded deployment).
+ * Idempotent; replicas may race.
+ */
+export async function removeRetiredSchedulers(queue, ids) {
+    for (const id of ids)
+        await queue.removeJobScheduler(id);
+}

package/dist/infra/queue/run-job.d.ts

@@ -0,0 +1,16 @@
+import { type ContextJob } from "../../log-context.js";
+/**
+ * The wrapper every queue processor runs its job in: a fresh async context (no transaction of
+ * whoever enqueued the job or started the worker is visible), `queue` / `jobId` / `runId` in the
+ * log context, and the tracing span when tracing is on (`withJobContext`).
+ *
+ * ```ts
+ * @Processor("cap-kernel-titles")
+ * class TitleProcessor extends WorkerHost {
+ *   process(job: Job) {
+ *     return runJob("cap-kernel-titles", job, () => this.titles.generate(job.data));
+ *   }
+ * }
+ * ```
+ */
+export declare function runJob<T>(queue: string, job: ContextJob, fn: () => Promise<T>): Promise<T>;

package/dist/infra/queue/run-job.js

@@ -0,0 +1,19 @@
+import { withJobContext } from "../../log-context.js";
+import { runOutsideTransaction } from "../database/transaction-host.js";
+/**
+ * The wrapper every queue processor runs its job in: a fresh async context (no transaction of
+ * whoever enqueued the job or started the worker is visible), `queue` / `jobId` / `runId` in the
+ * log context, and the tracing span when tracing is on (`withJobContext`).
+ *
+ * ```ts
+ * @Processor("cap-kernel-titles")
+ * class TitleProcessor extends WorkerHost {
+ *   process(job: Job) {
+ *     return runJob("cap-kernel-titles", job, () => this.titles.generate(job.data));
+ *   }
+ * }
+ * ```
+ */
+export function runJob(queue, job, fn) {
+    return runOutsideTransaction(() => withJobContext(queue, job, fn));
+}

package/dist/infra/redis/redis.module.d.ts

@@ -0,0 +1,24 @@
+import { Redis } from "ioredis";
+import { type BusSubscriber } from "../../ctx/bus.js";
+import type { KernelLogger } from "../../log.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+/**
+ * Closes the bus subscriber, then the main connection, at the end of the shutdown
+ * (`GracefulShutdown.closeLast`: together with the pool), within what is left of the total stop
+ * budget. A ready main connection is closed with QUIT, so commands still in flight (a lock
+ * release, an after-commit publish) complete; it is dropped when QUIT does not finish in time or
+ * the connection is not ready.
+ */
+export declare class RedisLifecycle {
+    private readonly redis;
+    private readonly subscriber;
+    private readonly log;
+    private readonly shutdown;
+    constructor(redis: Redis, subscriber: BusSubscriber & {
+        close(): Promise<void>;
+    }, log: KernelLogger, shutdown: GracefulShutdown);
+    close(): Promise<void>;
+}
+/** Global: the main Redis connection, the bus subscriber connection and the kernel bus. */
+export declare class RedisModule {
+}

package/dist/infra/redis/redis.module.js

@@ -0,0 +1,87 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Global, Inject, Injectable, Module } from "@nestjs/common";
+import { Redis } from "ioredis";
+import { createBus, createBusSubscriber } from "../../ctx/bus.js";
+import { closeWithin } from "../close-within.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
+/**
+ * Closes the bus subscriber, then the main connection, at the end of the shutdown
+ * (`GracefulShutdown.closeLast`: together with the pool), within what is left of the total stop
+ * budget. A ready main connection is closed with QUIT, so commands still in flight (a lock
+ * release, an after-commit publish) complete; it is dropped when QUIT does not finish in time or
+ * the connection is not ready.
+ */
+let RedisLifecycle = class RedisLifecycle {
+    redis;
+    subscriber;
+    log;
+    shutdown;
+    constructor(redis, subscriber, log, shutdown) {
+        this.redis = redis;
+        this.subscriber = subscriber;
+        this.log = log;
+        this.shutdown = shutdown;
+        shutdown.closeLast(() => this.close());
+    }
+    async close() {
+        const { shutdown, log } = this;
+        await closeWithin("bus", this.subscriber.close(), shutdown.remainingMs(), log);
+        if (this.redis.status === "ready" &&
+            (await closeWithin("redis", this.redis.quit(), shutdown.remainingMs(), log))) {
+            return;
+        }
+        this.redis.disconnect();
+    }
+};
+RedisLifecycle = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(REDIS_SUBSCRIBER)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(GracefulShutdown))
+], RedisLifecycle);
+export { RedisLifecycle };
+/** Global: the main Redis connection, the bus subscriber connection and the kernel bus. */
+let RedisModule = class RedisModule {
+};
+RedisModule = __decorate([
+    Global(),
+    Module({
+        imports: [GracefulShutdownModule],
+        providers: [
+            {
+                provide: REDIS,
+                inject: [KernelConfigService, KERNEL_LOGGER],
+                useFactory: (config, log) => {
+                    const redis = new Redis(config.get().redis.url, { lazyConnect: true });
+                    redis.on("error", (err) => log.error("redis connection error", { err }));
+                    return redis;
+                },
+            },
+            {
+                provide: REDIS_SUBSCRIBER,
+                inject: [KernelConfigService, KERNEL_LOGGER],
+                useFactory: (config, log) => createBusSubscriber(() => new Redis(config.get().redis.url), log),
+            },
+            {
+                provide: KERNEL_BUS,
+                inject: [REDIS, REDIS_SUBSCRIBER, KERNEL_LOGGER],
+                useFactory: (redis, sub, log) => createBus(redis, sub, "kernel", log),
+            },
+            RedisLifecycle,
+        ],
+        exports: [REDIS, REDIS_SUBSCRIBER, KERNEL_BUS],
+    })
+], RedisModule);
+export { RedisModule };

package/dist/infra/schedule/cron-tick.d.ts

@@ -0,0 +1,12 @@
+export interface CronTick {
+    /** The scheduled fire time (epoch ms) of the tick a call at `now` belongs to. */
+    tick: number;
+    /** The gap between that tick and the next scheduled one, ms. */
+    periodMs: number;
+}
+/**
+ * The scheduled tick a cron callback invoked at `now` belongs to: the latest scheduled time at or
+ * before `now` (plus a small early-fire tolerance). It comes from the expression, not from the
+ * clock, so replicas whose callbacks run a few ms apart agree on it.
+ */
+export declare function scheduledTick(expression: string, now: number, timeZone?: string): CronTick;

package/dist/infra/schedule/cron-tick.js

@@ -0,0 +1,25 @@
+import { CronTime } from "cron";
+/** Timers may fire a little early; a call this close before a tick still belongs to it. */
+const EARLY_TOLERANCE_MS = 50;
+/**
+ * The scheduled tick a cron callback invoked at `now` belongs to: the latest scheduled time at or
+ * before `now` (plus a small early-fire tolerance). It comes from the expression, not from the
+ * clock, so replicas whose callbacks run a few ms apart agree on it.
+ */
+export function scheduledTick(expression, now, timeZone) {
+    const time = new CronTime(expression, timeZone);
+    const ref = now + EARLY_TOLERANCE_MS;
+    let window = 1000;
+    for (;;) {
+        let t = time.getNextDateFrom(new Date(ref - window), timeZone).toMillis();
+        if (t <= ref) {
+            for (;;) {
+                const next = time.getNextDateFrom(new Date(t), timeZone).toMillis();
+                if (next > ref)
+                    return { tick: t, periodMs: next - t };
+                t = next;
+            }
+        }
+        window *= 2;
+    }
+}

package/dist/infra/schedule/locked-cron.decorator.d.ts

@@ -0,0 +1,27 @@
+import { type CronOptions } from "@nestjs/schedule";
+export interface LockedCronOptions extends Pick<CronOptions, "timeZone"> {
+    /** Unique job name (the scheduler registry key and the log field). */
+    name: string;
+    /** Redis lock key (default `cron:<name>`); `lock:` is prepended unless present. */
+    lockKey?: string;
+    /** Lock lifetime without renewal, ms (default 30000); a longer run keeps it by renewal. */
+    ttl?: number;
+}
+/**
+ * `@Cron` with exactly-once-per-tick across replicas: every replica's scheduler fires, the one that
+ * sets the per-tick marker (`cron:<name>:<scheduled tick ms>`, never released) takes a try-once
+ * renewed run lock and runs the job; the others log INFO and skip, as does a tick whose
+ * predecessor is still running. An error in the job is logged (never thrown into the scheduler)
+ * and the lock is released afterwards. The job starts in a fresh async context (no transaction).
+ * The method gets a signal as its only argument: it aborts when the application stops
+ * (`ScheduledRuns`, which waits for the run, bounded) or when the run lock is lost. The class must inject `lockService`
+ * and `log`:
+ *
+ * ```ts
+ * constructor(
+ *   @Inject(LockService) readonly lockService: LockService,
+ *   @Inject(KERNEL_LOGGER) readonly log: KernelLogger,
+ * ) {}
+ * ```
+ */
+export declare function LockedCron(expression: string, options: LockedCronOptions): (target: object, key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/infra/schedule/locked-cron.decorator.js

@@ -0,0 +1,53 @@
+// Packages octok-platform's two-layer cron pattern (@Cron plus a try-once Redis lock in the job,
+// e.g. libs/app/src/billing/service/subscription-reconcile.job.ts; owner-approved, 2026-10-28).
+import { Cron } from "@nestjs/schedule";
+import { scheduledTick } from "./cron-tick.js";
+import { assertLockedJobHost, LOCKED_JOB, LOCKED_JOB_BODY, runLockedTick, } from "./locked-tick.js";
+/**
+ * `@Cron` with exactly-once-per-tick across replicas: every replica's scheduler fires, the one that
+ * sets the per-tick marker (`cron:<name>:<scheduled tick ms>`, never released) takes a try-once
+ * renewed run lock and runs the job; the others log INFO and skip, as does a tick whose
+ * predecessor is still running. An error in the job is logged (never thrown into the scheduler)
+ * and the lock is released afterwards. The job starts in a fresh async context (no transaction).
+ * The method gets a signal as its only argument: it aborts when the application stops
+ * (`ScheduledRuns`, which waits for the run, bounded) or when the run lock is lost. The class must inject `lockService`
+ * and `log`:
+ *
+ * ```ts
+ * constructor(
+ *   @Inject(LockService) readonly lockService: LockService,
+ *   @Inject(KERNEL_LOGGER) readonly log: KernelLogger,
+ * ) {}
+ * ```
+ */
+export function LockedCron(expression, options) {
+    return (target, key, descriptor) => {
+        const original = descriptor.value;
+        const lockKey = options.lockKey ?? `cron:${options.name}`;
+        // The scheduler's arguments (the cron library passes its onComplete) are not the job's
+        const wrapped = async function () {
+            // Not caught on purpose: a class without `lockService` / `log` is a programming error with
+            // no logger to report through; the call rejects (Nest's scheduler wrapper logs it, and the
+            // schedule tests rely on the rejection). Everything after it is caught below.
+            assertLockedJobHost(this, "cron");
+            // runLockedTick logs instead of throwing; this catch keeps the scheduler free of rejections
+            await runLockedTick(this, {
+                kind: "cron",
+                name: options.name,
+                lockKey,
+                ttl: options.ttl ?? 30_000,
+                tick: () => scheduledTick(expression, Date.now(), options.timeZone),
+                run: (signal) => Promise.resolve(original.call(this, signal)),
+            }).catch((err) => this.log?.error("cron job failed", { cron: options.name, err }));
+        };
+        Reflect.defineMetadata(LOCKED_JOB, true, wrapped);
+        Reflect.defineMetadata(LOCKED_JOB_BODY, { name: options.name, body: original }, wrapped);
+        descriptor.value = wrapped;
+        // The scheduler reads the metadata from the final method, so register after wrapping.
+        Cron(expression, {
+            name: options.name,
+            ...(options.timeZone !== undefined && { timeZone: options.timeZone }),
+        })(target, key, descriptor);
+        return descriptor;
+    };
+}

package/dist/infra/schedule/locked-interval.d.ts

@@ -0,0 +1,69 @@
+import { type OnApplicationBootstrap, type OnModuleDestroy } from "@nestjs/common";
+import { DiscoveryService, MetadataScanner } from "@nestjs/core";
+import type { KernelConfig } from "../../config/schema.js";
+import type { KernelLogger } from "../../log.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+/** The period of a `@LockedInterval` job, read from the config (once, when it is scheduled). */
+export type IntervalPeriod = (config: KernelConfig) => number;
+export interface LockedIntervalOptions {
+    /** Redis lock key (default `cron:<name>`); `lock:` is prepended unless present. */
+    lockKey?: string;
+    /** Lock lifetime without renewal, ms (default 30000); a longer run keeps it by renewal. */
+    ttl?: number;
+    /**
+     * Also run once when the application has started (after the start sequence, without blocking
+     * it), once across replicas starting together (see `startMarkerTtl`), as a new repeatable
+     * scheduler's first run did.
+     */
+    runOnStart?: boolean;
+}
+/** The tick a call at `now` belongs to: the latest multiple of the period at or before it. */
+export declare function intervalTick(periodMs: number, now: number): {
+    tick: number;
+    periodMs: number;
+};
+/**
+ * Like `@LockedCron`, for a job whose period comes from the config (a number of milliseconds that
+ * a cron expression cannot express, such as `extensionHost.reconcileIntervalSeconds`): every
+ * replica fires at the multiples of the period (epoch-aligned, so replicas agree on the tick), and
+ * the same two layers run the job exactly once per tick across replicas. The period is read when
+ * the application starts (like the old repeatable schedulers, not hot). The method gets
+ * the same signal as a `@LockedCron` job (the stop, or the loss of the run lock). The class must inject
+ * `lockService`, `log` and `config` (`KernelConfigService`); {@link LockedIntervalScheduler}
+ * schedules every decorated method of the application's providers.
+ */
+export declare function LockedInterval(name: string, period: IntervalPeriod, options?: LockedIntervalOptions): (_target: object, _key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Schedules the `@LockedInterval` jobs of every provider at `onApplicationBootstrap` (each timer
+ * fires at the next multiple of the job's period, then re-arms) and stops them when the
+ * application stops (`ScheduledRuns` calls {@link stopAll} and waits for the runs in progress).
+ * One instance, in `KernelScheduleModule`.
+ */
+export declare class LockedIntervalScheduler implements OnApplicationBootstrap, OnModuleDestroy {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly config;
+    private readonly log;
+    private readonly timers;
+    private readonly periods;
+    private readonly startRuns;
+    private stopped;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, config: KernelConfigService, log: KernelLogger);
+    onApplicationBootstrap(): void;
+    /** The scheduled job names. */
+    names(): string[];
+    /** A scheduled job's period in ms (read from the config at bootstrap), undefined when unknown. */
+    periodOf(name: string): number | undefined;
+    /**
+     * Starts the start runs of the `runOnStart` jobs in the background (each once across replicas
+     * starting together) and returns their promises. The kernel's worker role calls it right after it
+     * opened the start gate (`ScheduledRuns.open()`); later calls start nothing.
+     */
+    runStartJobs(): Promise<void>[];
+    /** Stops one job's timer (a run in progress finishes). */
+    stop(name: string): void;
+    /** Stops every timer and drops the start runs not started yet (idempotent). */
+    stopAll(): void;
+    onModuleDestroy(): void;
+    private arm;
+}