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

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;
+}

package/dist/infra/schedule/locked-interval.js

@@ -0,0 +1,190 @@
+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 { Inject, Injectable, } from "@nestjs/common";
+import { DiscoveryService, MetadataScanner } from "@nestjs/core";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+import { assertLockedJobHost, LOCKED_JOB, LOCKED_JOB_BODY, runLockedTick, startMarkerTtl, } from "./locked-tick.js";
+const LOCKED_INTERVAL = Symbol("LOCKED_INTERVAL");
+/** Timers may fire a little early; a call this close before a tick still belongs to it. */
+const EARLY_TOLERANCE_MS = 50;
+/** The tick a call at `now` belongs to: the latest multiple of the period at or before it. */
+export function intervalTick(periodMs, now) {
+    const tolerance = Math.min(EARLY_TOLERANCE_MS, Math.floor(periodMs / 2));
+    return { tick: Math.floor((now + tolerance) / periodMs) * periodMs, periodMs };
+}
+/**
+ * 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 function LockedInterval(name, period, options = {}) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        const lockKey = options.lockKey ?? `cron:${name}`;
+        const wrapped = async function () {
+            assertLockedJobHost(this, "interval");
+            const config = this.config;
+            await runLockedTick(this, {
+                kind: "interval",
+                name,
+                lockKey,
+                ttl: options.ttl ?? 30_000,
+                tick: () => {
+                    if (!config) {
+                        throw new Error("@LockedInterval() needs the class to inject `KernelConfigService` as `config`.");
+                    }
+                    return intervalTick(period(config.get()), Date.now());
+                },
+                run: (signal) => Promise.resolve(original.call(this, signal)),
+            });
+        };
+        const start = async function () {
+            assertLockedJobHost(this, "interval");
+            const config = this.config;
+            await runLockedTick(this, {
+                kind: "interval",
+                name,
+                lockKey,
+                ttl: options.ttl ?? 30_000,
+                tick: () => {
+                    throw new Error("a start run has no tick");
+                },
+                start: { ttlMs: startMarkerTtl(config ? period(config.get()) : 60_000) },
+                run: (signal) => Promise.resolve(original.call(this, signal)),
+            });
+        };
+        Reflect.defineMetadata(LOCKED_JOB, true, wrapped);
+        Reflect.defineMetadata(LOCKED_JOB_BODY, { name, body: original }, wrapped);
+        Reflect.defineMetadata(LOCKED_INTERVAL, { name, period, ...(options.runOnStart === true && { start }) }, wrapped);
+        descriptor.value = wrapped;
+        return descriptor;
+    };
+}
+/**
+ * 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`.
+ */
+let LockedIntervalScheduler = class LockedIntervalScheduler {
+    discovery;
+    scanner;
+    config;
+    log;
+    timers = new Map();
+    periods = new Map();
+    startRuns = [];
+    stopped = false;
+    constructor(discovery, scanner, config, log) {
+        this.discovery = discovery;
+        this.scanner = scanner;
+        this.config = config;
+        this.log = log;
+    }
+    onApplicationBootstrap() {
+        for (const wrapper of this.discovery.getProviders()) {
+            const instance = wrapper.instance;
+            if (!instance || typeof instance !== "object" || !wrapper.isDependencyTreeStatic())
+                continue;
+            const proto = Object.getPrototypeOf(instance);
+            if (!proto)
+                continue;
+            for (const method of this.scanner.getAllMethodNames(proto)) {
+                const fn = instance[method];
+                if (typeof fn !== "function")
+                    continue;
+                const meta = Reflect.getMetadata(LOCKED_INTERVAL, fn);
+                if (!meta)
+                    continue;
+                if (this.timers.has(meta.name)) {
+                    throw new Error(`@LockedInterval job name ${meta.name} is used twice`);
+                }
+                const periodMs = meta.period(this.config.get());
+                if (!Number.isFinite(periodMs) || periodMs < 100) {
+                    throw new Error(`@LockedInterval job ${meta.name}: period ${periodMs} ms is too short`);
+                }
+                this.periods.set(meta.name, periodMs);
+                this.arm(meta.name, periodMs, () => fn.call(instance));
+                const start = meta.start;
+                if (start) {
+                    this.startRuns.push({
+                        name: meta.name,
+                        run: () => start.call(instance),
+                    });
+                }
+            }
+        }
+    }
+    /** The scheduled job names. */
+    names() {
+        return [...this.timers.keys()];
+    }
+    /** A scheduled job's period in ms (read from the config at bootstrap), undefined when unknown. */
+    periodOf(name) {
+        return this.periods.get(name);
+    }
+    /**
+     * 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() {
+        const runs = this.stopped ? [] : this.startRuns.splice(0);
+        return runs.map(({ name, run }) => run().catch((err) => this.log.error("interval start run failed", { job: name, err })));
+    }
+    /** Stops one job's timer (a run in progress finishes). */
+    stop(name) {
+        const t = this.timers.get(name);
+        if (t?.timer)
+            clearTimeout(t.timer);
+        this.timers.delete(name);
+    }
+    /** Stops every timer and drops the start runs not started yet (idempotent). */
+    stopAll() {
+        this.stopped = true;
+        this.startRuns.splice(0);
+        for (const name of [...this.timers.keys()])
+            this.stop(name);
+    }
+    onModuleDestroy() {
+        this.stopAll();
+    }
+    arm(name, periodMs, run) {
+        const slot = { timer: undefined };
+        this.timers.set(name, slot);
+        const next = () => {
+            const now = Date.now();
+            const at = (Math.floor(now / periodMs) + 1) * periodMs;
+            slot.timer = setTimeout(() => {
+                if (this.stopped || this.timers.get(name) !== slot)
+                    return;
+                next();
+                // runLockedTick never throws for a job error; this catches only a missing host property
+                run().catch((err) => this.log.error("interval job failed", { job: name, err }));
+            }, at - now);
+            slot.timer.unref();
+        };
+        next();
+    }
+};
+LockedIntervalScheduler = __decorate([
+    Injectable(),
+    __param(0, Inject(DiscoveryService)),
+    __param(1, Inject(MetadataScanner)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(KERNEL_LOGGER))
+], LockedIntervalScheduler);
+export { LockedIntervalScheduler };

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

