@camunda8/orchestration-cluster-api 10.0.0-alpha.3 → 10.0.0-alpha.31

package/CHANGELOG.md

@@ -1,3 +1,245 @@
+# [10.0.0-alpha.31](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.30...v10.0.0-alpha.31) (2026-08-20)
+
+
+### Features
+
+* **effect:** first-class Effect v4 surface, clean cut from experimental /fp ([#440](https://github.com/camunda/orchestration-cluster-api-js/issues/440)) ([04d2bd1](https://github.com/camunda/orchestration-cluster-api-js/commit/04d2bd1452e9196fb337deb2ecf50b3c5d179bf4)), closes [#437](https://github.com/camunda/orchestration-cluster-api-js/issues/437) [#437](https://github.com/camunda/orchestration-cluster-api-js/issues/437)
+
+
+### BREAKING CHANGES
+
+* **effect:** the experimental `/fp` subpath and its `fp-ts` optional peer are
+removed. Migrate to `./effect` and install the optional `effect` (v4) peer; the
+main `.` entry and its Promise-based API are unchanged.
+
+# [10.0.0-alpha.30](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.29...v10.0.0-alpha.30) (2026-08-20)
+
+
+### Features
+
+* **examples:** add coverage for 7 cluster-admin backup/exporting ops ([#442](https://github.com/camunda/orchestration-cluster-api-js/issues/442)) ([fdc805d](https://github.com/camunda/orchestration-cluster-api-js/commit/fdc805d2877e02b3cb7c89038e05ac9325d76c6a)), closes [#429](https://github.com/camunda/orchestration-cluster-api-js/issues/429) [#441](https://github.com/camunda/orchestration-cluster-api-js/issues/441)
+
+# [10.0.0-alpha.29](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.28...v10.0.0-alpha.29) (2026-08-18)
+
+
+### Features
+
+* add example coverage for restoreAsClusterAdmin, getClusterTopology ([#433](https://github.com/camunda/orchestration-cluster-api-js/issues/433)) ([fab79dc](https://github.com/camunda/orchestration-cluster-api-js/commit/fab79dc97b29c9dcc0c95f30833c832c690a0d6a)), closes [#432](https://github.com/camunda/orchestration-cluster-api-js/issues/432)
+
+# [10.0.0-alpha.28](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.27...v10.0.0-alpha.28) (2026-08-14)
+
+
+### Bug Fixes
+
+* **examples:** group plannedChanges by physical tenant ([d494ce7](https://github.com/camunda/orchestration-cluster-api-js/commit/d494ce716fa83a6ef4d406dd77d9e0ffc0797f35))
+* **examples:** group plannedChanges by physical tenant ([525c176](https://github.com/camunda/orchestration-cluster-api-js/commit/525c1760c6f9fe6f7ef0efb06fd6eefa95f2cc8d))
+
+
+### Features
+
+* **examples:** add cluster admin and history backup example coverage ([185071c](https://github.com/camunda/orchestration-cluster-api-js/commit/185071c9a62eb7d8cf24f903ca36d66342c4e2bf))
+
+# [10.0.0-alpha.27](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.26...v10.0.0-alpha.27) (2026-08-12)
+
+
+### Bug Fixes
+
+* mark agent-definition test scaffolds as todo with void unused local ([5ec2940](https://github.com/camunda/orchestration-cluster-api-js/commit/5ec2940b008314794b3f2a2263fa5f57d07a1ca8))
+* use it.skip instead of it.todo with a callback in test scaffolds ([f96e189](https://github.com/camunda/orchestration-cluster-api-js/commit/f96e189710b86fe4ecc414803d1bed507a89626f))
+
+
+### Features
+
+* add example coverage for getAgentDefinition, searchAgentDefinitions ([e596713](https://github.com/camunda/orchestration-cluster-api-js/commit/e5967130f963939762d6ccf7508fac94e0c2fe76))
+* **examples:** add agent definition examples for getAgentDefinition and searchAgentDefinitions ([d613ac1](https://github.com/camunda/orchestration-cluster-api-js/commit/d613ac1069dbb253c6a91f900cb39ee94cef1eb7))
+
+# [10.0.0-alpha.26](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.25...v10.0.0-alpha.26) (2026-08-10)
+
+
+### Features
+
+* **examples:** add searchOwnAuthorizations example coverage ([a3749c3](https://github.com/camunda/orchestration-cluster-api-js/commit/a3749c392e725957ad22d7627b2161a6a4866165))
+
+# [10.0.0-alpha.25](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.24...v10.0.0-alpha.25) (2026-08-04)
+
+
+### Bug Fixes
+
+* **runtime:** back off job-worker activation retries on transport errors ([#411](https://github.com/camunda/orchestration-cluster-api-js/issues/411)) ([bccaabe](https://github.com/camunda/orchestration-cluster-api-js/commit/bccaabeffc995b30fcb83488538928e57c8de953))
+
+# [10.0.0-alpha.24](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.23...v10.0.0-alpha.24) (2026-08-04)
+
+
+### Bug Fixes
+
+* **client:** reject transport errors regardless of throwOnError ([c1df143](https://github.com/camunda/orchestration-cluster-api-js/commit/c1df143fb001e7b2fb3e928c9c218e52b400a5e1)), closes [#405](https://github.com/camunda/orchestration-cluster-api-js/issues/405)
+* remaining regressions from the @hey-api/openapi-ts 0.86.12 to 0.99.0 upgrade ([37d00cd](https://github.com/camunda/orchestration-cluster-api-js/commit/37d00cd8211af5938fb1ed5ae3320fe25b837a68))
+* **types:** restore discriminators on JobResult and runtime instructions ([dcdf450](https://github.com/camunda/orchestration-cluster-api-js/commit/dcdf450a9ad6182ee6afdd5d5d12ab68b4a19253)), closes [#405](https://github.com/camunda/orchestration-cluster-api-js/issues/405)
+* **validation:** validate path and query params, not just the request body ([5bc2c56](https://github.com/camunda/orchestration-cluster-api-js/commit/5bc2c56d92508cebef7bb43e04494d2f3972679e)), closes [#405](https://github.com/camunda/orchestration-cluster-api-js/issues/405)
+
+# [10.0.0-alpha.23](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.22...v10.0.0-alpha.23) (2026-08-03)
+
+
+### Bug Fixes
+
+* **ci:** align the agent verify gate with the CI gates ([957083c](https://github.com/camunda/orchestration-cluster-api-js/commit/957083c96e14ad9012a5514f59ef0e147a1a4eba))
+* **ci:** fail closed when the verify gate is empty ([35c6f05](https://github.com/camunda/orchestration-cluster-api-js/commit/35c6f059b021a4f688795e21994c9d9bac18da7c))
+* **ci:** stop interpolating the issue body into an unquoted heredoc ([631ee22](https://github.com/camunda/orchestration-cluster-api-js/commit/631ee22057402027b543fe91904c561f2826b303))
+* **ci:** tell the agent which commands actually gate its work ([de6e466](https://github.com/camunda/orchestration-cluster-api-js/commit/de6e4661794c6e3e2d80a7cf72efba76098c13f2))
+
+# [10.0.0-alpha.22](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.21...v10.0.0-alpha.22) (2026-08-02)
+
+
+### Bug Fixes
+
+* **runtime:** reject transport errors instead of silently swallowing them ([#406](https://github.com/camunda/orchestration-cluster-api-js/issues/406)) ([3f84418](https://github.com/camunda/orchestration-cluster-api-js/commit/3f844183442649cfe2a8b8673e3c819b81337553)), closes [#405](https://github.com/camunda/orchestration-cluster-api-js/issues/405)
+
+# [10.0.0-alpha.21](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.20...v10.0.0-alpha.21) (2026-08-02)
+
+
+### Bug Fixes
+
+* **worker:** buffer start() until the transport is ready ([ad4d37f](https://github.com/camunda/orchestration-cluster-api-js/commit/ad4d37f6eeadffb89532af351bd80d404ffc2fde))
+* **worker:** buffer start() until the transport is ready ([708b544](https://github.com/camunda/orchestration-cluster-api-js/commit/708b544f79ffec9ef9060de0dea21ac8ecb2b207)), closes [#401](https://github.com/camunda/orchestration-cluster-api-js/issues/401)
+
+# [10.0.0-alpha.20](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.19...v10.0.0-alpha.20) (2026-08-02)
+
+
+### Bug Fixes
+
+* **runtime:** keep node:worker_threads out of the public type surface ([685ee15](https://github.com/camunda/orchestration-cluster-api-js/commit/685ee15d86982251eb2c02ec3c01d809fc2eb9a9))
+
+# [10.0.0-alpha.19](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.18...v10.0.0-alpha.19) (2026-07-31)
+
+
+### Features
+
+* add example coverage for getClusterStatus, getRestoreStatus ([ef02297](https://github.com/camunda/orchestration-cluster-api-js/commit/ef02297ee69b1da3346457ff12bbc82c12785332))
+* **examples:** add getClusterStatus and getRestoreStatus examples ([b633b00](https://github.com/camunda/orchestration-cluster-api-js/commit/b633b00f71c4960b5620c56bc109cb41c527213e))
+
+# [10.0.0-alpha.18](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.17...v10.0.0-alpha.18) (2026-07-27)
+
+
+### Bug Fixes
+
+* **gen:** derive semantic-key namespace helper types from alias primitive ([8889015](https://github.com/camunda/orchestration-cluster-api-js/commit/8889015ffc6ef4ec826c1379223ae5eb1465a8fd))
+* **gen:** derive semantic-key namespace helper types from alias primitive ([db969a5](https://github.com/camunda/orchestration-cluster-api-js/commit/db969a51a1a334e0ed0cc2e63868aae161c08054))
+
+# [10.0.0-alpha.17](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.16...v10.0.0-alpha.17) (2026-07-27)
+
+
+### Bug Fixes
+
+* **gen:** forward-compatible generation for @hey-api/openapi-ts 0.97 ([ef36a46](https://github.com/camunda/orchestration-cluster-api-js/commit/ef36a4654eedb7bae905bd56a0b4854d6bbe7ebc))
+* **gen:** forward-compatible generation for @hey-api/openapi-ts 0.97 ([47c7713](https://github.com/camunda/orchestration-cluster-api-js/commit/47c77131da1b51dffebd4745913252697169e5ff))
+
+# [10.0.0-alpha.16](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.15...v10.0.0-alpha.16) (2026-07-27)
+
+
+### Bug Fixes
+
+* **gen:** forward-compatible generation hooks for @hey-api/openapi-ts 0.96 ([2025d83](https://github.com/camunda/orchestration-cluster-api-js/commit/2025d8382d1a922c3bacd0ee946a57c551473270))
+* **gen:** forward-compatible generation hooks for @hey-api/openapi-ts 0.96 ([cb1bddd](https://github.com/camunda/orchestration-cluster-api-js/commit/cb1bdddf72eb44abf35dcbc243fac19adbc52013))
+
+# [10.0.0-alpha.15](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.14...v10.0.0-alpha.15) (2026-07-02)
+
+
+### Bug Fixes
+
+* change default CAMUNDA_SDK_LOG_LEVEL from 'error' to 'info' ([839b7ab](https://github.com/camunda/orchestration-cluster-api-js/commit/839b7abb95fee0e7802980802aa1117b2473486c)), closes [#274](https://github.com/camunda/orchestration-cluster-api-js/issues/274)
+
+# [10.0.0-alpha.14](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.13...v10.0.0-alpha.14) (2026-07-01)
+
+
+### Features
+
+* add example coverage for getProcessInstanceWaitStateStatistics ([9fa53ca](https://github.com/camunda/orchestration-cluster-api-js/commit/9fa53ca512a266ed29b23ceec6ccc9199240e4c8)), closes [camunda/orchestration-cluster-api-js#300](https://github.com/camunda/orchestration-cluster-api-js/issues/300)
+
+# [10.0.0-alpha.13](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.12...v10.0.0-alpha.13) (2026-06-28)
+
+
+### Bug Fixes
+
+* **client:** make generated fetch client work on Deno and Bun ([9260000](https://github.com/camunda/orchestration-cluster-api-js/commit/92600004f344a41d7ea5a5158484a98a440c2be3))
+* **client:** sanitize SSE onRequest init and harden the compat hook ([12eff25](https://github.com/camunda/orchestration-cluster-api-js/commit/12eff25fadac6ce45ca28f2c469ccdeb878bf98d))
+
+# [10.0.0-alpha.12](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.11...v10.0.0-alpha.12) (2026-06-18)
+
+
+### Features
+
+* regenerate src/gen for wait-state details union and job priority-updated state ([e0e8c8c](https://github.com/camunda/orchestration-cluster-api-js/commit/e0e8c8c7e30b88799ec17f1c061a21241648ee7d))
+* regenerate src/gen for wait-state details union and job priority-updated state ([76c5f82](https://github.com/camunda/orchestration-cluster-api-js/commit/76c5f829efcf826ff180e3116c4bbf303254c2b6))
+
+# [10.0.0-alpha.11](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.10...v10.0.0-alpha.11) (2026-06-11)
+
+
+### Bug Fixes
+
+* adopt upstream wait-state details union in example ([8f8603c](https://github.com/camunda/orchestration-cluster-api-js/commit/8f8603cd1ed445ab8062c15d525598a5c36084d4))
+* adopt upstream wait-state details union in example ([07ed89c](https://github.com/camunda/orchestration-cluster-api-js/commit/07ed89c0eb2db17f7979ebd57c88983f8561a137))
+
+# [10.0.0-alpha.10](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.9...v10.0.0-alpha.10) (2026-06-09)
+
+
+### Bug Fixes
+
+* apply eventual consistency only to first searchVariablesAsDto search ([29387b0](https://github.com/camunda/orchestration-cluster-api-js/commit/29387b0b478e0c9a4d1dd0eaaf82c0481be5ddd8))
+* **deps:** bump camunda-schema-bundler to 2.4.3 for IterationId generation ([16a7c5d](https://github.com/camunda/orchestration-cluster-api-js/commit/16a7c5ddccc52b60b0dab3efc6048daaba687013))
+* **deps:** bump camunda-schema-bundler to 2.4.3 for IterationId generation ([8a8cdae](https://github.com/camunda/orchestration-cluster-api-js/commit/8a8cdae5fe9327a991e9670e4aeb50c6d8591356))
+* wait for all declared variables at the collection level for searchVariablesAsDto ([ba2f911](https://github.com/camunda/orchestration-cluster-api-js/commit/ba2f911e1d6254d25ac68c3ebfaa690ef0d9067a))
+
+
+### Features
+
+* add searchVariablesAsDto for DTO-driven typed variable maps ([52a544f](https://github.com/camunda/orchestration-cluster-api-js/commit/52a544fcc37f7ecc86fcfa153859baf6cf653b9b))
+* add searchVariablesAsDto for DTO-driven typed variable maps ([67418f2](https://github.com/camunda/orchestration-cluster-api-js/commit/67418f2f9ccbdc8b535b82cb8a66ec77b66143e0))
+
+# [10.0.0-alpha.9](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.8...v10.0.0-alpha.9) (2026-06-04)
+
+
+### Bug Fixes
+
+* pass author-association to community notification workflow ([82e7f6e](https://github.com/camunda/orchestration-cluster-api-js/commit/82e7f6e5b34c60d122b93a302c84dda1fc28f6f9))
+
+# [10.0.0-alpha.8](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.7...v10.0.0-alpha.8) (2026-06-04)
+
+
+### Features
+
+* add Slack notifications for release failures and community events ([051e782](https://github.com/camunda/orchestration-cluster-api-js/commit/051e78230ce2a2eeda53bdc604a99a783e4b5caa))
+* add Slack notifications for release failures and community events ([2981264](https://github.com/camunda/orchestration-cluster-api-js/commit/29812649034d2e961d65a7a80bd8bb2590e77dc1))
+
+# [10.0.0-alpha.7](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.6...v10.0.0-alpha.7) (2026-05-18)
+
+
+### Bug Fixes
+
+* update docker-compose env vars for 8.10 config schema ([d343d56](https://github.com/camunda/orchestration-cluster-api-js/commit/d343d56a54d6b83246e3a2b26b6ce2469c2de77c))
+
+# [10.0.0-alpha.6](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.5...v10.0.0-alpha.6) (2026-05-13)
+
+
+### Features
+
+* add example coverage for 4 new operations ([3a2c875](https://github.com/camunda/orchestration-cluster-api-js/commit/3a2c87577bcca87996cc77546216c68fb5124ec5))
+* add example coverage for 4 new operations ([6d757a4](https://github.com/camunda/orchestration-cluster-api-js/commit/6d757a4be85ba733f07bcd08c1b6ae33aacd6c15))
+
+# [10.0.0-alpha.5](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.4...v10.0.0-alpha.5) (2026-05-08)
+
+
+### Features
+
+* add agent instance example coverage ([8a0072d](https://github.com/camunda/orchestration-cluster-api-js/commit/8a0072d03cf426ea895863d7cbdd87178c2e7e2f))
+* v10 migration — bundler 2.4.1, branded type examples, README ([dd4a714](https://github.com/camunda/orchestration-cluster-api-js/commit/dd4a7149682b89d1f8f9c0f627dfef5645b10ea7)), closes [#203](https://github.com/camunda/orchestration-cluster-api-js/issues/203) [#204](https://github.com/camunda/orchestration-cluster-api-js/issues/204)
+
+# [10.0.0-alpha.4](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.3...v10.0.0-alpha.4) (2026-04-29)
+
+
+### Bug Fixes
+
+* **gen:** apply CAMUNDA_DEFAULT_TENANT_ID to activateJobs tenantIds ([fb7c661](https://github.com/camunda/orchestration-cluster-api-js/commit/fb7c661ba1f24dcfcfd738c6e344df09a2e2c52d))
+
 # [10.0.0-alpha.3](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.2...v10.0.0-alpha.3) (2026-04-29)
 
 

package/README.md

@@ -149,10 +149,51 @@ await camunda.createDeployment({
 });
 ```
 
-`TenantId.assumeExists()` validates the string against the tenant ID pattern and brands it at zero runtime cost. See [Branded Keys](#branded-keys) for more on this pattern.
+`TenantId.assumeExists()` validates the string against the tenant ID pattern and returns a branded value. The branded value is just a string at runtime, but `assumeExists()` performs validation and can throw if the input is malformed. See [Branded Keys](#branded-keys) for more on this pattern.
 
 > **Tip**: If your tenant ID comes from a validated source (environment variable, config file), call `TenantId.assumeExists()` once at startup and pass the branded value throughout your application.
 
+## 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.
+
+### New branded types
+
+| 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
+
+<!-- snippet-source: examples/readme.ts | regions: V9ToV10Migration -->
+
+```ts
+// v9 — plain strings were accepted
+// await camunda.assignRoleToGroup({
+//   roleId: 'developer',
+//   groupId: 'engineering',
+// });
+
+// v10 — use the branded type helpers at the boundary
+await camunda.assignRoleToGroup({
+  roleId: RoleId.assumeExists('developer'),
+  groupId: GroupId.assumeExists('engineering'),
+});
+```
+
+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.
@@ -576,6 +617,41 @@ Benchmark results against a single-node local cluster with multiple independent
 
 BALANCED wins 3 of 4 on pure throughput. The only scenario where LEGACY is faster is extreme overload (800 concurrent requests against a single broker) — and in that case LEGACY accumulates 44,505 errors vs BALANCED's 15,527. The default just works.
 
+## Typed Variable Map (DTO-driven search)
+
+`searchVariablesAsDto` fetches process variables and binds them to a [Zod](https://zod.dev) schema that acts as the DTO. The schema's keys are the exact variable names to fetch, and its shape drives validation. Only the declared variables are queried (via a `name $in [...]` filter), so memory stays bound by the DTO shape rather than the total number of variables on the instance. Results are paged internally until every declared variable is found or the result set is exhausted.
+
+The returned `VariableMap` offers two access modes:
+
+- **Lenient** — `has(name)` / `get(name)` for defensive reads that never throw on missing variables.
+- **Strict** — `validate()` returns a fully-typed object, or throws a `ZodError` when a required variable is missing or malformed.
+
+If a declared variable is found at more than one scope (for example a local variable shadowing a process-level one), the search throws a `VariableScopeCollisionError` rather than silently picking one. Pass an explicit `scopeKey` to disambiguate.
+
+<!-- snippet-source: examples/readme.ts | regions: ReadmeTypedVariables -->
+
+```ts
+// The Zod schema is the DTO: its keys are the variable names to fetch, and its
+// shape drives validation. Only these declared variables are queried, so memory
+// stays bound by the DTO — not by the total number of variables on the instance.
+const OrderVariables = z.object({
+  orderId: z.string(), // required
+  amount: z.number().optional(), // optional
+});
+
+const map = await camunda.searchVariablesAsDto(OrderVariables, { processInstanceKey });
+
+// Lenient access: defensive reads that never throw on missing variables.
+if (map.has('amount')) {
+  console.log('Amount:', map.get('amount'));
+}
+
+// Strict access: returns a fully-typed object, or throws a ZodError when a
+// required variable is missing or malformed.
+const order = map.validate(); // { orderId: string; amount?: number }
+console.log('Order:', order.orderId);
+```
+
 ## Job Workers (Polling API)
 
 The SDK provides a lightweight polling job worker for service task job types using `createJobWorker`. It activates jobs in batches (respecting a concurrency limit), validates variables (optional), and offers action helpers on each job.
@@ -681,6 +757,7 @@ Example patterns:
 return job.complete({ variables: { processed: true } });
 
 // GOOD: No-arg completion example, sentinel stored for ultimate return
+// biome-ignore lint/correctness/noUnreachable: intentional — showing multiple completion patterns
 const ack = await job.complete();
 // ...
 return ack;
@@ -1173,67 +1250,92 @@ Notes:
 - Cancellation classification runs first so aborted fetches are never downgraded to generic network errors.
 - Abort is immediate and idempotent; underlying fetch is signalled.
 
-## Functional (fp-ts style) Surface (Opt-In Subpath)
+## Effect Surface (Opt-In Subpath)
 
-@experimental - this feature is not guaranteed to be tested or stable.
+The main entry stays Promise-based and pulls in **zero** Effect at runtime. Opt in to a
+first-class [Effect](https://effect.website) surface — a client whose every method returns an
+`Effect`, tagged domain errors, and Effect-native combinators — by importing the dedicated
+`./effect` subpath.
 
-> **Peer dependency:** `fp-ts` is an optional peer dependency. If you use real `fp-ts` functions
-> (e.g. `pipe`, `TE.match`) alongside this subpath, install it separately:
+> **Peer dependency:** `effect` is an **optional peer dependency** (Effect **v4**). The `./effect`
+> subpath requires it; install it alongside the SDK:
 > ```sh
-> npm install fp-ts
+> npm install effect
 > ```
-> The `/fp` subpath works without `fp-ts` installed — it exposes structurally-compatible
-> `Either`/`TaskEither` shapes that interoperate with `fp-ts` but do not require it at runtime.
-
-The main entry stays minimal. To opt in to a TaskEither-style facade & helper combinators import from the dedicated subpath:
+> The main `.` entry never imports `effect`, so Promise-first users are never forced to adopt it.
+>
+> **Module resolution:** Effect v4 ships as an `exports`-map-only package (no legacy
+> `main`/`types`), so consuming the `./effect` types requires a modern TypeScript module
+> resolution — set `"moduleResolution": "bundler"` (or `"node16"`/`"nodenext"`) in your
+> `tsconfig.json`. The Promise-first `.` entry is unaffected.
 
-<!-- snippet-exempt: uses SDK /fp subpath not available in examples project -->
+<!-- snippet-exempt: uses SDK /effect subpath + optional effect peer not available in examples project -->
 ```ts
+import { Effect } from 'effect';
 import {
-  createCamundaFpClient,
-  retryTE,
-  withTimeoutTE,
-  eventuallyTE,
-  isLeft,
-} from '@camunda8/orchestration-cluster-api/fp';
-
-const fp = createCamundaFpClient();
-const deployTE = fp.deployResourcesFromFiles(['./bpmn/process.bpmn']);
-const deployed = await deployTE();
-if (isLeft(deployed)) throw deployed.left; // DomainError union
+  createCamundaEffectClient,
+  eventually,
+  EventualConsistencyTimeout,
+} from '@camunda8/orchestration-cluster-api/effect';
+
+const camunda = createCamundaEffectClient();
+
+const program = Effect.gen(function* () {
+  const deployment = yield* camunda.deployResourcesFromFiles(['./bpmn/process.bpmn']);
+  const { processInstanceKey } = yield* camunda.createProcessInstance({
+    processDefinitionKey: deployment.processes[0].processDefinitionKey,
+  });
+  // Poll on the Effect Clock until the instance is searchable, timing out deterministically.
+  // waitUpToMs: 0 asks the SDK for the latest available state without its own wall-clock
+  // wait, so the Effect `eventually` combinator owns the predicate + timeout horizon —
+  // making the eventual-consistency wait deterministic under TestClock.
+  const search = yield* eventually(
+    camunda.searchProcessInstances(
+      { filter: { processInstanceKey } },
+      { consistency: { waitUpToMs: 0 } }
+    ),
+    (s) => s.items.some((i) => i.processInstanceKey === processInstanceKey),
+    { waitUpTo: '30 seconds', interval: '750 millis' }
+  );
+  return { processInstanceKey, search };
+}).pipe(
+  // Tagged errors → discriminate with catchTag / catchTags instead of a manual switch.
+  Effect.catchTag('EventualConsistencyTimeout', (e: EventualConsistencyTimeout) =>
+    Effect.logError(`Timed out: ${e.message}`).pipe(Effect.andThen(Effect.fail(e)))
+  )
+);
 
-// Chain with fp-ts (optional) – the returned thunks are structurally compatible with TaskEither
-// import { pipe } from 'fp-ts/function'; import * as TE from 'fp-ts/TaskEither';
+const result = await Effect.runPromise(program);
 ```
 
 Why a subpath?
 
-- Keeps base bundle lean for the 80% use case.
-- No hard dependency on `fp-ts` at runtime; only structural types.
-- Advanced users can compose with real `fp-ts` without pulling the effect model into the default import path.
+- Keeps the base bundle lean for the Promise-first 80% use case.
+- No dependency on `effect` at runtime unless you opt in; it is an **optional** peer.
+- Unlocks the Effect ecosystem (typed errors, `Schedule`, `Layer`/`Context`, `TestClock`).
 
-Exports available from `.../fp`:
+Exports available from `.../effect`:
 
-- `createCamundaFpClient` – typed facade (methods return `() => Promise<Either<DomainError,T>>`).
-- Type guards: `isLeft`, `isRight`.
-- Error / type aliases: `DomainError`, `TaskEither`, `Either`, `Left`, `Right`, `Fpify`.
-- Combinators: `retryTE`, `withTimeoutTE`, `eventuallyTE`.
+- `createCamundaEffectClient(options?)` – a `Proxy` client where every method returns
+  `Effect.Effect<Awaited<R>, DomainError, never>`; the throwing client is reachable via `.inner`.
+- Tagged errors (`Data.TaggedError`): `CamundaValidationError`, `EventualConsistencyTimeout`,
+  `HttpError`, `CamundaGenericError` — together the `DomainError` union. Discriminate with
+  `Effect.catchTag` / `Effect.catchTags`.
+- Combinators: `retryWithBackoff` (`Effect.retry` + `Schedule.exponential` + jitter), `withTimeout`
+  (`Effect.timeoutOrElse` with real interruption), `eventually` (a recursive `Effect.sleep` poll on
+  the Effect `Clock`, timing out to `EventualConsistencyTimeout`).
+- Dependency injection: `CamundaEffect` (`Context.Service`) + `layer(options?)` (`Layer`) so worker /
+  orchestration code composes via `Layer` and swaps a test double trivially.
 
-DomainError union currently includes:
-
-- `CamundaValidationError`
-- `EventualConsistencyTimeoutError`
-- HTTP-like error objects (status/body/message) produced by transport
-- Generic `Error`
-
-You can refine left-channel typing later by mapping HTTP status codes or discriminator fields.
+**Clock-class win:** `eventually` / `withTimeout` run on the Effect `Clock`, so `TestClock.adjust`
+advances eventual/timeout deterministically in tests — no real-clock burn.
 
 ## Eventual Consistency Polling
 
 Some endpoints accept consistency management options. Pass a `consistency` block (where supported) with `waitUpToMs` and optional `pollIntervalMs` (default 500). If the condition is not met within timeout an `EventualConsistencyTimeoutError` is thrown.
 
 To consume eventual polling in a non‑throwing fashion set the client error mode before invoking an eventually consistent method:
-At present the canonical client operates in throwing mode. Non‑throwing adaptation (Result / fp-ts) is achieved via the functional wrappers rather than mutating the base client.
+At present the canonical client operates in throwing mode. Non‑throwing adaptation (Result / Effect) is achieved via the functional wrappers rather than mutating the base client.
 
 ### Options
 
@@ -1512,43 +1614,32 @@ When to use:
 - Avoiding try/catch nesting in larger orchestration flows.
 - Converting to libraries expecting an Either/Result pattern.
 
-### fp-ts Adapter (TaskEither / Either) - EXPERIMENTAL
-
-_Note that this feature is experimental and subject to change._
+### Effect Adapter
 
-For projects using `fp-ts`, wrap the throwing client in a lazy `TaskEither` facade:
+For Effect-based projects, wrap the throwing client in an Effect-flavoured facade whose every method
+returns an `Effect` with a typed `DomainError` channel:
 
-<!-- snippet-exempt: requires external fp-ts dependency -->
+<!-- snippet-exempt: requires optional effect peer dependency -->
 ```ts
-import { createCamundaFpClient } from '@camunda8/orchestration-cluster-api/fp';
-import { pipe } from 'fp-ts/function';
-import * as TE from 'fp-ts/TaskEither';
+import { Effect } from 'effect';
+import { createCamundaEffectClient } from '@camunda8/orchestration-cluster-api/effect';
 
-const fp = createCamundaFpClient();
+const camunda = createCamundaEffectClient();
 
-const deployTE = fp.createDeployment({ resources: [file] }); // TaskEither<unknown, ExtendedDeploymentResult>
-
-pipe(
-  deployTE(), // invoke the task (returns Promise<Either>)
-  (then) => then // typical usage would use TE.match / TE.fold; shown expanded for clarity
+const deployment = await Effect.runPromise(
+  camunda.createDeployment({ resources: [file] })
 );
-
-// With helpers
-const task = fp.createDeployment({ resources: [file] });
-const either = await task();
-if (either._tag === 'Right') {
-  console.log(either.right.deployments.length);
-} else {
-  console.error('Error', either.left);
-}
+console.log(deployment.deployments.length);
 ```
 
+See [Effect Surface (Opt-In Subpath)](#effect-surface-opt-in-subpath) above for the full surface —
+tagged errors, `retryWithBackoff` / `withTimeout` / `eventually`, and `Layer`/`Context` DI.
+
 Notes:
 
-- No runtime dependency on `fp-ts`; adapter implements a minimal `Either` shape. Structural typing lets you lift into real `fp-ts` functions (`fromEither`, etc.).
-- Each method becomes a function returning `() => Promise<Either<E,A>>` (a `TaskEither` shape). Invoke it later to execute.
-- Cancellation: calling `.cancel()` on the original promise isn’t surfaced; if you need cancellation use the base client directly.
-- For richer interop, you can map the returned factory to `TE.tryCatch` in userland.
+- `effect` is an **optional peer dependency**; only the `./effect` subpath imports it.
+- Each method returns `Effect.Effect<Awaited<R>, DomainError, never>`; the throwing client is reachable via `.inner`.
+- Failures are narrowed into tagged errors so you discriminate with `Effect.catchTag` / `catchTags`.
 
 ## Pagination
 
@@ -1671,7 +1762,7 @@ Generate an HTML API reference site with TypeDoc (public entry points only):
 npm run docs:api
 ```
 
-Output: static site in `docs/api` (open `docs/api/index.html` in a browser or serve the folder, e.g. `npx http-server docs/api`). Entry points: `src/index.ts`, `src/logger.ts`, `src/fp/index.ts`. Internal generated code, scripts, tests are excluded and private / protected members are filtered. Regenerate after changing public exports.
+Output: static site in `docs/api` (open `docs/api/index.html` in a browser or serve the folder, e.g. `npx http-server docs/api`). Entry points: `src/index.ts`, `src/logger.ts`, `src/effect/index.ts`. Internal generated code, scripts, tests are excluded and private / protected members are filtered. Regenerate after changing public exports.
 
 ## Contributing