@camunda8/orchestration-cluster-api 10.0.0-alpha.42 → 10.0.0-alpha.44

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [10.0.0-alpha.44](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.43...v10.0.0-alpha.44) (2026-09-10)
+
+
+### Features
+
+* regenerate and update agentInstance examples ([#501](https://github.com/camunda/orchestration-cluster-api-js/issues/501)) ([093ffca](https://github.com/camunda/orchestration-cluster-api-js/commit/093ffca9593205585e197daa07fdd8909009fde7))
+
+# [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)
 
 

package/README.md

@@ -155,20 +155,11 @@ await camunda.createDeployment({
 
 ## Migrating from 8.9
 
-SDK 10.x (for Camunda 8.10) promotes several identifier and name fields from plain `string` to **branded types** via `CamundaKey<T>`. The wire format and runtime API are unchanged — branded values are still plain strings at runtime and are assignable anywhere a `string` is expected (template literals, logging, JSON serialization). Callers need to brand values using `.assumeExists()` (which performs validation) to satisfy the new types.
+SDK 10.x (for Camunda 8.10) promotes several identifier fields from plain `string` to **branded types**, changes the `getResourceContent` response from a string to an object, and makes `BatchOperationItemResponse.processInstanceKey` nullable. Nothing was removed or renamed, and the wire format is unchanged.
 
-### New branded types
+**→ See [MIGRATION.md](./MIGRATION.md) for the full guide**, including the complete list of affected fields.
 
-| Brand | Used for |
-|-------|----------|
-| `RoleId` | Role identifiers |
-| `GroupId` | Group identifiers |
-| `ClientId` | OAuth client identifiers |
-| `MappingRuleId` | Mapping-rule identifiers |
-| `ClusterVariableName` | Cluster variable names |
-| `AgentInstanceKey` | Agent-instance system keys |
-
-### Migration
+The common case is branding an identifier at the boundary:
 
 <!-- snippet-source: examples/readme.ts | regions: V9ToV10Migration -->
 
@@ -188,12 +179,6 @@ await camunda.assignRoleToGroup({
 
 Each branded type has an `.assumeExists()` method that validates the string and returns the branded value. Validation runs at call time and can throw if the input is malformed, so call it once at the boundary (startup, config parsing, API response) and pass the branded value through your application. See [Branded Keys](#branded-keys) for more on this pattern.
 
-### What does NOT change
-
-- The wire format is unchanged — all values are still strings on the wire.
-- No method signatures changed name or arity.
-- Branded values are assignable anywhere a `string` is expected (template literals, logging, JSON serialization), so existing string-handling code continues to work.
-
 ## Quick Start (Zero‑Config – Recommended)
 
 Keep configuration out of application code. Let the factory read `CAMUNDA_*` variables from the environment (12‑factor style). This makes rotation, secret management, and environment promotion safer & simpler.
@@ -766,6 +751,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 +1420,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 +1533,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