@@ -0,0 +1,90 @@
+import type { KernelLogger } from "../../log.js";
+import type { LockService } from "../lock/lock.service.js";
+/** Marks a method wrapped by `@LockedCron` / `@LockedInterval` (read by `ScheduledRuns`). */
+export declare const LOCKED_JOB: unique symbol;
+/**
+ * The job's name and its undecorated body, on the wrapped method: `ScheduledRuns.runNow` runs the
+ * body once outside the schedule.
+ */
+export declare const LOCKED_JOB_BODY: unique symbol;
+/** What {@link LOCKED_JOB_BODY} holds. */
+export interface LockedJobBody {
+    name: string;
+    body: (signal?: AbortSignal) => unknown;
+}
+/** The property `ScheduledRuns` attaches itself under on every instance with a locked job. */
+export declare const SCHEDULED_RUNS: unique symbol;
+/** The properties a class with a `@LockedCron` / `@LockedInterval` job must inject. */
+export interface LockedJobHost {
+    lockService?: LockService;
+    log?: KernelLogger;
+    /** Attached by `ScheduledRuns` at module init (absent outside a Nest application). */
+    [SCHEDULED_RUNS]?: ScheduledRunScope;
+}
+/** What a locked job's run sees of `ScheduledRuns`: the stop state, the signal and the tracking. */
+export interface ScheduledRunScope {
+    /**
+     * The start gate (decision R21 of the Nest kernel spec): false until the role that runs the jobs
+     * opened it (the kernel's worker role, after the extension load) and again once the stop began;
+     * no run starts while it is shut.
+     */
+    readonly opened: boolean;
+    /** True once the stop began: no new run starts. */
+    readonly stopped: boolean;
+    /** Aborted when the stop begins; the job method's argument aborts with it. */
+    readonly signal: AbortSignal;
+    /** Registers a run the stop waits for (bounded); returns `p`. */
+    track<T>(p: Promise<T>): Promise<T>;
+}
+/**
+ * Throws when the class lacks `lockService` / `log` (a programming error, so the decorated call
+ * rejects); everything after this check is logged, never thrown.
+ */
+export declare function assertLockedJobHost(host: LockedJobHost, kind: "cron" | "interval"): void;
+/** The tick marker's lifetime: two periods, at least 10 s, at most a day. */
+export declare const tickMarkerTtl: (periodMs: number) => number;
+/**
+ * The start marker's lifetime: replicas that start within this window (one period, at most a
+ * minute) run a `runOnStart` job once; a replica restarted after it runs it again, like the first
+ * run of a newly created repeatable scheduler.
+ */
+export declare const startMarkerTtl: (periodMs: number) => number;
+/**
+ * Runs one scheduled tick of a job exactly once across replicas, in two layers:
+ * 1. one winner per tick: the replica that sets the per-tick marker `cron:<name>:<tick>` (never
+ *    released, so a fast job on the winner does not let a slower replica run the same tick);
+ * 2. a try-once renewed run lock (`lockKey`), so a long run never overlaps the next tick's run.
+ * The others log INFO and skip. 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).
+ *
+ * Inside a Nest application the run is tracked by `ScheduledRuns` (the stop aborts the signal the
+ * job gets and waits for the run, bounded) and no run starts before `ScheduledRuns.open()` (the
+ * timers are armed at application bootstrap, before the kernel's start sequence) or once the
+ * stop began; failures caused
+ * by the stop (an aborted job, a lock release after Redis closed) are logged at WARN / INFO. Only
+ * the host check rejects (see {@link assertLockedJobHost}).
+ */
+export declare function runLockedTick(host: LockedJobHost, o: {
+    kind: "cron" | "interval";
+    name: string;
+    lockKey: string;
+    ttl: number;
+    /** The tick (epoch ms) and the period it belongs to; thrown errors are logged as marker failures. */
+    tick: () => {
+        tick: number;
+        periodMs: number;
+    };
+    /**
+     * A start run (`@LockedInterval({ runOnStart })`) instead of a tick: the first layer is the
+     * start marker `cron:<name>:start` for `ttlMs` (see {@link startMarkerTtl}).
+     */
+    start?: {
+        ttlMs: number;
+    };
+    /**
+     * The job body; `signal` aborts when the stop begins (`ScheduledRuns`) or the run lock is lost.
+     * Only a body that reads `signal` stops on a lost lock; the others are idempotent sweeps that
+     * run to completion.
+     */
+    run: (signal: AbortSignal) => Promise<unknown>;
+}): Promise<void>;

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

