@ap3x/cadence 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+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,28 @@
+# @ap3x/cadence
+
+A standalone durable scheduler: cron, interval, and one-shot jobs with exactly-once firing semantics and pluggable storage.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/cadence
+```
+
+## What's inside
+
+- **Schedules** — cron expressions, fixed intervals, and one-shot timers.
+- **Exactly-once** — an occurrence fires once, even across restarts and concurrent workers.
+- **Pluggable stores** — in-memory and file-backed stores ship with the package, behind a store interface with a conformance suite.
+- **Injectable clock** — no wall-clock reads in core, so schedules are testable deterministically.
+
+Depends on no other `@ap3x` package.
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/core/backoff.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure, deterministic retry-backoff helpers. No wall-clock reads and no
+ * `Math.random` — jitter comes from a deterministic integer hash of a seed the
+ * engine derives per-occurrence (e.g. from schedule id + occurrenceAt), so a
+ * given (ms, jitterMs, seed) always yields the same value. This keeps retry
+ * timing reproducible across restarts and testable under a TestClock.
+ */
+/**
+ * Exponential backoff: `baseMs * 2^(attempt-1)`, clamped to `capMs`. `attempt`
+ * is 1-based; values < 1 are treated as 1. Non-finite inputs are sanitized to
+ * keep the result a finite, non-negative number.
+ */
+export declare function backoffMs(attempt: number, baseMs: number, capMs: number): number;
+/**
+ * Deterministic jitter. Returns a value in `[ms, ms + jitterMs]` inclusive,
+ * derived from `seed` via a mulberry32-style integer hash (two xor-shift +
+ * `Math.imul` rounds), so the same `(ms, jitterMs, seed)` is stable. When
+ * `jitterMs <= 0` the input `ms` is returned unchanged.
+ */
+export declare function applyJitter(ms: number, jitterMs: number, seed: number): number;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/core/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/core/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAU9E"}

package/dist/core/clock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The `Clock` port: the only way cadence reads time or waits.
+ *
+ * Core code never touches the wall clock directly — a guard test bans argless
+ * wall-clock and RNG reads across all of `src/`. Time enters through an
+ * injected `Clock`, which keeps the engine deterministic under test.
+ *
+ * - `SystemClock` wraps the real clock, but takes `nowFn` as a REQUIRED
+ *   constructor argument so this file never contains a wall-clock literal. The
+ *   AP3X CLI boundary (outside `src/`) constructs it by injecting a wall-clock
+ *   factory. `sleep` is `setTimeout`-based.
+ * - `TestClock` does pure arithmetic on an injected start instant — no
+ *   wall-clock at all. `sleep` resolves only when `advance`/`setNow` push
+ *   `now()` past the sleep's absolute deadline, so time is fully driven by the
+ *   test.
+ *
+ * Abort semantics: `sleep(ms, signal)` RESOLVES (does not reject) when the
+ * signal aborts. The daemon tick loop passes its abort signal to `sleep`
+ * between ticks; resolving on abort lets the loop fall through and exit
+ * promptly rather than having to catch a rejection.
+ */
+export interface Clock {
+    now(): Date;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/** A real clock. `nowFn` is injected so this file holds no wall-clock literal. */
+export declare class SystemClock implements Clock {
+    #private;
+    constructor(nowFn: () => Date);
+    now(): Date;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * A deterministic clock whose time only moves via `advance`/`setNow`. Pending
+ * sleeps are tracked by absolute deadline and resolved, in deadline order, as
+ * soon as `now()` reaches them.
+ */
+export declare class TestClock implements Clock {
+    #private;
+    constructor(startIso: string);
+    now(): Date;
+    /** Move time forward by `ms`, resolving any sleeps whose deadline passed. */
+    advance(ms: number): void;
+    /** Jump to an absolute instant, resolving any sleeps whose deadline passed. */
+    setNow(iso: string): void;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=clock.d.ts.map

package/dist/core/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/core/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,IAAI,CAAC;IACZ,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,kFAAkF;AAClF,qBAAa,WAAY,YAAW,KAAK;;gBAG3B,KAAK,EAAE,MAAM,IAAI;IAI7B,GAAG,IAAI,IAAI;IAIX,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAcvD;AAOD;;;;GAIG;AACH,qBAAa,SAAU,YAAW,KAAK;;gBAIzB,QAAQ,EAAE,MAAM;IAI5B,GAAG,IAAI,IAAI;IAIX,6EAA6E;IAC7E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKzB,+EAA+E;IAC/E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAwBvD"}

package/dist/core/engine.d.ts

@@ -0,0 +1,46 @@
+import type { Clock } from "./clock";
+import type { Executor } from "./executor";
+import type { Store } from "./store";
+import { type Attempt, type NewSchedule, type Schedule } from "./types";
+export interface EngineOptions {
+    store: Store;
+    executor: Executor;
+    clock: Clock;
+    /** Poll-loop cadence. Default 1000ms. */
+    pollIntervalMs?: number;
+    /** Max occurrences claimed (and retries picked up) per tick. Default 25. */
+    batchLimit?: number;
+    /** Age past which a "running" attempt counts as a crashed worker. Default 5min. */
+    orphanGraceMs?: number;
+    /** Retry backoff ladder base. Default 1000ms. */
+    retryBaseMs?: number;
+    /** Retry backoff ladder cap. Default 60s. */
+    retryCapMs?: number;
+    /** Id source for schedules and attempts. Default: per-engine counter. */
+    idFactory?: () => string;
+}
+export declare class Engine {
+    #private;
+    constructor(opts: EngineOptions);
+    /**
+     * Validate (TypeBox shape + kind-specific expression check), fill server-side
+     * fields, compute the initial slot, and persist. Throws on invalid input.
+     */
+    register(input: NewSchedule): Promise<Schedule>;
+    remove(id: string): Promise<boolean>;
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+    get(id: string): Promise<Schedule | undefined>;
+    list(): Promise<Schedule[]>;
+    /** Attempt history for one schedule, newest first — "did it actually run?". */
+    listAttempts(scheduleId: string, limit?: number): Promise<Attempt[]>;
+    /** Occurrences that exhausted the retry ladder: the permanent-failure record. */
+    deadLetteredFor(scheduleId: string): Promise<Attempt[]>;
+    /** Begin the poll loop. Idempotent: a second start while running is a no-op. */
+    start(): void;
+    /**
+     * Drain: stop claiming, let in-flight attempts run to completion (bounded by
+     * their own maxRuntimeMs timeouts), then resolve. Idempotent.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAoB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,KAAK,EAAqB,KAAK,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAqB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE3F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,qBAAa,MAAM;;gBAmBL,IAAI,EAAE,aAAa;IAc/B;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IA6BrD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAI9C,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI3B,+EAA+E;IAC/E,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAIhE,iFAAiF;IACjF,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAMvD,gFAAgF;IAChF,KAAK,IAAI,IAAI;IAOb;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA+Q5B"}

package/dist/core/executor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The Executor port: what a schedule fire actually *does*. The engine owns the
+ * WHEN (due computation, exactly-once, retry, timeout); the Executor owns the
+ * WHAT. Concrete executors (e.g. an AgentBackend-backed one) live outside
+ * `src/core`, which keeps the core free of AP3X imports and extractable as a
+ * standalone package.
+ */
+import type { Schedule } from "./types";
+/** Everything an executor needs for a single attempt of one occurrence. */
+export interface ExecutionContext {
+    schedule: Schedule;
+    /** The occurrence instant this attempt belongs to (ISO-8601). */
+    occurrenceAt: string;
+    /** 1-based attempt number within the retry ladder. */
+    attempt: number;
+    /** Aborted by the engine on timeout, shutdown, or kill-switch. */
+    signal: AbortSignal;
+}
+/** The result of one execution attempt. */
+export interface ExecutionOutcome {
+    ok: boolean;
+    error?: string;
+    result?: unknown;
+}
+export interface Executor {
+    execute(ctx: ExecutionContext): Promise<ExecutionOutcome>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/core/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC3D"}

package/dist/core/memory-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * In-memory reference {@link Store}. Backs schedules and attempts with `Map`s.
+ *
+ * The atomic-claim contract is modeled by a single-writer, in-process critical
+ * section: JavaScript's run-to-completion means each `claimDue` call executes
+ * without interleaving, and claimed slots are stamped into a `#claimed` set so a
+ * second `claimDue` at the same instant (before `advanceSlot`) can never
+ * re-return the same occurrence. `advanceSlot` clears the claim as it persists
+ * the next slot. This is what makes firing exactly-once.
+ *
+ * ponytail: single global in-process claim. FileStore keeps the same in-process
+ * contract (one engine process per store directory — no lockfile); a true
+ * multi-process store (e.g. Postgres) would enforce it with a row lock.
+ */
+import type { Clock } from "./clock";
+import type { ClaimedOccurrence, Store } from "./store";
+import type { Attempt, Schedule } from "./types";
+export declare class InMemoryStore implements Store {
+    #private;
+    constructor(clock: Clock);
+    createSchedule(s: Schedule): Promise<void>;
+    getSchedule(id: string): Promise<Schedule | undefined>;
+    listSchedules(): Promise<Schedule[]>;
+    removeSchedule(id: string): Promise<boolean>;
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+    claimDue(now: Date, limit: number): Promise<ClaimedOccurrence[]>;
+    advanceSlot(id: string, nextRunAt: string | null, lastTriggeredAt: string, occurrenceCount: number): Promise<void>;
+    openAttempt(a: Attempt): Promise<void>;
+    updateAttempt(id: string, patch: Partial<Attempt>): Promise<void>;
+    listDueRetries(now: Date, limit: number): Promise<Attempt[]>;
+    hasActiveAttempt(scheduleId: string): Promise<boolean>;
+    reclaimOrphans(now: Date, graceMs: number): Promise<Attempt[]>;
+    listAttempts(scheduleId: string, limit: number): Promise<Attempt[]>;
+    deadLetteredFor(scheduleId: string): Promise<Attempt[]>;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/core/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/core/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,qBAAa,aAAc,YAAW,KAAK;;gBAQ7B,KAAK,EAAE,KAAK;IAIlB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAKtD,aAAa,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIpC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK5C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAchE,WAAW,CACf,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC;IAUV,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAa5D,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAY9D,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IASnE,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAK9D"}

package/dist/core/next-run.d.ts

@@ -0,0 +1,21 @@
+import type { NewSchedule, Schedule } from "./types";
+/**
+ * The next fire instant strictly AFTER `after`, or `null` if none exists
+ * (a malformed expression, a past one-shot, or an expired schedule).
+ */
+export declare function computeNextRun(s: Pick<Schedule, "kind" | "expr" | "timezone">, after: Date): Date | null;
+/**
+ * Validate a registration input: syntactically valid + reachable for its kind,
+ * and — when `opts.minCadenceMs` is set — not tighter than the anti-runaway floor.
+ *
+ * A past one-shot is NOT an error: it is a valid schedule that simply will not fire.
+ */
+export declare function validateSchedule(input: NewSchedule, opts?: {
+    minCadenceMs?: number;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=next-run.d.ts.map

package/dist/core/next-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-run.d.ts","sourceRoot":"","sources":["../../src/core/next-run.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKrD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC,EAC/C,KAAK,EAAE,IAAI,GACV,IAAI,GAAG,IAAI,CAwBb;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuD7C"}

package/dist/core/store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The durable-persistence port every cadence adapter implements
+ * (in-memory, file, Postgres, HTTP). The engine depends only on this
+ * interface, never on a concrete store.
+ */
+import type { Attempt, Schedule } from "./types";
+/** A schedule whose due slot has been claimed for firing, at a fixed instant. */
+export interface ClaimedOccurrence {
+    schedule: Schedule;
+    occurrenceAt: string;
+}
+export interface Store {
+    createSchedule(s: Schedule): Promise<void>;
+    getSchedule(id: string): Promise<Schedule | undefined>;
+    listSchedules(): Promise<Schedule[]>;
+    removeSchedule(id: string): Promise<boolean>;
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+    /**
+     * ATOMIC claim. Select due (`nextRunAt <= now`) AND enabled schedules and mark
+     * their slot claimed in one critical section, so no concurrent caller can take
+     * the same occurrence. Returns the claimed occurrences. This exclusivity is
+     * half of what makes firing exactly-once — {@link Store.advanceSlot} is the
+     * other half and MUST run in the same logical transaction/critical section.
+     */
+    claimDue(now: Date, limit: number): Promise<ClaimedOccurrence[]>;
+    /**
+     * Persist the next occurrence + lastTriggered + occurrenceCount in the SAME
+     * logical transaction/critical-section as the {@link Store.claimDue} that
+     * produced this slot. Committing the claim and the slot advance together is
+     * what guarantees each occurrence fires exactly once, even under concurrent
+     * or crashed workers.
+     */
+    advanceSlot(id: string, nextRunAt: string | null, lastTriggeredAt: string, occurrenceCount: number): Promise<void>;
+    openAttempt(a: Attempt): Promise<void>;
+    updateAttempt(id: string, patch: Partial<Attempt>): Promise<void>;
+    /** Attempts with status "pending" and `retryAt <= now`. */
+    listDueRetries(now: Date, limit: number): Promise<Attempt[]>;
+    /** Whether the schedule has any attempt currently in status "running". */
+    hasActiveAttempt(scheduleId: string): Promise<boolean>;
+    /** "running" attempts whose `startedAt` is older than `graceMs` (crashed workers). */
+    reclaimOrphans(now: Date, graceMs: number): Promise<Attempt[]>;
+    /** Attempt history for a schedule, newest-first (audit/history). */
+    listAttempts(scheduleId: string, limit: number): Promise<Attempt[]>;
+    /** Attempts with status "dead_letter" (for replay). */
+    deadLetteredFor(scheduleId: string): Promise<Attempt[]>;
+}
+/** Error raised by store adapters for the well-known failure modes. */
+export declare class StoreError extends Error {
+    readonly code: "not_found" | "conflict" | "locked" | "corrupt";
+    constructor(code: "not_found" | "conflict" | "locked" | "corrupt", message: string);
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/core/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/core/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IACvD,aAAa,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,WAAW,CACT,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE,2DAA2D;IAC3D,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7D,0EAA0E;IAC1E,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,sFAAsF;IACtF,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,oEAAoE;IACpE,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACpE,uDAAuD;IACvD,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzD;AAED,uEAAuE;AACvE,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;gBAEnD,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM;CAKnF"}

package/dist/core/types.d.ts

@@ -0,0 +1,116 @@
+/** The three schedule kinds cadence knows how to compute a next run for. */
+export declare const ScheduleKind: {
+    readonly Cron: "cron";
+    readonly Interval: "interval";
+    readonly OneShot: "one_shot";
+};
+export type ScheduleKind = (typeof ScheduleKind)[keyof typeof ScheduleKind];
+/** What to do when a new occurrence is due while a prior attempt still runs. */
+export type OverlapPolicy = "allow" | "skip_if_running" | "queue";
+/** What to do with occurrences missed while the engine was down. */
+export type MisfirePolicy = "fire" | "skip" | "backfill";
+/** Lifecycle state of a single execution attempt. */
+export type AttemptStatus = "running" | "succeeded" | "failed" | "pending" | "dead_letter";
+export interface Schedule {
+    id: string;
+    name?: string;
+    kind: ScheduleKind;
+    expr: string;
+    timezone: string;
+    payload: unknown;
+    enabled: boolean;
+    overlap: OverlapPolicy;
+    misfire: MisfirePolicy;
+    maxAttempts: number;
+    maxRuntimeMs?: number;
+    jitterMs?: number;
+    validFrom?: string;
+    validUntil?: string;
+    maxOccurrences?: number;
+    occurrenceCount: number;
+    nextRunAt: string | null;
+    lastTriggeredAt?: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+export declare const ScheduleSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"cron">, import("@sinclair/typebox").TLiteral<"interval">, import("@sinclair/typebox").TLiteral<"one_shot">]>;
+    expr: import("@sinclair/typebox").TString;
+    timezone: import("@sinclair/typebox").TString;
+    payload: import("@sinclair/typebox").TUnknown;
+    enabled: import("@sinclair/typebox").TBoolean;
+    overlap: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"allow">, import("@sinclair/typebox").TLiteral<"skip_if_running">, import("@sinclair/typebox").TLiteral<"queue">]>;
+    misfire: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"fire">, import("@sinclair/typebox").TLiteral<"skip">, import("@sinclair/typebox").TLiteral<"backfill">]>;
+    maxAttempts: import("@sinclair/typebox").TNumber;
+    maxRuntimeMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    jitterMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    validFrom: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    validUntil: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    maxOccurrences: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    occurrenceCount: import("@sinclair/typebox").TNumber;
+    nextRunAt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNull]>;
+    lastTriggeredAt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    createdAt: import("@sinclair/typebox").TString;
+    metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+}>;
+export interface Attempt {
+    id: string;
+    scheduleId: string;
+    occurrenceAt: string;
+    attempt: number;
+    status: AttemptStatus;
+    startedAt?: string;
+    finishedAt?: string;
+    retryAt?: string;
+    error?: string;
+    outcome?: unknown;
+}
+export declare const AttemptSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    scheduleId: import("@sinclair/typebox").TString;
+    occurrenceAt: import("@sinclair/typebox").TString;
+    attempt: import("@sinclair/typebox").TNumber;
+    status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"running">, import("@sinclair/typebox").TLiteral<"succeeded">, import("@sinclair/typebox").TLiteral<"failed">, import("@sinclair/typebox").TLiteral<"pending">, import("@sinclair/typebox").TLiteral<"dead_letter">]>;
+    startedAt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    finishedAt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    retryAt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    error: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    outcome: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+}>;
+export interface NewSchedule {
+    name?: string;
+    kind: ScheduleKind;
+    expr: string;
+    timezone?: string;
+    payload: unknown;
+    overlap?: OverlapPolicy;
+    misfire?: MisfirePolicy;
+    maxAttempts?: number;
+    maxRuntimeMs?: number;
+    jitterMs?: number;
+    validFrom?: string;
+    validUntil?: string;
+    maxOccurrences?: number;
+    enabled?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export declare const NewScheduleSchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"cron">, import("@sinclair/typebox").TLiteral<"interval">, import("@sinclair/typebox").TLiteral<"one_shot">]>;
+    expr: import("@sinclair/typebox").TString;
+    timezone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    payload: import("@sinclair/typebox").TUnknown;
+    overlap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"allow">, import("@sinclair/typebox").TLiteral<"skip_if_running">, import("@sinclair/typebox").TLiteral<"queue">]>>;
+    misfire: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"fire">, import("@sinclair/typebox").TLiteral<"skip">, import("@sinclair/typebox").TLiteral<"backfill">]>>;
+    maxAttempts: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    maxRuntimeMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    jitterMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    validFrom: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    validUntil: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    maxOccurrences: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    enabled: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAcA,4EAA4E;AAC5E,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,iBAAiB,GAAG,OAAO,CAAC;AAElE,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEzD,qDAAqD;AACrD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAmC3F,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;EAqBzB,CAAC;AAMH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;EAWxB,CAAC;AAMH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;EAgB5B,CAAC"}

