@ap3x/cadence 0.1.0 → 0.2.0

package/README.md

@@ -1,22 +1,53 @@
 # @ap3x/cadence
 
-A standalone durable scheduler: cron, interval, and one-shot jobs with exactly-once firing semantics and pluggable storage.
+A standalone scheduler for cron, interval and one-shot jobs, with pluggable storage and retry policies. The bundled file store persists schedules and attempts for a single engine process; it does not guarantee exactly-once external effects.
 
 Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
 
-## Install
+## Run from source
 
-```bash
-npm install @ap3x/cadence
-```
+Follow the repository's [source quick start](../../README.md#quick-start-from-source) to install
+locked dependencies and build all workspaces, including cadence. That local install/build/help
+path has been exercised; published-artifact installation qualification remains open.
 
 ## 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.
+- **Occurrence claims** — bundled stores use in-memory claim markers to exclude competing
+  claims within one process. Schedule advancement is distinct from attempt persistence and execution.
+- **File-backed state and retries** — the file store reloads persisted schedules and attempts;
+  stale running attempts are reclaimed and routed through the retry policy. The memory store
+  does not survive process restart.
+- **Overlap + misfire policies** — choose what happens when an occurrence comes due while the
+  previous attempt is still running (`allow`, `queue`, `skip_if_running`), and what to do with
+  occurrences missed while the engine was down.
+- **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.
 
+## Concurrency scope
+
+The bundled stores hold their claim in process memory and rely on JavaScript's run-to-completion
+as the critical section. **Run one engine process per store directory** — multi-process exclusion
+is out of scope for the in-memory and file stores.
+
+The `Store` interface specifies claim/advance consistency requirements for alternative adapters.
+No PostgreSQL adapter ships here, and satisfying those methods alone would not make an external
+action part of the same transaction.
+
+## Crash and effect semantics
+
+A crash after claiming but before persisted slot advancement releases the transient claim, so
+the occurrence may be claimed again after restart. The engine advances a slot before opening
+its execution attempt: a crash in that window can leave an advanced schedule without an attempt
+record for recovery. Persisted running attempts can be retried, including when an external effect
+completed but its successful result was not recorded. Those retries may repeat the effect.
+
+Consumers must handle effect idempotency and reconciliation separately. Current stores and
+engine behavior do not establish loss-free delivery across every crash point, multi-process
+recovery, or exactly-once remote actions. See the [durability architecture](../../docs/architecture/durability.md)
+for the current boundary and proposed qualification work.
+
 Depends on no other `@ap3x` package.
 
 ## Documentation

package/dist/core/attempt-identity.d.ts

@@ -0,0 +1,4 @@
+import type { Attempt } from "./types";
+/** Keep updates bound to the same durable execution identity. */
+export declare function assertAttemptIdentity(a: Attempt, patch: Partial<Attempt>): void;
+//# sourceMappingURL=attempt-identity.d.ts.map

package/dist/core/attempt-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-identity.d.ts","sourceRoot":"","sources":["../../src/core/attempt-identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAM/E"}

package/dist/core/engine.d.ts

