@adonis-agora/durable 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @adonis-agora/durable
 
+## 0.43.0
+
+### Minor Changes
+
+- [#222](https://github.com/DavideCarvalho/adonis-agora-durable/pull/222) [`9540e66`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/9540e66f942c3bbae6440ca6657909ffd6cc3734) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **Persisted schedules** — port of nestjs-durable#338. Temporal-style schedules managed at runtime and stored next to the runs, alongside the code-declared `schedules` config / `static schedule`.
+  
+  - `engine.schedules`: `create` / `upsert` / `get` / `list` / `pause(note?)` / `resume` / `trigger` / `delete` / `tick`. A schedule starts `workflow` with `input` on a `cron` (+ IANA `timezone`) or a fixed `every` interval, with a stable per-window `jitter`, `overlap` (`allow` / `skip` while the previous run is in flight), `catchup` (`latest` missed window once, or `skip`), `tags` (also stamped on its runs, plus `schedule:<id>`), `searchAttributes`, `priority` and `namespace`. Failed starts are recorded as `lastError`; `get`/`list` report next/last fire, last run and fire count.
+  - **Multi-worker safe without locks**: a window's run id is deterministic (`sched:<id>:<windowMs>`) and advancing a schedule is a compare-and-set on its `next_fire_at`.
+  - `persistedSchedules: true` in `config/durable.ts` makes the worker tick (`durable:work` / the embedded worker) fire due schedules — off by default.
+  - New `durable_schedules` table, created by `createDurableTables` (auto-schema on boot; with `autoSchema: false`, add a migration that calls `createDurableTables` again — it only creates what's missing), and five optional `StateStore` methods (`saveSchedule`, `getSchedule`, `updateSchedule` with CAS, `deleteSchedule`, `listSchedules`) implemented by the Lucid and in-memory stores; `CodecStateStore` forwards them, encoding the schedule input. Covered by the shared contract.
+
+- [#226](https://github.com/DavideCarvalho/adonis-agora-durable/pull/226) [`edab227`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/edab227f547e2804688ec7b8596c085a71240393) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - A persisted schedule can carry a **concurrency quota** (port of nestjs-durable#340): `engine.schedules.create/upsert({ …, concurrency: { key, limit, countStatuses? } })` applies it to every run the schedule starts, like `StartOptions.concurrency`. An over-limit window is skipped and recorded as the schedule's `lastError`; the schedule moves on to its next window.
+
+## 0.42.0
+
+### Minor Changes
+
+- [#221](https://github.com/DavideCarvalho/adonis-agora-durable/pull/221) [`448b3b1`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/448b3b129c0f586b19b35036cf76a4e3982d7a60) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - New `DynamicWorkflowCtx` type — port of nestjs-durable#337: `WorkflowCtx` with ONE string-addressed signature for each of its overloaded methods (`step`, `child`, `startChild`, `all`). Every `WorkflowCtx` is assignable to it, so code that drives the ctx by names (a graph interpreter) and test fakes can depend on it — or on a `Pick` of it — instead of re-declaring a narrow interface and casting `ctx as unknown as …`. A type-test pins the assignability.
+
+- [#219](https://github.com/DavideCarvalho/adonis-agora-durable/pull/219) [`614ca9b`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/614ca9bd259e48710738a88f73dc227d4f9844c2) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Retention can be **scoped**, and a tenant's runs can be **purged** through the engine — port of nestjs-durable#335.
+  
+  - **`retention.policies`** (engine: `retentionPolicies`): scoped rules next to the per-status ages — each deletes terminal runs in its `statuses` that match its `scope` (`namespace(s)`, `workflow(s)`, `tag`/`tags`, search-attribute `attributes` — the new `RunScope` type) once their last activity is older than `maxAge`. Swept by the same throttled `sweepRetention`, with the same `onEvict` archival hooks and subtree cascade. A namespaced worker never sweeps another partition's scope.
+  - **`engine.purgeRuns(scope, { batchSize?, cancelLive?, children? })` / `engine.purgeNamespace(ns)`**: hard-delete every run a scope matches with its child subtree (children inherit `namespace`, not `tags` — they go with their root either way), in bounded batches, sweeping their buffered signals. Live runs are cancelled first (`cancelLive: false` keeps them). An empty scope is rejected.
+  - New exports: `RunScope`, `isNonEmptyRunScope`, `TERMINAL_RUN_STATUSES`, `TerminalRunStatus`, `ScopedRetentionPolicy`.
+
+- [#220](https://github.com/DavideCarvalho/adonis-agora-durable/pull/220) [`0d19781`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/0d1978138af2bb5f7348b49dd618fad77aa4c200) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **Start-time concurrency quotas** — port of nestjs-durable#336. Cap how many runs sharing a key can be in flight and reject the start that would exceed it ("a tenant can have at most 8 turns executing"), without a hand-rolled count gate.
+  
+  - `static workflow = { concurrency: { key: (input) => …, limit, countStatuses? } }` (also `engine.register` / `registerRemote`), or per start with `StartOptions.concurrency: { key, limit, countStatuses? }` (overrides the workflow's). The key is global, so several workflows can share one quota; `limit` may be an async function of the key; `countStatuses` narrows what occupies a slot (default: every non-terminal status).
+  - Over the limit `start` throws **`ConcurrencyLimitError`** (`key`, `limit`, `active`, `workflow`) and creates nothing; an idempotent re-start of an existing run id is never rejected. Quota-bearing runs carry the engine-minted tag `concurrency:<key>`.
+  - New optional `StateStore.countRuns(query)` — one `COUNT(*)` over the `listRuns` predicates — implemented by the Lucid and in-memory stores and `CodecStateStore`, and covered by the shared contract. The engine falls back to counting a listing for a custom store.
+  
+  A soft cap under a race (count and insert are separate statements); use `singleton` for a strict, queueing per-key limit.
+
+## 0.41.1
+
+### Patch Changes
+
+- [#202](https://github.com/DavideCarvalho/adonis-agora-durable/pull/202) [`573a198`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/573a198ae5e1e69503f3a37d3b9817da07b038c4) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - A run is no longer counted, dead-lettered or executed twice when its turn settles while the orphan sweep is looking at it.
+  
+  Port of the same race fixed in the NestJS core (nestjs-durable#331), seen there as intermittently hung durable chat turns where an in-process worker answers a dispatched step in a couple of milliseconds:
+  
+  - **A turn releases its lease only after its settled state is written.** `runExecution` returned `this.settleRun(...)` (and `this.parkBlocked(...)`) without awaiting it inside `try … finally { releaseRunLock }`, so the `finally` ran first: a first turn that completed, failed or parked `blocked` sat unlocked while its row still read `running`, which is what `listOrphanedRuns` returns for a crashed turn. Every settle in that block is now `return await`ed. (The suspend settle was already awaited.)
+  - **`recoverIncomplete` decides on the run it locked, not the one it listed.** It trusted the listed `running` status: a run that settled between the listing and `tryLockRun` got a recovery attempt counted and, past `maxRecoveryAttempts`, an unconditional `dead` written over a completed or suspended run. It now re-reads the run under the lease and releases it again unless it still reads `running`. The dead-letter write is also conditional on `running`, so a lease-free `cancel()` landing after that re-read is not overwritten with `dead`.
+  - **A replay re-reads a `pending` remote step before acting on it.** With `remoteRedispatchMs` set, a replay that found its step pending in its start-of-execution snapshot stamped the lease by writing `{ ...snapshot, wakeAt }` back, overwriting a result that had landed since with `pending` and parking the run on a lease an hour out. The step is now re-read from the store first; a result that has landed is replayed instead.
+
 ## 0.41.0
 
 ### Minor Changes