@ferricstore/ferricstore 0.5.2 → 0.11.4

package/README.md

@@ -18,10 +18,10 @@ Requires Node.js 22.22 or newer. The SDK ships ESM and CommonJS builds and is te
 
 ## Compatibility
 
-SDK `0.5.x` requires FerricStore server `0.11.0` or newer and is tested against
-FerricStore `0.11.3`. FerricStore 0.11 is a breaking beta API contract update,
-while the native wire protocol remains v1 (`FSNP` framing and existing opcode
-numbers are unchanged). Capabilities and response-size limits are negotiated
+TypeScript SDK `0.11.4` requires FerricStore server `0.11.4` or newer because
+schedule responses now use the complete recurrence contract. The native wire
+protocol remains v1 (`FSNP` framing and existing opcode numbers are unchanged).
+Capabilities and response-size limits are negotiated
 per connection from the HELLO-shaped startup response rather than inferred from
 a server version table.
 
@@ -43,7 +43,7 @@ const { FerricStoreClient, JsonCodec } = require("@ferricstore/ferricstore");
 docker run -p 6388:6388 \
   -e FERRICSTORE_PROTECTED_MODE=false \
   -v ferricstore_data:/data \
-  ghcr.io/ferricstore/ferricstore:0.11.3
+  ghcr.io/ferricstore/ferricstore:0.11.4
 ```
 
 ## Query durable runs
@@ -428,6 +428,45 @@ await flow.scheduleCreate("orders-every-five-minutes", {
 });
 ```
 
+Overdue interval schedules use bounded `fire_once` catch-up. Recovery creates
+one target, coalesces additional elapsed periods in constant time, and sets the
+next run one full interval after recovery:
+
+```ts
+const schedule = await flow.scheduleCreate("billing-sweep", {
+  catchupPolicy: "fire_once",
+  everyMs: 60_000,
+  kind: "interval",
+  overlapPolicy: "queue_after_previous",
+  target: { id_prefix: "billing-sweep", type: "billing" }
+});
+```
+
+`ScheduleRecord` exposes the complete recurrence configuration through
+`created_at_ms`, `every_ms`, `cron`, `timezone`, `overlap_policy`, and
+`overlap_retry_ms`, in addition to `catchup_policy`, `coalesced_count`,
+`last_coalesced_count`, `last_catchup_at_ms`, and `last_planning_error`, using
+the server's canonical field names. Non-applicable recurrence fields are
+`null`, not omitted. `scheduleFireDue()` returns
+`ScheduleFireDueResult`, including the
+batch `coalesced` total. Its `errors` entries correspond to claimed schedules;
+`claim_error` separately reports a failure to request a later wave after
+completed outcomes were preserved. Catch-up handles scheduler delay; overlap
+policy separately handles a previous target that is still active. `fire_once` is the
+default and only catch-up policy for intervals; other schedule kinds reject it.
+The built-in server scheduler normally owns due execution. Call
+`scheduleFireDue()` only for tests, administration, or a deployment that
+deliberately disables the built-in runner and supplies a custom one.
+
+Recurring targets reject a fixed `id`. Set `id_prefix` to choose their
+generated prefix, or omit it to use the schedule ID. `ScheduleState` includes
+the transient `"running"` state used while the server holds a due-execution
+lease. Bounded catch-up is interval-only; overdue cron schedules advance one
+matching occurrence per successful automatic fire.
+When planning fails, `state` is `"failed"`, `end_reason` is
+`"planning_failed"`, and `last_planning_error` contains the actionable error.
+`scheduleDelete()` resolves to `undefined` only after an `OK` server reply.
+
 FIFO Flow state policy is opt-in per state:
 
 ```ts