@@ -16,7 +16,7 @@ export interface EngineOptions {
     retryBaseMs?: number;
     /** Retry backoff ladder cap. Default 60s. */
     retryCapMs?: number;
-    /** Id source for schedules and attempts. Default: per-engine counter. */
+    /** Restart-safe id source for schedules and attempts. Default: randomUUID. */
     idFactory?: () => string;
 }
 export declare class Engine {

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

@@ -1 +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"}
+{"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,8EAA8E;IAC9E,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;CA2V5B"}

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

@@ -13,7 +13,7 @@
  * 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 ClaimedOccurrence, type Store } from "./store";
 import type { Attempt, Schedule } from "./types";
 export declare class InMemoryStore implements Store {
     #private;

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

@@ -1 +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"}
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/core/memory-store.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,KAAK,EAAc,MAAM,SAAS,CAAC;AACzE,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;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;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;IAOtC,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/core/store.d.ts

@@ -8,8 +8,14 @@ import type { Attempt, Schedule } from "./types";
 export interface ClaimedOccurrence {
     schedule: Schedule;
     occurrenceAt: string;
+    claimToken?: string;
 }
 export interface Store {
+    transaction?<T>(call: () => Promise<T>): Promise<T>;
+    afterCommit?(effect: () => void | Promise<void>): void;
+    claimAttempt?(id: string, now: Date): Promise<Attempt | undefined>;
+    renewAttempt?(id: string, claimToken: string): Promise<void>;
+    /** Create only; an existing id raises StoreError(conflict). */
     createSchedule(s: Schedule): Promise<void>;
     getSchedule(id: string): Promise<Schedule | undefined>;
     listSchedules(): Promise<Schedule[]>;
@@ -30,9 +36,11 @@ export interface Store {
      * 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>;
+    advanceSlot(id: string, nextRunAt: string | null, lastTriggeredAt: string, occurrenceCount: number, claimToken?: string): Promise<void>;
+    /** Create only; an existing id raises StoreError(conflict). */
     openAttempt(a: Attempt): Promise<void>;
-    updateAttempt(id: string, patch: Partial<Attempt>): Promise<void>;
+    /** Identity (id, scheduleId, occurrenceAt) is immutable. */
+    updateAttempt(id: string, patch: Partial<Attempt>, claimToken?: string): 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". */

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

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

package/dist/core/types.d.ts

@@ -56,6 +56,8 @@ export declare const ScheduleSchema: import("@sinclair/typebox").TObject<{
     metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
 }>;
 export interface Attempt {
+    claimToken?: string;
+    leaseUntil?: string;
     id: string;
     scheduleId: string;
     occurrenceAt: string;
@@ -68,6 +70,8 @@ export interface Attempt {
     outcome?: unknown;
 }
 export declare const AttemptSchema: import("@sinclair/typebox").TObject<{
+    claimToken: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    leaseUntil: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     id: import("@sinclair/typebox").TString;
     scheduleId: import("@sinclair/typebox").TString;
     occurrenceAt: import("@sinclair/typebox").TString;

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

@@ -1 +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"}
+{"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,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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;;;;;;;;;;;;;EAaxB,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.map

@@ -1 +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"}
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"AAwCA,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;;gBAUzB,GAAG,EAAE,MAAM;IAmEjB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C,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;IAQtC,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,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.js

@@ -83,6 +83,7 @@ var TestClock = class {
 };
 
 // src/core/engine.ts
+import { randomUUID } from "crypto";
 import { Value } from "@sinclair/typebox/value";
 
 // src/core/next-run.ts
@@ -245,6 +246,8 @@ var ScheduleSchema = Type.Object({
   metadata: Type.Optional(MetadataSchema)
 });
 var AttemptSchema = Type.Object({
+  claimToken: Type.Optional(Type.String()),
+  leaseUntil: Type.Optional(Type.String()),
   id: Type.String(),
   scheduleId: Type.String(),
   occurrenceAt: Type.String(),
@@ -301,7 +304,7 @@ var Engine = class {
     this.#orphanGraceMs = opts.orphanGraceMs ?? 3e5;
     this.#retryBaseMs = opts.retryBaseMs ?? 1e3;
     this.#retryCapMs = opts.retryCapMs ?? 6e4;
-    this.#idFactory = opts.idFactory ?? defaultIdFactory();
+    this.#idFactory = opts.idFactory ?? randomUUID;
   }
   // -- registration & passthroughs ----------------------------------------
   /**
@@ -386,8 +389,11 @@ var Engine = class {
     const now = this.#clock.now();
     await this.#recoverOrphans(now);
     await this.#runDueRetries(now);
-    const claimed = await this.#store.claimDue(now, this.#batchLimit);
-    for (const c of claimed) await this.#dispatch(c, now);
+    const claimAndPlan = async () => {
+      const claimed = await this.#store.claimDue(now, this.#batchLimit);
+      for (const c of claimed) await this.#dispatch(c, now);
+    };
+    await (this.#store.transaction?.(claimAndPlan) ?? claimAndPlan());
   }
   /** Crashed-worker recovery: route stale "running" attempts to the retry ladder. */
   async #recoverOrphans(now) {
@@ -395,18 +401,26 @@ var Engine = class {
     for (const a of orphans) {
       if (this.#inflightAttemptIds.has(a.id)) continue;
       const s = await this.#store.getSchedule(a.scheduleId);
-      if (s !== void 0 && a.attempt < s.maxAttempts) {
-        await this.#store.updateAttempt(a.id, {
-          status: "pending",
-          retryAt: this.#retryAt(s, a.occurrenceAt, now, a.attempt),
-          error: "orphaned: worker crashed or stalled"
-        });
+      if (!a.error?.startsWith("uncertain:") && s !== void 0 && a.attempt < s.maxAttempts) {
+        await this.#store.updateAttempt(
+          a.id,
+          {
+            status: "pending",
+            retryAt: this.#retryAt(s, a.occurrenceAt, now, a.attempt),
+            error: a.error ?? "orphaned: worker crashed or stalled"
+          },
+          a.claimToken
+        );
       } else {
-        await this.#store.updateAttempt(a.id, {
-          status: "dead_letter",
-          finishedAt: now.toISOString(),
-          error: "orphaned: worker crashed or stalled"
-        });
+        await this.#store.updateAttempt(
+          a.id,
+          {
+            status: "dead_letter",
+            finishedAt: now.toISOString(),
+            error: a.error ?? "orphaned: worker crashed or stalled"
+          },
+          a.claimToken
+        );
       }
     }
   }
@@ -423,13 +437,21 @@ var Engine = class {
         });
         continue;
       }
-      const attemptNo = a.attempt + 1;
-      await this.#store.updateAttempt(a.id, {
-        status: "running",
-        attempt: attemptNo,
-        startedAt: now.toISOString()
-      });
-      this.#track(this.#execute(s, a.id, a.occurrenceAt, attemptNo));
+      if (this.#store.claimAttempt) {
+        const owned = await this.#store.claimAttempt(a.id, now);
+        if (owned)
+          this.#track(
+            this.#execute(s, owned.id, owned.occurrenceAt, owned.attempt, owned.claimToken)
+          );
+      } else {
+        const attemptNo = a.attempt + 1;
+        await this.#store.updateAttempt(a.id, {
+          status: "running",
+          attempt: attemptNo,
+          startedAt: now.toISOString()
+        });
+        this.#track(this.#execute(s, a.id, a.occurrenceAt, attemptNo));
+      }
     }
   }
   /** Apply misfire + overlap policies to one claimed occurrence, advance its slot. */
