@camunda8/orchestration-cluster-api 10.0.0-alpha.41 → 10.0.0-alpha.43

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [10.0.0-alpha.43](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.42...v10.0.0-alpha.43) (2026-08-28)
+
+
+### Features
+
+* bind SDK cadence to the engine clock with createEngineClock ([#482](https://github.com/camunda/orchestration-cluster-api-js/issues/482)) ([8770212](https://github.com/camunda/orchestration-cluster-api-js/commit/8770212210097606b3400b8b98b6d2b452b1ff83)), closes [#450](https://github.com/camunda/orchestration-cluster-api-js/issues/450) [#450](https://github.com/camunda/orchestration-cluster-api-js/issues/450) [#467](https://github.com/camunda/orchestration-cluster-api-js/issues/467) [#474](https://github.com/camunda/orchestration-cluster-api-js/issues/474) [#476](https://github.com/camunda/orchestration-cluster-api-js/issues/476) [#477](https://github.com/camunda/orchestration-cluster-api-js/issues/477) [#479](https://github.com/camunda/orchestration-cluster-api-js/issues/479)
+
+# [10.0.0-alpha.42](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.41...v10.0.0-alpha.42) (2026-08-27)
+
+
+### Features
+
+* add createTestClock and a Clock contract conformance suite ([#479](https://github.com/camunda/orchestration-cluster-api-js/issues/479)) ([5beea42](https://github.com/camunda/orchestration-cluster-api-js/commit/5beea4241d27b01194960bda3555874ec0258bef)), closes [#477](https://github.com/camunda/orchestration-cluster-api-js/issues/477) [#476](https://github.com/camunda/orchestration-cluster-api-js/issues/476) [#451](https://github.com/camunda/orchestration-cluster-api-js/issues/451) [#476](https://github.com/camunda/orchestration-cluster-api-js/issues/476) [#474](https://github.com/camunda/orchestration-cluster-api-js/issues/474)
+
 # [10.0.0-alpha.41](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.40...v10.0.0-alpha.41) (2026-08-27)
 
 

package/README.md

@@ -766,6 +766,111 @@ return ack;
 const ack2 = await job.ignore();
 ```
 
+### Deterministic Time (`job.clock`)
+
+The SDK resolves its own cadence — worker poll intervals, retry backoff, eventual-consistency
+polling, backpressure decay — through an injectable clock. Pinning that clock runs all of it
+on virtual time, so tests that would otherwise wait out a 30-second poll finish immediately.
+
+The clock is configured on the client and available as `client.clock`. Handlers reach it as
+`job.clock`, a narrowed view exposing only `now()` and `sleep(ms, signal?)` — `deadline` is
+withheld because a handler that built one against a pinned clock would hang rather than time
+out:
+
+<!-- snippet-source: examples/readme.ts | regions: ReadmeHandlerClock -->
+
+```ts
+const startedAt = job.clock.now();
+
+// A short back-off around a flaky dependency. Waiting here rather than on
+// setTimeout means a test that pins the client's clock also drives the handler.
+await job.clock.sleep(250);
+
+return job.complete({ variables: { waitedMs: job.clock.now() - startedAt } });
+```
+
+Read and wait through `job.clock` rather than `Date.now()` / `setTimeout`, and a test that
+pins the client's clock drives your handler too.
+
+`job.clock.sleep` is for **short in-handler coordination** — spacing retries within one job,
+backing off around a flaky dependency. Long or business-meaningful waits belong in the
+process as BPMN timers, where they survive a crash and are visible to operations.
+
+Pass `createTestClock()` to pin the clock in your own tests:
+
+<!-- snippet-source: examples/readme.ts | regions: ReadmeTestClock -->
+
+```ts
+// Pin the client's clock and the SDK's own cadence runs on virtual time: poll intervals,
+// retry backoff and backpressure decay all settle without waiting in real time.
+const clock = createTestClock({ start: 0, autoAdvance: false });
+const client = createCamundaClient({ clock });
+
+// Nothing settles until the test moves time, so start the wait and advance into it.
+const waiting = client.clock.sleep(30_000);
+await clock.advance(30_000);
+await waiting;
+
+console.log(client.clock.now()); // 30000
+console.log(clock.sleeps); // [30000] — every duration the SDK asked to wait
+```
+
+`autoAdvance` defaults to `true`, where each sleep settles itself on the next macrotask
+having moved time to its wake point — the SDK's loops make progress without the test driving
+them. Set it to `false`, as above, when you need to assert on state *between* two waits.
+
+#### Binding the SDK to the engine clock
+
+`createTestClock` pins the SDK in isolation: the engine carries on at real time. When you are
+testing against a live engine, `createEngineClock` binds the two together so they advance as
+one — `sleep` moves engine time forward via `PUT /clock` instead of waiting:
+
+<!-- snippet-source: examples/readme.ts | regions: ReadmeEngineClock -->
+
+```ts
+// Bind the SDK's cadence to the engine's own clock. `sleep` no longer waits — it moves
+// engine time forward — so a worker polling for something that never arrives advances the
+// engine instead of burning real seconds.
+//
+// Two clients, deliberately. `client` issues the pins and must stay on the live clock:
+// HTTP retry sleeps on whatever clock its client was given, so pointing the engine clock
+// at its own driver would have a failed pin back off through `sleep`, which issues another
+// pin, and so on.
+const client = createCamundaClient();
+const clock = createEngineClock(client, { start: Date.now() });
+const pinned = createCamundaClient({ clock });
+
+await clock.pin(Date.now());
+try {
+  // A minute of engine time. BPMN timers due inside it fire; the test does not wait.
+  await pinned.clock.sleep(60_000);
+} finally {
+  await clock.reset(); // hand the engine back to real time
+}
+```
+
+This is what makes a worker loop deterministic end to end: the poll interval *drives* engine
+time rather than racing it, so a test that would spend a real minute waiting on something
+that never becomes ready finishes as fast as the requests complete.
+
+> [!WARNING]
+> Pinning is global to the cluster. Only point an engine clock at an engine you own —
+> never a shared environment. Always `reset()` in a `finally`.
+
+> [!IMPORTANT]
+> The client you hand to `createEngineClock` must not itself be configured with that clock.
+> HTTP retry backs off on whatever clock its client was given, so a self-referential setup
+> would have a failed `pinClock` retry through `sleep`, which issues another `pinClock`.
+> Keep the driving client on the live clock, as in the example above.
+
+Prefer `createTestClock` over hand-writing a `Clock`. The contract has clauses that are easy
+to get subtly wrong — most notably that `sleep` must not settle in a microtask, because the
+worker schedules its next poll on resolution and would otherwise spin.
+
+Two things deliberately stay on real time even when the clock is pinned, so that pinning it
+cannot hang a process: **liveness bounds** (shutdown drain, request and config-fetch
+timeouts) and **observational timestamps** (log, telemetry and support-bundle records).
+
 ### Job Corrections (User Task Listeners)
 
 When a job worker handles a [user task listener](https://docs.camunda.io/docs/components/concepts/user-task-listeners/), it can correct task properties (assignee, due date, candidate groups, etc.) by passing a `result` to `job.complete()`:
@@ -1330,7 +1435,9 @@ Exports available from `.../effect`:
   (`pages()` / `items()` → `Stream`, `toArray()` → `Effect`). See below.
 
 **Clock-class win:** `eventually` / `withTimeout` run on the Effect `Clock`, so `TestClock.adjust`
-advances eventual/timeout deterministically in tests — no real-clock burn.
+advances eventual/timeout deterministically in tests — no real-clock burn. The Promise surface
+has the same property via [`createTestClock`](#deterministic-time-jobclock); the difference is
+that Effect gives you `TestClock` and the rest of the ecosystem for free.
 
 ### Paginated Search as a `Stream`
 
@@ -1441,7 +1548,9 @@ Worker exports from `.../effect`:
 
 **Clock-class win:** the activation poll interval and the handler-retry `Schedule` run on the Effect
 `Clock`, so `TestClock.adjust` bounds activation/retry timing in virtual time — the whole loop is
-deterministic in tests, with no real-clock burn.
+deterministic in tests, with no real-clock burn. The Promise worker is equally drivable by pinning
+the client clock (see [Deterministic Time](#deterministic-time-jobclock)); what Effect adds here is
+`Schedule` composition over the retry policy.
 
 ### Injecting Services into a Handler