package/dist/file-store.d.ts

@@ -0,0 +1,21 @@
+import { type ClaimedOccurrence, type Store } from "./core/store";
+import { type Attempt, type Schedule } from "./core/types";
+export declare class FileStore implements Store {
+    #private;
+    constructor(dir: string);
+    createSchedule(s: Schedule): Promise<void>;
+    getSchedule(id: string): Promise<Schedule | undefined>;
+    listSchedules(): Promise<Schedule[]>;
+    removeSchedule(id: string): Promise<boolean>;
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+    claimDue(now: Date, limit: number): Promise<ClaimedOccurrence[]>;
+    advanceSlot(id: string, nextRunAt: string | null, lastTriggeredAt: string, occurrenceCount: number): Promise<void>;
+    openAttempt(a: Attempt): Promise<void>;
+    updateAttempt(id: string, patch: Partial<Attempt>): Promise<void>;
+    listDueRetries(now: Date, limit: number): Promise<Attempt[]>;
+    hasActiveAttempt(scheduleId: string): Promise<boolean>;
+    reclaimOrphans(now: Date, graceMs: number): Promise<Attempt[]>;
+    listAttempts(scheduleId: string, limit: number): Promise<Attempt[]>;
+    deadLetteredFor(scheduleId: string): Promise<Attempt[]>;
+}
+//# sourceMappingURL=file-store.d.ts.map

package/dist/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,KAAK,EAAc,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,KAAK,OAAO,EAAiB,KAAK,QAAQ,EAAkB,MAAM,cAAc,CAAC;AAK1F,qBAAa,SAAU,YAAW,KAAK;;gBASzB,GAAG,EAAE,MAAM;IAyDjB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAKtD,aAAa,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIpC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO5C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvD,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAchE,WAAW,CACf,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC;IAWV,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjE,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAa5D,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAY9D,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IASnE,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAK9D"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./core/backoff";
+export * from "./core/clock";
+export * from "./core/engine";
+export * from "./core/executor";
+export * from "./core/memory-store";
+export * from "./core/next-run";
+export * from "./core/store";
+export * from "./core/types";
+export * from "./file-store";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}