@@ -460,7 +482,8 @@ var Engine = class {
         s.id,
         c.occurrenceAt,
         s.lastTriggeredAt ?? s.createdAt,
-        s.occurrenceCount
+        s.occurrenceCount,
+        c.claimToken
       );
       return;
     }
@@ -477,7 +500,7 @@ var Engine = class {
     }
     const nextRunAt = this.#boundedNext(s, anchor, countAfter);
     const lastTriggeredAt = firedCount > 0 ? now.toISOString() : s.lastTriggeredAt ?? s.createdAt;
-    await this.#store.advanceSlot(s.id, nextRunAt, lastTriggeredAt, countAfter);
+    await this.#store.advanceSlot(s.id, nextRunAt, lastTriggeredAt, countAfter, c.claimToken);
     if (skipped) {
       await this.#store.openAttempt({
         id: this.#idFactory(),
@@ -491,9 +514,36 @@ var Engine = class {
       return;
     }
     if (toFire.length === 0) return;
-    this.#track(this.#fire(s, toFire));
+    if (this.#store.transaction && this.#store.claimAttempt) {
+      const planned = [];
+      for (const occurrenceAt of toFire) {
+        const id = this.#idFactory();
+        const delay = s.jitterMs ? applyJitter(0, s.jitterMs, hashSeed(`${s.id}@${occurrenceAt}`)) : 0;
+        const readyAt = now.getTime() + delay;
+        planned.push({ id, readyAt });
+        await this.#store.openAttempt({
+          id,
+          scheduleId: s.id,
+          occurrenceAt,
+          attempt: 0,
+          status: "pending",
+          retryAt: new Date(readyAt).toISOString()
+        });
+      }
+      this.#store.afterCommit?.(() => {
+        this.#track(this.#firePrepared(s, planned));
+      });
+    } else this.#track(this.#fire(s, toFire));
   }
   // -- execution -----------------------------------------------------------
