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

package/dist/effect/index.d.cts

@@ -0,0 +1,302 @@
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import { Context, Effect, Stream, Duration, Layer, Schedule, Cause, Scope } from 'effect';
+import { S as SearchPaginateOptions, P as Paginator, a as PaginationMode, C as ConsistencyOptions, b as SearchResponse, c as CamundaClient, d as CamundaOptions, A as ActivatedJobResult } from '../CamundaClient-DsXh8p3U.cjs';
+import 'zod';
+import '../logger-D-p21VHo.cjs';
+
+declare const CamundaValidationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "CamundaValidationError";
+} & Readonly<A>;
+/** A request/response validation failure surfaced by the SDK. */
+declare class CamundaValidationError extends CamundaValidationError_base<{
+    readonly side: 'request' | 'response';
+    readonly operationId?: string;
+    readonly summary: string;
+    readonly issues: string[];
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const EventualConsistencyTimeout_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "EventualConsistencyTimeout";
+} & Readonly<A>;
+/** An eventual-consistency poll that did not converge within its budget. */
+declare class EventualConsistencyTimeout extends EventualConsistencyTimeout_base<{
+    readonly attempts?: number;
+    readonly elapsedMs?: number;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const HttpError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "HttpError";
+} & Readonly<A>;
+/** An HTTP-level failure (non-2xx / transport carrying a status). */
+declare class HttpError extends HttpError_base<{
+    readonly status?: number;
+    readonly body?: unknown;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const CamundaGenericError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "CamundaGenericError";
+} & Readonly<A>;
+/** Any other thrown value that does not map to a more specific tag. */
+declare class CamundaGenericError extends CamundaGenericError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+/** The typed error channel for every Effect the client produces. */
+type DomainError = CamundaValidationError | EventualConsistencyTimeout | HttpError | CamundaGenericError;
+/** The tag literals of the {@link DomainError} union. */
+type DomainErrorTag = DomainError['_tag'];
+/** Options for the Effect client's `.paginate`. */
+interface EffectPaginateOptions<TData = unknown> {
+    /**
+     * Safety cap on pages fetched (default: unbounded). A non-positive value fetches
+     * no pages at all — the cap is enforced *before* the first request.
+     */
+    readonly maxPages?: number;
+    /** How to advance. `auto` prefers a cursor, falls back to offset. */
+    readonly mode?: PaginationMode;
+    /**
+     * Eventual-consistency controls forwarded to the underlying search call. Defaults
+     * to `{ waitUpToMs: 0 }`. Only the **first** page honours this window: once paging
+     * is under way an empty page is end-of-results, not a not-yet-consistent read.
+     */
+    readonly consistency?: ConsistencyOptions<TData>;
+}
+/**
+ * The Effect-flavoured counterpart of a {@link Paginator}: the same three views
+ * (`pages` / `items` / `toArray`) over a multi-page search, as `Stream`s and an
+ * `Effect` rather than async iterables and a `Promise`.
+ *
+ * Every view is lazy — a page is fetched only when pulled — and interruptible:
+ * interrupting the fiber cancels the in-flight page request rather than leaving it
+ * to settle unobserved.
+ */
+interface EffectPaginator<TItem> {
+    /** A `Stream` of whole pages, each fetched lazily as it is pulled. */
+    pages(): Stream.Stream<SearchResponse<TItem>, DomainError>;
+    /** A `Stream` of individual items, flattened across all pages. */
+    items(): Stream.Stream<TItem, DomainError>;
+    /** Eagerly drains every item into an array. Bounded result sets only. */
+    toArray(): Effect.Effect<TItem[], DomainError>;
+}
+/** Keys of `C` whose values are callable. */
+type FnKeys<C> = {
+    [K in keyof C]: C[K] extends (...a: any) => any ? K : never;
+}[keyof C];
+/**
+ * Helpers attached to a client *method* (not to the client), re-expressed in Effect
+ * terms. Resolves to `unknown` — the identity of `&` — for a method that carries none.
+ */
+type EffectifyMethodHelpers<F> = F extends {
+    paginate(body: infer B, opts?: SearchPaginateOptions<infer D>): Paginator<infer I>;
+} ? {
+    paginate(body: B, opts?: EffectPaginateOptions<D>): EffectPaginator<I>;
+} : unknown;
+/** Maps a single method to its Effect-returning form, keeping its attached helpers. */
+type EffectifyMethod<F> = F extends (...a: infer A) => infer R ? ((...a: A) => Effect.Effect<Awaited<R>, DomainError, never>) & EffectifyMethodHelpers<F> : never;
+/** Maps every method of `C` to an Effect-returning method, preserving non-fn members. */
+type Effectify<C> = {
+    [K in FnKeys<C>]: EffectifyMethod<C[K]>;
+} & {
+    inner: C;
+} & {
+    [K in Exclude<keyof C, FnKeys<C>>]: C[K];
+};
+/** The Effect-flavoured Camunda client. Every operation returns an `Effect`. */
+type CamundaEffectClient = Effectify<CamundaClient>;
+/**
+ * Create an Effect-flavoured Camunda client.
+ *
+ * Every `CamundaClient` method becomes `(...args) => Effect.Effect<Awaited<R>,
+ * DomainError, never>`. Failures are narrowed into the tagged {@link DomainError}
+ * union so callers use `Effect.catchTag`/`catchTags`. The underlying throwing
+ * client is reachable via the `.inner` escape hatch.
+ *
+ * @description Camunda Effect Client. See the README and [this test](https://github.com/camunda/orchestration-cluster-api-js/blob/main/tests-integration/effect.test.ts) for example usage.
+ */
+declare function createCamundaEffectClient(options?: CamundaOptions): CamundaEffectClient;
+/**
+ * Retry an effect with exponential backoff (+ jitter), capped attempts, and an
+ * optional predicate over the error.
+ */
+declare function retryWithBackoff<A, E, R>(effect: Effect.Effect<A, E, R>, opts: {
+    max: number;
+    baseDelay?: Duration.Input;
+    while?: (e: E) => boolean;
+}): Effect.Effect<A, E, R>;
+/**
+ * Fail an effect with a real interruption if it does not settle within `duration`
+ * (true interruption, not a best-effort `Promise.race`).
+ */
+declare function withTimeout<A, E, R>(effect: Effect.Effect<A, E, R>, duration: Duration.Input, onTimeout?: () => E | EventualConsistencyTimeout): Effect.Effect<A, E | EventualConsistencyTimeout, R>;
+/**
+ * Poll `effect` on the Effect `Clock` until `predicate` holds, timing out to
+ * {@link EventualConsistencyTimeout} once `waitUpTo` elapses. Because it uses the
+ * Effect `Clock` (not `Date.now`/`setTimeout`), `TestClock.adjust` advances it
+ * deterministically in tests — no real-clock burn.
+ */
+declare function eventually<A, E, R>(effect: Effect.Effect<A, E, R>, predicate: (a: A) => boolean, opts: {
+    waitUpTo: Duration.Input;
+    interval?: Duration.Input;
+}): Effect.Effect<A, E | EventualConsistencyTimeout, R>;
+declare const CamundaEffect_base: Context.ServiceClass<CamundaEffect, "CamundaEffect", CamundaEffectClient>;
+/**
+ * `Context` service key for the Effect Camunda client. Compose worker/orchestration
+ * code against this tag and provide {@link layer} (or a test double) via `Layer`.
+ */
+declare class CamundaEffect extends CamundaEffect_base {
+}
+/**
+ * A `Layer` that constructs a {@link CamundaEffectClient} and provides it as the
+ * {@link CamundaEffect} service. Swap in a test double by providing a different
+ * `Layer` for the same tag.
+ */
+declare function layer(options?: CamundaOptions): Layer.Layer<CamundaEffect>;
+
+/**
+ * A single activated job handed to an Effect handler. This is the raw activation
+ * payload (variables + custom headers + lifecycle keys); acknowledgement is driven
+ * by the value/error the handler's `Effect` produces, not by imperative methods.
+ */
+type Job = ActivatedJobResult;
+/** Variables to complete a job with. `void`/`undefined` completes with no variables. */
+type CompleteVars = {
+    readonly [key: string]: unknown;
+} | void | undefined;
+declare const RetryableJobError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "RetryableJobError";
+} & Readonly<A>;
+/**
+ * A retryable job failure: the handler could not complete the job now, but a later
+ * activation might succeed. Mapped to `failJob` with `retries - 1` and an optional
+ * server-side re-activation backoff.
+ */
+declare class RetryableJobError extends RetryableJobError_base<{
+    readonly message: string;
+    /** Server-side delay before the job becomes re-activatable (`failJob` `retryBackOff`). */
+    readonly retryBackoff?: Duration.Input;
+    /** Optional variables to attach to the job on failure. */
+    readonly variables?: {
+        readonly [key: string]: unknown;
+    };
+    readonly cause?: unknown;
+}> {
+}
+declare const TerminalJobError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "TerminalJobError";
+} & Readonly<A>;
+/**
+ * A terminal job failure: retrying will not help. Mapped to `throwJobError`, which
+ * is caught by a matching BPMN error boundary event or — if uncaught — raises an
+ * incident.
+ */
+declare class TerminalJobError extends TerminalJobError_base<{
+    /** The BPMN error code matched against an error catch event. */
+    readonly code: string;
+    readonly message: string;
+    /** Optional variables to instantiate at the error catch event's scope. */
+    readonly variables?: {
+        readonly [key: string]: unknown;
+    };
+    readonly cause?: unknown;
+}> {
+}
+/** The typed error channel a job handler may fail with. */
+type JobError = RetryableJobError | TerminalJobError;
+/** A job handler: consumes a {@link Job}, produces completion variables or a {@link JobError}. */
+type JobHandler<A extends CompleteVars, R> = (job: Job) => Effect.Effect<A, JobError, R>;
+interface ActivateJobsStreamOptions<R = never> {
+    /** Worker name recorded on the activation request. Defaults to `effect-worker-<type>-<n>`, where `<n>` is an incrementing per-process counter. */
+    readonly workerName?: string;
+    /** Max jobs to activate per poll (the activation batch size). Default `10`. */
+    readonly maxJobsToActivate?: number;
+    /**
+     * Delay between polls that returned **no** jobs, on the Effect `Clock` (so it is
+     * virtual under `TestClock`). A poll that returns jobs schedules the next poll
+     * immediately. Default `1 second`.
+     */
+    readonly pollInterval?: Duration.Input;
+    /** Per-job activation lock timeout (server-side). Default `60 seconds`. */
+    readonly jobTimeout?: Duration.Input;
+    /**
+     * Long-poll request timeout. `0` (the default) lets the broker hold the request
+     * for its configured default; a negative value returns immediately when idle.
+     */
+    readonly requestTimeout?: Duration.Input | number;
+    /** Restrict activation to these variable names. */
+    readonly fetchVariables?: readonly string[];
+    /**
+     * `Schedule` used to back off and retry a **failed activation request** (transport
+     * outage, broker restart, transient server error). Runs on the Effect `Clock`.
+     * When omitted, an activation failure fails the stream.
+     */
+    readonly activationRetrySchedule?: Schedule.Schedule<unknown, DomainError, never, R>;
+}
+interface EffectWorkerConfig<A extends CompleteVars, R = never> extends ActivateJobsStreamOptions<R> {
+    /** The job type to activate. */
+    readonly type: string;
+    /** The Effect job handler. */
+    readonly handler: JobHandler<A, R>;
+    /**
+     * Max jobs processed concurrently (handler parallelism / backpressure). The
+     * activation loop will not pull faster than handlers drain, and the activation
+     * batch is capped to this value (when it is a finite number) so the worker never
+     * leases more jobs than it can process at once. Default: the value of
+     * {@link ActivateJobsStreamOptions.maxJobsToActivate} (or `10`).
+     */
+    readonly concurrency?: number | 'unbounded';
+    /**
+     * `Schedule` used to retry the **handler** in-process on a {@link RetryableJobError}
+     * before the job is failed back to the broker. Runs on the Effect `Clock`
+     * (virtual under `TestClock`). A {@link TerminalJobError} is never retried.
+     */
+    readonly handlerRetrySchedule?: Schedule.Schedule<unknown, JobError, never, R>;
+}
+/** A handle to a running Effect worker. */
+interface CamundaEffectWorkerHandle {
+    /** The job type this worker activates. */
+    readonly type: string;
+    /** Completes when the worker loop ends (only on a fatal, non-retryable activation error). */
+    readonly join: Effect.Effect<void, DomainError>;
+    /** Interrupt the worker (also happens automatically when the owning scope closes). */
+    readonly interrupt: Effect.Effect<void>;
+}
+/**
+ * A `Stream` of activated jobs of `type`. Repeatedly calls `activateJobs` (through the
+ * `/effect` client `Layer`, i.e. the same backpressure-aware runtime the Promise worker
+ * uses) and emits each activated job. The between-empty-polls delay and the optional
+ * activation-retry `Schedule` both run on the Effect `Clock`, so `TestClock.adjust`
+ * advances them deterministically in tests.
+ */
+declare function activateJobsStream<R = never>(type: string, options?: ActivateJobsStreamOptions<R>): Stream.Stream<Job, DomainError, CamundaEffect | R>;
+/**
+ * The worker loop: drains {@link activateJobsStream}, running the handler for each job
+ * with bounded `concurrency` (the backpressure knob), and acknowledging via
+ * `completeJob`/`failJob`/`throwJobError` per the handler's typed outcome.
+ */
+declare function runWorkerLoop<A extends CompleteVars, R = never>(config: EffectWorkerConfig<A, R>): Effect.Effect<void, DomainError, CamundaEffect | R>;
+/**
+ * Create and start an Effect job worker, forked into the current `Scope`. The worker
+ * runs until its scope closes (or {@link CamundaEffectWorkerHandle.interrupt} is run),
+ * at which point it is interrupted and any in-flight job's lease is released.
+ *
+ * Depends on the {@link CamundaEffect} service — provide the `/effect` client `layer`.
+ *
+ * @description Camunda Effect Worker. See the README and [this test](https://github.com/camunda/orchestration-cluster-api-js/blob/main/tests-integration/effect-worker.test.ts) for example usage.
+ */
+declare function createCamundaEffectWorker<A extends CompleteVars, R = never>(config: EffectWorkerConfig<A, R>): Effect.Effect<CamundaEffectWorkerHandle, never, Scope.Scope | CamundaEffect | R>;
+/**
+ * A `Layer` that runs a Camunda Effect worker for the layer's lifetime. Compose it
+ * with the `/effect` client `layer` (which provides its {@link CamundaEffect}
+ * dependency) plus a `Layer` for the handler's own requirements `R`.
+ */
+declare function workerLayer<A extends CompleteVars, R = never>(config: EffectWorkerConfig<A, R>): Layer.Layer<never, never, CamundaEffect | R>;
+
+export { type ActivateJobsStreamOptions, CamundaEffect, type CamundaEffectClient, type CamundaEffectWorkerHandle, CamundaGenericError, CamundaValidationError, type CompleteVars, type DomainError, type DomainErrorTag, type EffectPaginateOptions, type EffectPaginator, type EffectWorkerConfig, type Effectify, EventualConsistencyTimeout, type FnKeys, HttpError, type Job, type JobError, type JobHandler, RetryableJobError, TerminalJobError, activateJobsStream, createCamundaEffectClient, createCamundaEffectWorker, eventually, layer, retryWithBackoff, runWorkerLoop, withTimeout, workerLayer };

