@ap3x/cadence 0.1.0 → 0.1.1

package/README.md

@@ -13,10 +13,28 @@ 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.
+- **Exactly-once slot advance** — claiming a due occurrence and advancing its slot happen in one
+  critical section, so a given occurrence is never fired twice by the running engine. A crash
+  *between* the two releases the claim, and the occurrence fires again on restart — the design
+  prefers re-firing over silently dropping a scheduled run.
+- **Durable across restarts** — state reloads from the store; in-flight attempts abandoned by a
+  crashed process are reclaimed and routed through the retry ladder.
+- **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 is designed for it: a backend that can claim and advance in one transaction
+(a Postgres row lock, say) extends the same guarantee across processes. No such adapter ships here.
+
 Depends on no other `@ap3x` package.
 
 ## Documentation

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.1.1",
+  "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",