+  async #firePrepared(s, ids) {
+    for (const { id, readyAt } of ids) {
+      const delay = readyAt - this.#clock.now().getTime();
+      if (delay > 0) await this.#clock.sleep(delay, this.#loopCtl?.signal);
+      const owned = await this.#store.claimAttempt?.(id, this.#clock.now());
+      if (owned) await this.#execute(s, id, owned.occurrenceAt, owned.attempt, owned.claimToken);
+    }
+  }
   /** Fire the given occurrences of one schedule, in order, honoring jitter. */
   async #fire(s, occurrences) {
     for (const occurrenceAt of occurrences) {
@@ -515,10 +565,17 @@ var Engine = class {
     }
   }
   /** One attempt: executor call under a timeout signal, then the retry ladder. */
-  async #execute(s, attemptId, occurrenceAt, attemptNo) {
+  async #execute(s, attemptId, occurrenceAt, attemptNo, claimToken) {
     this.#inflightAttemptIds.add(attemptId);
     const ac = new AbortController();
     const timeoutCtl = new AbortController();
+    const renewal = claimToken && this.#store.renewAttempt ? (async () => {
+      while (!timeoutCtl.signal.aborted) {
+        await this.#clock.sleep(1e4, timeoutCtl.signal);
+        if (!timeoutCtl.signal.aborted)
+          await this.#store.renewAttempt?.(attemptId, claimToken);
+      }
+    })().catch(() => ac.abort()) : Promise.resolve();
     if (s.maxRuntimeMs !== void 0 && s.maxRuntimeMs > 0) {
       void this.#clock.sleep(s.maxRuntimeMs, timeoutCtl.signal).then(() => {
         if (!timeoutCtl.signal.aborted) ac.abort();
@@ -536,27 +593,40 @@ var Engine = class {
       outcome = { ok: false, error: err instanceof Error ? err.message : String(err) };
     } finally {
       timeoutCtl.abort();
+      await renewal;
       this.#inflightAttemptIds.delete(attemptId);
     }
     const now = this.#clock.now();
     if (outcome.ok) {
-      await this.#store.updateAttempt(attemptId, {
-        status: "succeeded",
-        finishedAt: now.toISOString(),
-        ...outcome.result !== void 0 ? { outcome: outcome.result } : {}
-      });
+      await this.#store.updateAttempt(
+        attemptId,
+        {
+          status: "succeeded",
+          finishedAt: now.toISOString(),
+          ...outcome.result !== void 0 ? { outcome: outcome.result } : {}
+        },
+        claimToken
+      );
     } else if (attemptNo < s.maxAttempts) {
-      await this.#store.updateAttempt(attemptId, {
-        status: "pending",
-        retryAt: this.#retryAt(s, occurrenceAt, now, attemptNo),
-        ...outcome.error !== void 0 ? { error: outcome.error } : {}
-      });
+      await this.#store.updateAttempt(
+        attemptId,
+        {
+          status: "pending",
+          retryAt: this.#retryAt(s, occurrenceAt, now, attemptNo),
+          ...outcome.error !== void 0 ? { error: outcome.error } : {}
+        },
+        claimToken
+      );
     } else {
-      await this.#store.updateAttempt(attemptId, {
-        status: "dead_letter",
-        finishedAt: now.toISOString(),
-        ...outcome.error !== void 0 ? { error: outcome.error } : {}
-      });
+      await this.#store.updateAttempt(
+        attemptId,
+        {
+          status: "dead_letter",
+          finishedAt: now.toISOString(),
+          ...outcome.error !== void 0 ? { error: outcome.error } : {}
+        },
+        claimToken
+      );
     }
   }
   // -- helpers ---------------------------------------------------------------
@@ -592,10 +662,6 @@ var Engine = class {
     void wrapped.finally(() => this.#inflight.delete(wrapped));
   }
 };