package/dist/effect/index.d.ts

@@ -0,0 +1,302 @@
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import { Context, Effect, Stream, Duration, Layer, Schedule, Cause, Scope } from 'effect';
+import { S as SearchPaginateOptions, P as Paginator, a as PaginationMode, C as ConsistencyOptions, b as SearchResponse, c as CamundaClient, d as CamundaOptions, A as ActivatedJobResult } from '../CamundaClient-BsoVLG5C.js';
+import 'zod';
+import '../logger-D-p21VHo.js';
+
+declare const CamundaValidationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "CamundaValidationError";
+} & Readonly<A>;
+/** A request/response validation failure surfaced by the SDK. */
+declare class CamundaValidationError extends CamundaValidationError_base<{
+    readonly side: 'request' | 'response';
+    readonly operationId?: string;
+    readonly summary: string;
+    readonly issues: string[];
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const EventualConsistencyTimeout_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "EventualConsistencyTimeout";
+} & Readonly<A>;
+/** An eventual-consistency poll that did not converge within its budget. */
+declare class EventualConsistencyTimeout extends EventualConsistencyTimeout_base<{
+    readonly attempts?: number;
+    readonly elapsedMs?: number;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const HttpError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "HttpError";
+} & Readonly<A>;
+/** An HTTP-level failure (non-2xx / transport carrying a status). */
+declare class HttpError extends HttpError_base<{
+    readonly status?: number;
+    readonly body?: unknown;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const CamundaGenericError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "CamundaGenericError";
+} & Readonly<A>;
+/** Any other thrown value that does not map to a more specific tag. */
+declare class CamundaGenericError extends CamundaGenericError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+/** The typed error channel for every Effect the client produces. */
+type DomainError = CamundaValidationError | EventualConsistencyTimeout | HttpError | CamundaGenericError;
+/** The tag literals of the {@link DomainError} union. */
+type DomainErrorTag = DomainError['_tag'];
+/** Options for the Effect client's `.paginate`. */
+interface EffectPaginateOptions<TData = unknown> {
+    /**
+     * Safety cap on pages fetched (default: unbounded). A non-positive value fetches
+     * no pages at all — the cap is enforced *before* the first request.
+     */
+    readonly maxPages?: number;
+    /** How to advance. `auto` prefers a cursor, falls back to offset. */
+    readonly mode?: PaginationMode;
+    /**
+     * Eventual-consistency controls forwarded to the underlying search call. Defaults
+     * to `{ waitUpToMs: 0 }`. Only the **first** page honours this window: once paging
+     * is under way an empty page is end-of-results, not a not-yet-consistent read.
+     */
+    readonly consistency?: ConsistencyOptions<TData>;
+}
+/**
+ * The Effect-flavoured counterpart of a {@link Paginator}: the same three views
+ * (`pages` / `items` / `toArray`) over a multi-page search, as `Stream`s and an
+ * `Effect` rather than async iterables and a `Promise`.
+ *
+ * Every view is lazy — a page is fetched only when pulled — and interruptible:
+ * interrupting the fiber cancels the in-flight page request rather than leaving it
+ * to settle unobserved.
+ */
+interface EffectPaginator<TItem> {
+    /** A `Stream` of whole pages, each fetched lazily as it is pulled. */
+    pages(): Stream.Stream<SearchResponse<TItem>, DomainError>;
+    /** A `Stream` of individual items, flattened across all pages. */
+    items(): Stream.Stream<TItem, DomainError>;
+    /** Eagerly drains every item into an array. Bounded result sets only. */
+    toArray(): Effect.Effect<TItem[], DomainError>;
+}
+/** Keys of `C` whose values are callable. */
+type FnKeys<C> = {
+    [K in keyof C]: C[K] extends (...a: any) => any ? K : never;
+}[keyof C];
+/**
+ * Helpers attached to a client *method* (not to the client), re-expressed in Effect
+ * terms. Resolves to `unknown` — the identity of `&` — for a method that carries none.
+ */
+type EffectifyMethodHelpers<F> = F extends {
+    paginate(body: infer B, opts?: SearchPaginateOptions<infer D>): Paginator<infer I>;
+} ? {
+    paginate(body: B, opts?: EffectPaginateOptions<D>): EffectPaginator<I>;
+} : unknown;
+/** Maps a single method to its Effect-returning form, keeping its attached helpers. */
+type EffectifyMethod<F> = F extends (...a: infer A) => infer R ? ((...a: A) => Effect.Effect<Awaited<R>, DomainError, never>) & EffectifyMethodHelpers<F> : never;
+/** Maps every method of `C` to an Effect-returning method, preserving non-fn members. */
+type Effectify<C> = {
+    [K in FnKeys<C>]: EffectifyMethod<C[K]>;
+} & {
+    inner: C;
+} & {
+    [K in Exclude<keyof C, FnKeys<C>>]: C[K];
+};
+/** The Effect-flavoured Camunda client. Every operation returns an `Effect`. */
+type CamundaEffectClient = Effectify<CamundaClient>;
+/**
+ * Create an Effect-flavoured Camunda client.
+ *
+ * Every `CamundaClient` method becomes `(...args) => Effect.Effect<Awaited<R>,
+ * DomainError, never>`. Failures are narrowed into the tagged {@link DomainError}
+ * union so callers use `Effect.catchTag`/`catchTags`. The underlying throwing
+ * client is reachable via the `.inner` escape hatch.
+ *
+ * @description Camunda Effect Client. See the README and [this test](https://github.com/camunda/orchestration-cluster-api-js/blob/main/tests-integration/effect.test.ts) for example usage.
+ */
+declare function createCamundaEffectClient(options?: CamundaOptions): CamundaEffectClient;
+/**
+ * Retry an effect with exponential backoff (+ jitter), capped attempts, and an
+ * optional predicate over the error.
+ */
+declare function retryWithBackoff<A, E, R>(effect: Effect.Effect<A, E, R>, opts: {
+    max: number;
+    baseDelay?: Duration.Input;
+    while?: (e: E) => boolean;
+}): Effect.Effect<A, E, R>;
+/**
+ * Fail an effect with a real interruption if it does not settle within `duration`
+ * (true interruption, not a best-effort `Promise.race`).
+ */
+declare function withTimeout<A, E, R>(effect: Effect.Effect<A, E, R>, duration: Duration.Input, onTimeout?: () => E | EventualConsistencyTimeout): Effect.Effect<A, E | EventualConsistencyTimeout, R>;
+/**
+ * Poll `effect` on the Effect `Clock` until `predicate` holds, timing out to
+ * {@link EventualConsistencyTimeout} once `waitUpTo` elapses. Because it uses the
+ * Effect `Clock` (not `Date.now`/`setTimeout`), `TestClock.adjust` advances it
+ * deterministically in tests — no real-clock burn.
+ */
+declare function eventually<A, E, R>(effect: Effect.Effect<A, E, R>, predicate: (a: A) => boolean, opts: {
+    waitUpTo: Duration.Input;
+    interval?: Duration.Input;
+}): Effect.Effect<A, E | EventualConsistencyTimeout, R>;
+declare const CamundaEffect_base: Context.ServiceClass<CamundaEffect, "CamundaEffect", CamundaEffectClient>;
+/**
+ * `Context` service key for the Effect Camunda client. Compose worker/orchestration
+ * code against this tag and provide {@link layer} (or a test double) via `Layer`.
+ */
+declare class CamundaEffect extends CamundaEffect_base {
+}
+/**
+ * A `Layer` that constructs a {@link CamundaEffectClient} and provides it as the
+ * {@link CamundaEffect} service. Swap in a test double by providing a different
+ * `Layer` for the same tag.
+ */
+declare function layer(options?: CamundaOptions): Layer.Layer<CamundaEffect>;
+
+/**
+ * A single activated job handed to an Effect handler. This is the raw activation
+ * payload (variables + custom headers + lifecycle keys); acknowledgement is driven
+ * by the value/error the handler's `Effect` produces, not by imperative methods.
+ */
+type Job = ActivatedJobResult;
+/** Variables to complete a job with. `void`/`undefined` completes with no variables. */
+type CompleteVars = {
+    readonly [key: string]: unknown;
+} | void | undefined;
+declare const RetryableJobError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "RetryableJobError";
+} & Readonly<A>;
+/**
+ * A retryable job failure: the handler could not complete the job now, but a later
+ * activation might succeed. Mapped to `failJob` with `retries - 1` and an optional
+ * server-side re-activation backoff.
+ */
+declare class RetryableJobError extends RetryableJobError_base<{
+    readonly message: string;
+    /** Server-side delay before the job becomes re-activatable (`failJob` `retryBackOff`). */
+    readonly retryBackoff?: Duration.Input;
+    /** Optional variables to attach to the job on failure. */
+    readonly variables?: {
+        readonly [key: string]: unknown;
+    };
+    readonly cause?: unknown;
+}> {
+}
+declare const TerminalJobError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "TerminalJobError";
+} & Readonly<A>;
+/**
+ * A terminal job failure: retrying will not help. Mapped to `throwJobError`, which
+ * is caught by a matching BPMN error boundary event or — if uncaught — raises an
+ * incident.
+ */
+declare class TerminalJobError extends TerminalJobError_base<{
+    /** The BPMN error code matched against an error catch event. */
+    readonly code: string;
+    readonly message: string;
+    /** Optional variables to instantiate at the error catch event's scope. */
+    readonly variables?: {
+        readonly [key: string]: unknown;
+    };
+    readonly cause?: unknown;
+}> {
+}
+/** The typed error channel a job handler may fail with. */
+type JobError = RetryableJobError | TerminalJobError;
+/** A job handler: consumes a {@link Job}, produces completion variables or a {@link JobError}. */
+type JobHandler<A extends CompleteVars, R> = (job: Job) => Effect.Effect<A, JobError, R>;
+interface ActivateJobsStreamOptions<R = never> {
+    /** Worker name recorded on the activation request. Defaults to `effect-worker-<type>-<n>`, where `<n>` is an incrementing per-process counter. */
+    readonly workerName?: string;
+    /** Max jobs to activate per poll (the activation batch size). Default `10`. */
+    readonly maxJobsToActivate?: number;
+    /**
+     * Delay between polls that returned **no** jobs, on the Effect `Clock` (so it is
+     * virtual under `TestClock`). A poll that returns jobs schedules the next poll
+     * immediately. Default `1 second`.
+     */
+    readonly pollInterval?: Duration.Input;
+    /** Per-job activation lock timeout (server-side). Default `60 seconds`. */
+    readonly jobTimeout?: Duration.Input;
+    /**
+     * Long-poll request timeout. `0` (the default) lets the broker hold the request
+     * for its configured default; a negative value returns immediately when idle.
+     */
+    readonly requestTimeout?: Duration.Input | number;
+    /** Restrict activation to these variable names. */
+    readonly fetchVariables?: readonly string[];
+    /**
+     * `Schedule` used to back off and retry a **failed activation request** (transport
+     * outage, broker restart, transient server error). Runs on the Effect `Clock`.
+     * When omitted, an activation failure fails the stream.
+     */
+    readonly activationRetrySchedule?: Schedule.Schedule<unknown, DomainError, never, R>;
+}
+interface EffectWorkerConfig<A extends CompleteVars, R = never> extends ActivateJobsStreamOptions<R> {
+    /** The job type to activate. */
+    readonly type: string;
+    /** The Effect job handler. */
+    readonly handler: JobHandler<A, R>;
+    /**
+     * Max jobs processed concurrently (handler parallelism / backpressure). The
+     * activation loop will not pull faster than handlers drain, and the activation
+     * batch is capped to this value (when it is a finite number) so the worker never
+     * leases more jobs than it can process at once. Default: the value of
+     * {@link ActivateJobsStreamOptions.maxJobsToActivate} (or `10`).
+     */
+    readonly concurrency?: number | 'unbounded';
+    /**
+     * `Schedule` used to retry the **handler** in-process on a {@link RetryableJobError}
+     * before the job is failed back to the broker. Runs on the Effect `Clock`
+     * (virtual under `TestClock`). A {@link TerminalJobError} is never retried.
+     */
+    readonly handlerRetrySchedule?: Schedule.Schedule<unknown, JobError, never, R>;
+}
+/** A handle to a running Effect worker. */
+interface CamundaEffectWorkerHandle {
+    /** The job type this worker activates. */
+    readonly type: string;
+    /** Completes when the worker loop ends (only on a fatal, non-retryable activation error). */
+    readonly join: Effect.Effect<void, DomainError>;
+    /** Interrupt the worker (also happens automatically when the owning scope closes). */
+    readonly interrupt: Effect.Effect<void>;
+}
+/**
+ * A `Stream` of activated jobs of `type`. Repeatedly calls `activateJobs` (through the
+ * `/effect` client `Layer`, i.e. the same backpressure-aware runtime the Promise worker
+ * uses) and emits each activated job. The between-empty-polls delay and the optional
+ * activation-retry `Schedule` both run on the Effect `Clock`, so `TestClock.adjust`
+ * advances them deterministically in tests.
+ */
+declare function activateJobsStream<R = never>(type: string, options?: ActivateJobsStreamOptions<R>): Stream.Stream<Job, DomainError, CamundaEffect | R>;
+/**
+ * The worker loop: drains {@link activateJobsStream}, running the handler for each job
+ * with bounded `concurrency` (the backpressure knob), and acknowledging via
+ * `completeJob`/`failJob`/`throwJobError` per the handler's typed outcome.
+ */
+declare function runWorkerLoop<A extends CompleteVars, R = never>(config: EffectWorkerConfig<A, R>): Effect.Effect<void, DomainError, CamundaEffect | R>;
+/**
+ * Create and start an Effect job worker, forked into the current `Scope`. The worker
+ * runs until its scope closes (or {@link CamundaEffectWorkerHandle.interrupt} is run),
+ * at which point it is interrupted and any in-flight job's lease is released.
+ *
+ * Depends on the {@link CamundaEffect} service — provide the `/effect` client `layer`.
+ *
+ * @description Camunda Effect Worker. See the README and [this test](https://github.com/camunda/orchestration-cluster-api-js/blob/main/tests-integration/effect-worker.test.ts) for example usage.
+ */
+declare function createCamundaEffectWorker<A extends CompleteVars, R = never>(config: EffectWorkerConfig<A, R>): Effect.Effect<CamundaEffectWorkerHandle, never, Scope.Scope | CamundaEffect | R>;
+/**
+ * A `Layer` that runs a Camunda Effect worker for the layer's lifetime. Compose it
+ * with the `/effect` client `layer` (which provides its {@link CamundaEffect}
+ * dependency) plus a `Layer` for the handler's own requirements `R`.
+ */
+declare function workerLayer<A extends CompleteVars, R = never>(config: EffectWorkerConfig<A, R>): Layer.Layer<never, never, CamundaEffect | R>;
+
+export { type ActivateJobsStreamOptions, CamundaEffect, type CamundaEffectClient, type CamundaEffectWorkerHandle, CamundaGenericError, CamundaValidationError, type CompleteVars, type DomainError, type DomainErrorTag, type EffectPaginateOptions, type EffectPaginator, type EffectWorkerConfig, type Effectify, EventualConsistencyTimeout, type FnKeys, HttpError, type Job, type JobError, type JobHandler, RetryableJobError, TerminalJobError, activateJobsStream, createCamundaEffectClient, createCamundaEffectWorker, eventually, layer, retryWithBackoff, runWorkerLoop, withTimeout, workerLayer };