@camunda8/orchestration-cluster-api 10.0.0-alpha.39 → 10.0.0-alpha.40

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [10.0.0-alpha.40](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.39...v10.0.0-alpha.40) (2026-08-27)
+
+
+### Features
+
+* **clock:** resolve runtime cadence through the injected clock ([#474](https://github.com/camunda/orchestration-cluster-api-js/issues/474)) ([303d10d](https://github.com/camunda/orchestration-cluster-api-js/commit/303d10de1e092c6bb7aa5b95ef036eaba9a47f06))
+
 # [10.0.0-alpha.39](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.38...v10.0.0-alpha.39) (2026-08-27)
 
 

package/dist/{CamundaClient-Crt5W0EI.d.ts → CamundaClient-BsoVLG5C.d.ts}

@@ -2,6 +2,68 @@ import * as zod from 'zod';
 import { z } from 'zod';
 import { L as LogLevel, a as LogTransport, b as Logger } from './logger-D-p21VHo.js';
 
+/**
+ * The clock all SDK runtime cadence resolves through — worker poll loops, eventual
+ * consistency polling, retry backoff, backpressure decay and auth refresh.
+ *
+ * Pinning this pins the client's own timing, which is what makes those loops testable
+ * without waiting for real time. See the cross-SDK contract in
+ * camunda/orchestration-cluster-api-js#450.
+ *
+ * Generalises the two seams that already existed: `CollectClock` in `typedVariables.ts`
+ * and the injected `now`/`sleep` on `BackpressureManager`.
+ */
+interface Clock {
+    /** Current wall-clock time in epoch milliseconds. */
+    now(): number;
+    /**
+     * Resolve after `ms` have elapsed on this clock.
+     *
+     * Rejects with the signal's reason if `signal` aborts first, so a caller can cancel a
+     * wait without leaving the timer behind.
+     */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * A signal that aborts once `ms` have elapsed on this clock.
+     *
+     * `dispose()` releases the underlying timer; call it when the guarded work finishes
+     * early, or a long deadline keeps a handle alive for its full duration.
+     */
+    deadline(ms: number): {
+        signal: AbortSignal;
+        dispose: () => void;
+    };
+}
+/**
+ * The live clock: the platform clock, made non-decreasing and self-correcting.
+ *
+ * This is the single place the SDK runtime is allowed to read ambient time or use a
+ * platform timer. Everything else takes a `Clock`.
+ *
+ * Ruling 2a requires three properties together, and the C# pilot shipped three
+ * implementations that each satisfied only two:
+ *
+ * - **Never decreases.** Wall clocks step backwards (NTP correction, VM resume, manual
+ *   change), and a deadline measured across a backward step waits longer than asked.
+ * - **Keeps advancing immediately after a step.** Clamping to a high-water mark satisfies
+ *   the first property but freezes logical time for the *whole* duration of the
+ *   correction, so an hour-long step adds an hour to every deadline in flight — the very
+ *   damage the rule exists to prevent.
+ * - **Converges back.** Absorbing the step into a permanent offset satisfies the first two
+ *   but leaves reported time ahead of true time forever, so any comparison against a
+ *   server-supplied absolute time is wrong for the life of the process.
+ *
+ * A backward step is therefore absorbed and then repaid gradually out of forward
+ * progress, the way NTP slews rather than steps.
+ *
+ * @param source injectable purely so the slew behaviour itself is testable; production
+ * callers use the default. Called through rather than captured, so a test that swaps the
+ * global `Date` (fake timers) still drives the shared `liveClock`.
+ */
+declare function createLiveClock(source?: () => number): Clock;
+/** The clock used when none is injected. */
+declare const liveClock: Clock;
+
 /** Manages eventual consistency for a given operation */
 interface ConsistencyOptions<T> {
     waitUpToMs: number;
@@ -639,7 +701,10 @@ type AgentInstanceUpdateRequest = {
      * Used for ownership/equality validation against the stored agent instance
      * and, when the supplied key differs from the previous association (re-entry
      * of an ad-hoc sub-process or AI Agent task), appended to elementInstanceKeys
-     * with the reverse link updated on the supplied element instance.
+     * with the reverse link updated on the supplied element instance. Only one
+     * element instance may hold this write claim at a time: any update from a
+     * different element instance is rejected while the current writer's job is
+     * still active.
      *
      */
     elementInstanceKey: ElementInstanceKey;
@@ -8131,7 +8196,7 @@ type MappingRuleFilter = {
     /**
      * The name of the mapping rule.
      */
-    name?: string;
+    name?: StringFilterProperty;
     /**
      * The ID of the mapping rule.
      */
@@ -10040,7 +10105,7 @@ type RoleFilter = {
     /**
      * The role name search filters.
      */
-    name?: string;
+    name?: StringFilterProperty;
 };
 /**
  * Role search response.
@@ -22048,67 +22113,6 @@ declare namespace VariableKey {
 
 type BackpressureSeverity = 'healthy' | 'soft' | 'severe';
 
-/**
- * The clock all SDK runtime cadence resolves through — worker poll loops, eventual
- * consistency polling, retry backoff, backpressure decay and auth refresh.
- *
- * Pinning this pins the client's own timing, which is what makes those loops testable
- * without waiting for real time. See the cross-SDK contract in
- * camunda/orchestration-cluster-api-js#450.
- *
- * Generalises the two seams that already existed: `CollectClock` in `typedVariables.ts`
- * and the injected `now`/`sleep` on `BackpressureManager`.
- */
-interface Clock {
-    /** Current wall-clock time in epoch milliseconds. */
-    now(): number;
-    /**
-     * Resolve after `ms` have elapsed on this clock.
-     *
-     * Rejects with the signal's reason if `signal` aborts first, so a caller can cancel a
-     * wait without leaving the timer behind.
-     */
-    sleep(ms: number, signal?: AbortSignal): Promise<void>;
-    /**
-     * A signal that aborts once `ms` have elapsed on this clock.
-     *
-     * `dispose()` releases the underlying timer; call it when the guarded work finishes
-     * early, or a long deadline keeps a handle alive for its full duration.
-     */
-    deadline(ms: number): {
-        signal: AbortSignal;
-        dispose: () => void;
-    };
-}
-/**
- * The live clock: the platform clock, made non-decreasing and self-correcting.
- *
- * This is the single place the SDK runtime is allowed to read ambient time or use a
- * platform timer. Everything else takes a `Clock`.
- *
- * Ruling 2a requires three properties together, and the C# pilot shipped three
- * implementations that each satisfied only two:
- *
- * - **Never decreases.** Wall clocks step backwards (NTP correction, VM resume, manual
- *   change), and a deadline measured across a backward step waits longer than asked.
- * - **Keeps advancing immediately after a step.** Clamping to a high-water mark satisfies
- *   the first property but freezes logical time for the *whole* duration of the
- *   correction, so an hour-long step adds an hour to every deadline in flight — the very
- *   damage the rule exists to prevent.
- * - **Converges back.** Absorbing the step into a permanent offset satisfies the first two
- *   but leaves reported time ahead of true time forever, so any comparison against a
- *   server-supplied absolute time is wrong for the life of the process.
- *
- * A backward step is therefore absorbed and then repaid gradually out of forward
- * progress, the way NTP slews rather than steps.
- *
- * @param source injectable purely so the slew behaviour itself is testable; production
- * callers use the default.
- */
-declare function createLiveClock(source?: () => number): Clock;
-/** The clock used when none is injected. */
-declare const liveClock: Clock;
-
 interface GracefulStopResult {
     remainingJobs: number;
     timedOut: boolean;
@@ -22186,7 +22190,7 @@ declare class JobWorker {
     private _name;
     private _activeJobs;
     private _stopped;
-    private _pollTimer;
+    private _pollWait;
     private _inFlightActivation;
     /** Consecutive failed activation requests; drives the retry backoff, reset on success. */
     private _consecutiveActivationErrors;
@@ -22877,7 +22881,7 @@ declare class ThreadedJobWorker {
     private _name;
     private _activeJobs;
     private _stopped;
-    private _pollTimer;
+    private _pollWait;
     private _inFlightActivation;
     /** Consecutive failed activation requests; drives the retry backoff, reset on success. */
     private _consecutiveActivationErrors;

package/dist/{CamundaClient-VlYVveFG.d.cts → CamundaClient-DsXh8p3U.d.cts}

@@ -2,6 +2,68 @@ import * as zod from 'zod';
 import { z } from 'zod';
 import { L as LogLevel, a as LogTransport, b as Logger } from './logger-D-p21VHo.cjs';
 
+/**
+ * The clock all SDK runtime cadence resolves through — worker poll loops, eventual
+ * consistency polling, retry backoff, backpressure decay and auth refresh.
+ *
+ * Pinning this pins the client's own timing, which is what makes those loops testable
+ * without waiting for real time. See the cross-SDK contract in
+ * camunda/orchestration-cluster-api-js#450.
+ *
+ * Generalises the two seams that already existed: `CollectClock` in `typedVariables.ts`
+ * and the injected `now`/`sleep` on `BackpressureManager`.
+ */
+interface Clock {
+    /** Current wall-clock time in epoch milliseconds. */
+    now(): number;
+    /**
+     * Resolve after `ms` have elapsed on this clock.
+     *
+     * Rejects with the signal's reason if `signal` aborts first, so a caller can cancel a
+     * wait without leaving the timer behind.
+     */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * A signal that aborts once `ms` have elapsed on this clock.
+     *
+     * `dispose()` releases the underlying timer; call it when the guarded work finishes
+     * early, or a long deadline keeps a handle alive for its full duration.
+     */
+    deadline(ms: number): {
+        signal: AbortSignal;
+        dispose: () => void;
+    };
+}
+/**
+ * The live clock: the platform clock, made non-decreasing and self-correcting.
+ *
+ * This is the single place the SDK runtime is allowed to read ambient time or use a
+ * platform timer. Everything else takes a `Clock`.
+ *
+ * Ruling 2a requires three properties together, and the C# pilot shipped three
+ * implementations that each satisfied only two:
+ *
+ * - **Never decreases.** Wall clocks step backwards (NTP correction, VM resume, manual
+ *   change), and a deadline measured across a backward step waits longer than asked.
+ * - **Keeps advancing immediately after a step.** Clamping to a high-water mark satisfies
+ *   the first property but freezes logical time for the *whole* duration of the
+ *   correction, so an hour-long step adds an hour to every deadline in flight — the very
+ *   damage the rule exists to prevent.
+ * - **Converges back.** Absorbing the step into a permanent offset satisfies the first two
+ *   but leaves reported time ahead of true time forever, so any comparison against a
+ *   server-supplied absolute time is wrong for the life of the process.
+ *
+ * A backward step is therefore absorbed and then repaid gradually out of forward
+ * progress, the way NTP slews rather than steps.
+ *
+ * @param source injectable purely so the slew behaviour itself is testable; production
+ * callers use the default. Called through rather than captured, so a test that swaps the
+ * global `Date` (fake timers) still drives the shared `liveClock`.
+ */
+declare function createLiveClock(source?: () => number): Clock;
+/** The clock used when none is injected. */
+declare const liveClock: Clock;
+
 /** Manages eventual consistency for a given operation */
 interface ConsistencyOptions<T> {
     waitUpToMs: number;
@@ -639,7 +701,10 @@ type AgentInstanceUpdateRequest = {
      * Used for ownership/equality validation against the stored agent instance
      * and, when the supplied key differs from the previous association (re-entry
      * of an ad-hoc sub-process or AI Agent task), appended to elementInstanceKeys
-     * with the reverse link updated on the supplied element instance.
+     * with the reverse link updated on the supplied element instance. Only one
+     * element instance may hold this write claim at a time: any update from a
+     * different element instance is rejected while the current writer's job is
+     * still active.
      *
      */
     elementInstanceKey: ElementInstanceKey;
@@ -8131,7 +8196,7 @@ type MappingRuleFilter = {
     /**
      * The name of the mapping rule.
      */
-    name?: string;
+    name?: StringFilterProperty;
     /**
      * The ID of the mapping rule.
      */
@@ -10040,7 +10105,7 @@ type RoleFilter = {
     /**
      * The role name search filters.
      */
-    name?: string;
+    name?: StringFilterProperty;
 };
 /**
  * Role search response.
@@ -22048,67 +22113,6 @@ declare namespace VariableKey {
 
 type BackpressureSeverity = 'healthy' | 'soft' | 'severe';
 
-/**
- * The clock all SDK runtime cadence resolves through — worker poll loops, eventual
- * consistency polling, retry backoff, backpressure decay and auth refresh.
- *
- * Pinning this pins the client's own timing, which is what makes those loops testable
- * without waiting for real time. See the cross-SDK contract in
- * camunda/orchestration-cluster-api-js#450.
- *
- * Generalises the two seams that already existed: `CollectClock` in `typedVariables.ts`
- * and the injected `now`/`sleep` on `BackpressureManager`.
- */
-interface Clock {
-    /** Current wall-clock time in epoch milliseconds. */
-    now(): number;
-    /**
-     * Resolve after `ms` have elapsed on this clock.
-     *
-     * Rejects with the signal's reason if `signal` aborts first, so a caller can cancel a
-     * wait without leaving the timer behind.
-     */
-    sleep(ms: number, signal?: AbortSignal): Promise<void>;
-    /**
-     * A signal that aborts once `ms` have elapsed on this clock.
-     *
-     * `dispose()` releases the underlying timer; call it when the guarded work finishes
-     * early, or a long deadline keeps a handle alive for its full duration.
-     */
-    deadline(ms: number): {
-        signal: AbortSignal;
-        dispose: () => void;
-    };
-}
-/**
- * The live clock: the platform clock, made non-decreasing and self-correcting.
- *
- * This is the single place the SDK runtime is allowed to read ambient time or use a
- * platform timer. Everything else takes a `Clock`.
- *
- * Ruling 2a requires three properties together, and the C# pilot shipped three
- * implementations that each satisfied only two:
- *
- * - **Never decreases.** Wall clocks step backwards (NTP correction, VM resume, manual
- *   change), and a deadline measured across a backward step waits longer than asked.
- * - **Keeps advancing immediately after a step.** Clamping to a high-water mark satisfies
- *   the first property but freezes logical time for the *whole* duration of the
- *   correction, so an hour-long step adds an hour to every deadline in flight — the very
- *   damage the rule exists to prevent.
- * - **Converges back.** Absorbing the step into a permanent offset satisfies the first two
- *   but leaves reported time ahead of true time forever, so any comparison against a
- *   server-supplied absolute time is wrong for the life of the process.
- *
- * A backward step is therefore absorbed and then repaid gradually out of forward
- * progress, the way NTP slews rather than steps.
- *
- * @param source injectable purely so the slew behaviour itself is testable; production
- * callers use the default.
- */
-declare function createLiveClock(source?: () => number): Clock;
-/** The clock used when none is injected. */
-declare const liveClock: Clock;
-
 interface GracefulStopResult {
     remainingJobs: number;
     timedOut: boolean;
@@ -22186,7 +22190,7 @@ declare class JobWorker {
     private _name;
     private _activeJobs;
     private _stopped;
-    private _pollTimer;
+    private _pollWait;
     private _inFlightActivation;
     /** Consecutive failed activation requests; drives the retry backoff, reset on success. */
     private _consecutiveActivationErrors;
@@ -22877,7 +22881,7 @@ declare class ThreadedJobWorker {
     private _name;
     private _activeJobs;
     private _stopped;
-    private _pollTimer;
+    private _pollWait;
     private _inFlightActivation;
     /** Consecutive failed activation requests; drives the retry backoff, reset on success. */
     private _consecutiveActivationErrors;