-function defaultIdFactory() {
-  let n = 0;
-  return () => `cad_${++n}`;
-}
 function hashSeed(input) {
   let h = 5381;
   for (let i = 0; i < input.length; i++) {
@@ -604,6 +670,25 @@ function hashSeed(input) {
   return h;
 }
 
+// src/core/store.ts
+var StoreError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "StoreError";
+    this.code = code;
+  }
+};
+
+// src/core/attempt-identity.ts
+function assertAttemptIdentity(a, patch) {
+  for (const key of ["id", "scheduleId", "occurrenceAt"]) {
+    if (Object.hasOwn(patch, key) && patch[key] !== a[key]) {
+      throw new StoreError("conflict", `attempt ${key} is immutable`);
+    }
+  }
+}
+
 // src/core/memory-store.ts
 var InMemoryStore = class {
   #clock;
@@ -616,6 +701,7 @@ var InMemoryStore = class {
     this.#clock = clock;
   }
   async createSchedule(s) {
+    if (this.#schedules.has(s.id)) throw new StoreError("conflict", "duplicate schedule id");
     this.#schedules.set(s.id, { ...s });
   }
   async getSchedule(id) {
@@ -656,11 +742,17 @@ var InMemoryStore = class {
     this.#claimed.delete(id);
   }
   async openAttempt(a) {
+    if (this.#attempts.some((existing) => existing.id === a.id)) {
+      throw new StoreError("conflict", "duplicate attempt id");
+    }
     this.#attempts.push({ ...a });
   }
   async updateAttempt(id, patch) {
     const a = this.#attempts.find((x) => x.id === id);
-    if (a) Object.assign(a, patch);
+    if (a) {
+      assertAttemptIdentity(a, patch);
+      Object.assign(a, patch);
+    }
   }
   async listDueRetries(now, limit) {
     const nowMs = now.getTime();
@@ -686,16 +778,6 @@ var InMemoryStore = class {
   }
 };
 
-// src/core/store.ts
-var StoreError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "StoreError";
-    this.code = code;
-  }
-};
-
 // src/file-store.ts
 import {
   closeSync,
@@ -720,6 +802,7 @@ var FileStore = class {
   #attempts = [];
   /** Schedule ids whose due slot is claimed pending `advanceSlot`. Transient by design. */
   #claimed = /* @__PURE__ */ new Set();
+  #persistedJson;
   constructor(dir) {
     mkdirSync(dir, { recursive: true });
     this.#statePath = join(dir, STATE_FILE);
@@ -744,14 +827,22 @@ var FileStore = class {
       if (!Value2.Check(ScheduleSchema, s)) {
         throw new StoreError("corrupt", `${this.#statePath}: invalid schedule record`);
       }
+      if (this.#schedules.has(s.id)) throw new StoreError("corrupt", "duplicate schedule id");
       this.#schedules.set(s.id, s);
     }
     for (const a of state.attempts) {
       if (!Value2.Check(AttemptSchema, a)) {
         throw new StoreError("corrupt", `${this.#statePath}: invalid attempt record`);
       }
+      if (this.#attempts.some((existing) => existing.id === a.id)) {
+        throw new StoreError("corrupt", "duplicate attempt id");
+      }
       this.#attempts.push(a);
     }
+    this.#persistedJson = JSON.stringify({
+      schedules: [...this.#schedules.values()],
+      attempts: this.#attempts
+    });
   }
   /** Atomically rewrite the full state: temp file + fsync + rename. */
   #persist() {
@@ -759,6 +850,7 @@ var FileStore = class {
       schedules: [...this.#schedules.values()],
       attempts: this.#attempts
     });
+    if (json === this.#persistedJson) return;
     const fd = openSync(this.#tempPath, "w");
     try {
       writeSync(fd, json);
@@ -767,8 +859,10 @@ var FileStore = class {
       closeSync(fd);
     }
     renameSync(this.#tempPath, this.#statePath);
+    this.#persistedJson = json;
   }
   async createSchedule(s) {
+    if (this.#schedules.has(s.id)) throw new StoreError("conflict", "duplicate schedule id");
     this.#schedules.set(s.id, { ...s });
     this.#persist();
   }
@@ -816,12 +910,16 @@ var FileStore = class {
     this.#claimed.delete(id);
   }
   async openAttempt(a) {
+    if (this.#attempts.some((existing) => existing.id === a.id)) {
+      throw new StoreError("conflict", "duplicate attempt id");
+    }
     this.#attempts.push({ ...a });
     this.#persist();
   }
   async updateAttempt(id, patch) {
     const a = this.#attempts.find((x) => x.id === id);
     if (a) {
+      assertAttemptIdentity(a, patch);
       Object.assign(a, patch);
       this.#persist();
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ap3x/cadence",
-  "version": "0.1.0",
-  "description": "Durable scheduler — cron, interval, and one-shot jobs with exactly-once firing",
+  "version": "0.2.0",
+  "description": "Durable scheduler — cron, interval, and one-shot jobs with exactly-once slot advance",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AP3X-Dev/AP3X.git",