@@ -0,0 +1,137 @@
+import { withLogContext } from "../../log-context.js";
+import { runOutsideTransaction } from "../database/transaction-host.js";
+/** Marks a method wrapped by `@LockedCron` / `@LockedInterval` (read by `ScheduledRuns`). */
+export const LOCKED_JOB = Symbol("LOCKED_JOB");
+/**
+ * The job's name and its undecorated body, on the wrapped method: `ScheduledRuns.runNow` runs the
+ * body once outside the schedule.
+ */
+export const LOCKED_JOB_BODY = Symbol("LOCKED_JOB_BODY");
+/** The property `ScheduledRuns` attaches itself under on every instance with a locked job. */
+export const SCHEDULED_RUNS = Symbol("SCHEDULED_RUNS");
+/**
+ * Throws when the class lacks `lockService` / `log` (a programming error, so the decorated call
+ * rejects); everything after this check is logged, never thrown.
+ */
+export function assertLockedJobHost(host, kind) {
+    if (!host.lockService || !host.log) {
+        const decorator = kind === "cron" ? "@LockedCron()" : "@LockedInterval()";
+        throw new Error(`${decorator} needs the class to inject \`LockService\` as \`lockService\` and the ` +
+            "logger as `log`.");
+    }
+}
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/** The tick marker's lifetime: two periods, at least 10 s, at most a day. */
+export const tickMarkerTtl = (periodMs) => Math.min(Math.max(periodMs * 2, 10_000), 24 * 3600_000);
+/**
+ * The start marker's lifetime: replicas that start within this window (one period, at most a
+ * minute) run a `runOnStart` job once; a replica restarted after it runs it again, like the first
+ * run of a newly created repeatable scheduler.
+ */
+export const startMarkerTtl = (periodMs) => Math.min(periodMs, 60_000);
+/**
+ * Runs one scheduled tick of a job exactly once across replicas, in two layers:
+ * 1. one winner per tick: the replica that sets the per-tick marker `cron:<name>:<tick>` (never
+ *    released, so a fast job on the winner does not let a slower replica run the same tick);
+ * 2. a try-once renewed run lock (`lockKey`), so a long run never overlaps the next tick's run.
+ * The others log INFO and skip. 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).
+ *
+ * Inside a Nest application the run is tracked by `ScheduledRuns` (the stop aborts the signal the
+ * job gets and waits for the run, bounded) and no run starts before `ScheduledRuns.open()` (the
+ * timers are armed at application bootstrap, before the kernel's start sequence) or once the
+ * stop began; failures caused
+ * by the stop (an aborted job, a lock release after Redis closed) are logged at WARN / INFO. Only
+ * the host check rejects (see {@link assertLockedJobHost}).
+ */
+export async function runLockedTick(host, o) {
+    assertLockedJobHost(host, o.kind);
+    const lockService = host.lockService;
+    const log = host.log;
+    const scope = host[SCHEDULED_RUNS];
+    if (scope?.stopped) {
+        log.info("cron skipped: the scheduler is stopping", { cron: o.name });
+        return;
+    }
+    if (scope && !scope.opened) {
+        // the start gate is shut: the start sequence (migrations, bootstrap, extensions) is not done
+        log.info("cron skipped: the scheduler is not started", { cron: o.name });
+        return;
+    }
+    const signal = scope?.signal;
+    /** Errors during the stop are expected (the job aborted, Redis closing): WARN, not ERROR. */
+    const logFailure = (msg, fields) => signal?.aborted ? log.warn(msg, fields) : log.error(msg, fields);
+    const run = runOutsideTransaction(() => withLogContext({ cron: o.name }, async () => {
+        let tick;
+        try {
+            if (o.start) {
+                tick = "start";
+                if (!(await lockService.lease(`cron:${o.name}:start`, "start", o.start.ttlMs))) {
+                    log.info("cron skipped: start run already taken by another replica", { cron: o.name });
+                    return;
+                }
+            }
+            else {
+                const t = o.tick();
+                tick = t.tick;
+                if (!(await lockService.lease(`cron:${o.name}:${tick}`, "tick", tickMarkerTtl(t.periodMs)))) {
+                    log.info("cron skipped: tick already taken by another replica", {
+                        cron: o.name,
+                        tick,
+                    });
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            logFailure("cron tick marker failed", { cron: o.name, err });
+            return;
+        }
+        let handle;
+        try {
+            handle = await lockService.acquire(o.lockKey, { ttlMs: o.ttl, waitMs: 0 });
+        }
+        catch (err) {
+            logFailure("cron lock failed", { cron: o.name, err });
+            return;
+        }
+        if (!handle) {
+            log.info("cron skipped: the previous run still holds the lock", { cron: o.name, tick });
+            return;
+        }
+        try {
+            if (signal?.aborted) {
+                log.info("cron skipped: the scheduler is stopping", { cron: o.name, tick });
+            }
+            else {
+                // the signal aborts on the stop and when the run lock is lost (another replica may take
+                // the lock and start the next run); only jobs that read it stop, the others are
+                // idempotent sweeps that run to completion
+                await o.run(signal ? AbortSignal.any([signal, handle.lost]) : handle.lost);
+            }
+        }
+        catch (err) {
+            if (signal?.aborted) {
+                log.info("cron run stopped by the shutdown", { cron: o.name, error: errMsg(err) });
+            }
+            else if (handle.lost.aborted) {
+                log.warn("cron run stopped: its run lock was lost", { cron: o.name, error: errMsg(err) });
+            }
+            else {
+                log.error("cron job failed", { cron: o.name, error: errMsg(err), err });
+            }
+        }
+        finally {
+            await handle
+                .release()
+                .catch((err) => logFailure("cron lock release failed", { cron: o.name, err }));
+        }
+    }));
+    try {
+        await (scope ? scope.track(run) : run);
+    }
+    catch (err) {
+        // runOutsideTransaction / withLogContext themselves; never into the scheduler
+        logFailure("cron run failed", { cron: o.name, err });
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * The cron scheduler (`@nestjs/schedule`), the `@LockedInterval` scheduler and the runs of both
+ * (`ScheduledRuns`: tracked, stopped within the stop budget). The one place that imports them;
+ * only worker-only modules import this module (`WorkerModule` and `MaintenanceModule`, which only
+ * `WorkerModule` imports), so only worker processes run `@LockedCron` / `@LockedInterval` jobs.
+ */
+export declare class KernelScheduleModule {
+}

package/dist/infra/schedule/schedule.module.js

@@ -0,0 +1,27 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import { ScheduleModule } from "@nestjs/schedule";
+import { LockedIntervalScheduler } from "./locked-interval.js";
+import { ScheduledRuns } from "./scheduled-runs.js";
+/**
+ * The cron scheduler (`@nestjs/schedule`), the `@LockedInterval` scheduler and the runs of both
+ * (`ScheduledRuns`: tracked, stopped within the stop budget). The one place that imports them;
+ * only worker-only modules import this module (`WorkerModule` and `MaintenanceModule`, which only
+ * `WorkerModule` imports), so only worker processes run `@LockedCron` / `@LockedInterval` jobs.
+ */
+let KernelScheduleModule = class KernelScheduleModule {
+};
+KernelScheduleModule = __decorate([
+    Module({
+        imports: [ScheduleModule.forRoot(), DiscoveryModule],
+        providers: [LockedIntervalScheduler, ScheduledRuns],
+        exports: [ScheduleModule, LockedIntervalScheduler, ScheduledRuns],
+    })
+], KernelScheduleModule);
+export { KernelScheduleModule };

package/dist/infra/schedule/scheduled-runs.d.ts

@@ -0,0 +1,69 @@
+import { type BeforeApplicationShutdown, type OnModuleInit } from "@nestjs/common";
+import { DiscoveryService, MetadataScanner } from "@nestjs/core";
+import { SchedulerRegistry } from "@nestjs/schedule";
+import type { KernelLogger } from "../../log.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+import { LockedIntervalScheduler } from "./locked-interval.js";
+import { type ScheduledRunScope } from "./locked-tick.js";
+/**
+ * The runs of the `@LockedCron` / `@LockedInterval` jobs (ticks and `runOnStart` runs), their
+ * start gate ({@link open}) and their stop. At module init it attaches itself to every provider instance with a locked job
+ * (`SCHEDULED_RUNS`), so each run is tracked and gets {@link signal}. {@link stop} (idempotent)
+ * stops the cron and interval timers, aborts the signal, refuses new runs and waits for the runs in
+ * progress within its budget, capped by what is left of the shared stop deadline
+ * (`GracefulShutdown`): the runs end (and release their locks) before Redis and the pool close.
+ * Runs over the budget are abandoned with a WARN; the job's own failures after the stop began are
+ * logged at WARN / INFO, never ERROR. The kernel's stop phases call it through the worker role
+ * (`WorkerRole.stopSchedules`, awaited in the runs phase, before the extension host closes: jobs may
+ * call extensions); `beforeApplicationShutdown` covers an application without them.
+ */
+export declare class ScheduledRuns implements ScheduledRunScope, OnModuleInit, BeforeApplicationShutdown {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly crons;
+    private readonly intervals;
+    private readonly shutdown;
+    private readonly log;
+    private readonly abort;
+    private readonly inFlight;
+    private stopping;
+    private gateOpen;
+    /** Each locked job's body by job name, bound to its instance (for {@link runNow}). */
+    private readonly bodies;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, crons: SchedulerRegistry, intervals: LockedIntervalScheduler, shutdown: GracefulShutdown, log: KernelLogger);
+    /**
+     * Attaches itself to every instance with a locked job in `onModuleInit`, which runs before any
+     * `onApplicationBootstrap` hook, so the start gate already guards the jobs when the cron
+     * orchestrator and the interval scheduler arm their timers there.
+     */
+    onModuleInit(): void;
+    /**
+     * Runs the body of the locked job named `name` once, now, outside its schedule: no tick marker
+     * and no run lock, in a fresh async context (no transaction), with the stop signal. A job's name
+     * enqueued on the maintenance queue runs this way, as the maintenance handlers of the periodic
+     * jobs did before they became locked jobs. Resolves false when no job has that name; the body's
+     * error is thrown.
+     */
+    runNow(name: string): Promise<boolean>;
+    /** The start gate is open: ticks and start runs may run. */
+    get opened(): boolean;
+    /**
+     * Opens the start gate. Until this is called every tick and start run skips at INFO: the
+     * cron and interval timers are armed at application bootstrap, which runs before the kernel's
+     * start sequence (migrations, bootstrap, extension load). The kernel's worker role opens it once
+     * its queue consumers started (then starts the `runOnStart` runs); a stop closes it again.
+     */
+    open(): void;
+    get stopped(): boolean;
+    get signal(): AbortSignal;
+    /** The number of runs in progress. */
+    get inFlightCount(): number;
+    track<T>(p: Promise<T>): Promise<T>;
+    /**
+     * Stops the schedulers and waits for the runs in progress, at most `budgetMs` (capped by the
+     * shared stop deadline). Idempotent: later calls return the first call's promise.
+     */
+    stop(budgetMs: number): Promise<void>;
+    beforeApplicationShutdown(): Promise<void>;
+    private runStop;
+}