@nanobpm/nano-sdk 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1,10 +1,77 @@
 import { JobActionReceiptSymbol, createCamundaClient as createCamundaClient$1 } from '@camunda8/orchestration-cluster-api';
 export * from '@camunda8/orchestration-cluster-api';
 
+/** A job handed to a worker handler. */
+interface EmbeddedJob {
+    jobKey: string;
+    type: string;
+    processInstanceKey: string;
+    elementId: string;
+    retries: number;
+    variables: Record<string, unknown>;
+}
+/** The engine bridge an embedded app supplies (implemented by the app template's
+ *  Deno host around μ-nano.wasm). Engine-core stays clock-free; the host injects now(). */
+interface EmbeddedHost {
+    deploy(xml: string): Promise<{
+        processIds: string[];
+    }>;
+    createInstance(input: {
+        processDefinitionId?: string;
+        variables?: Record<string, unknown>;
+    }): Promise<{
+        processInstanceKey: string;
+    }>;
+    activateJobs(type: string, max: number, timeoutMs: number, worker: string): Promise<EmbeddedJob[]>;
+    completeJob(jobKey: string, variables?: Record<string, unknown>): Promise<void>;
+    failJob(jobKey: string, retries: number, errorMessage?: string): Promise<void>;
+    instanceCompleted(key: string): boolean;
+    instanceVariables(key: string): Record<string, unknown>;
+    /** Drive timers + dispatch at wall-clock now. Returns true if anything changed. */
+    tick(): void;
+}
+/** Pull-based dispatch over an in-process host. Structurally compatible with the
+ *  FalconTransport surface used by NanoJobWorker + the client proxy. */
+declare class EmbeddedTransport {
+    private host;
+    private pollMs;
+    private subs;
+    private timer;
+    private closed;
+    constructor(host: EmbeddedHost, pollMs?: number);
+    createInstance(input: {
+        processDefinitionId?: string;
+        variables?: Record<string, unknown>;
+        awaitCompletion?: boolean;
+    }): Promise<{
+        status: number;
+        body: unknown;
+        completion?: {
+            processCompleted: boolean;
+            variables: unknown;
+            processInstanceKey: string;
+        };
+    }>;
+    subscribe(sub: {
+        jobType: string;
+        worker: string;
+        credits: number;
+        timeoutMs: number;
+        onJob: (j: any) => void;
+    }): Promise<void>;
+    unsubscribe(jobType: string): void;
+    completeJob(jobKey: string, variables?: Record<string, unknown>): void;
+    failJob(jobKey: string, retries?: number, errorMessage?: string): void;
+    throwError(jobKey: string, _errorCode: string, errorMessage?: string): void;
+    grantCredits(jobType: string, n: number): void;
+    private pump;
+    close(): void;
+}
+
 interface NanoInfo {
     engine: string;
     version?: string;
-    commandStreamPath: string;
+    falconPath: string;
 }
 /**
  * Probes a REST address once (cached) and returns the Nano engine info if the
@@ -29,7 +96,19 @@ interface Subscription {
     fetchVariables: string[] | null;
     onJob: (job: JobFrame) => void;
 }
-declare class CommandStreamTransport {
+/**
+ * Thrown by {@link FalconTransport.createInstance} when the gateway does
+ * not acknowledge a create within `submitTimeoutMs`. On the Falcon protocol,
+ * admission backpressure is expressed by the server withholding submission
+ * credits (no `503`, no retry), so a create otherwise waits indefinitely for
+ * intake capacity. This turns that stall into a typed rejection — treat it as
+ * "the server is backpressured" and back off; do not tight-loop retry.
+ */
+declare class SubmissionTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+declare class FalconTransport {
     private url;
     private ws;
     private open;
@@ -40,13 +119,29 @@ declare class CommandStreamTransport {
     private heartbeat;
     private connectPromise;
     private closed;
-    constructor(restAddress: string, path: string);
+    private defaultSubmitTimeoutMs?;
+    /**
+     * Server-granted submission-credit window (seeded by `welcome`, topped up by
+     * `submissionCredits`). Mirrors the engine's intake metering so creates queue
+     * client-side under admission backpressure instead of flooding the gateway.
+     */
+    private credits;
+    private creditWaiters;
+    constructor(restAddress: string, path: string, defaultSubmitTimeoutMs?: number);
     private nextCorr;
     private send;
     connect(): Promise<void>;
     private reconnect;
     private handle;
     private sendSubscribe;
+    /**
+     * Take one submission credit, waiting for the gateway to replenish when the
+     * window is exhausted (admission backpressure — no 503, no retry). When
+     * `timeoutMs` elapses first, rejects with {@link SubmissionTimeoutError} and
+     * removes the queued waiter so no credit slot leaks.
+     */
+    private acquireCredit;
+    private releaseCreditWaiters;
     /** Create a process instance over the stream. */
     createInstance(input: {
         processDefinitionId?: string;
@@ -55,6 +150,13 @@ declare class CommandStreamTransport {
         awaitCompletion?: boolean;
         fetchVariables?: string[];
         requestTimeoutMs?: number;
+        /**
+         * Client-side bound (ms) on how long to wait for a submission credit before
+         * rejecting with {@link SubmissionTimeoutError}. Overrides the transport-wide
+         * default. Omit to wait indefinitely under backpressure. Never sent on the
+         * wire — the server is unaware of it.
+         */
+        submitTimeoutMs?: number;
     }): Promise<{
         status: number;
         body: unknown;
@@ -90,9 +192,9 @@ declare class NanoJobWorker {
     private stopped;
     readonly jobType: string;
     readonly name: string;
-    constructor(transport: CommandStreamTransport, cfg: NanoJobWorkerConfig);
+    constructor(transport: FalconTransport, cfg: NanoJobWorkerConfig);
     /** Bind the transport after async Nano detection. */
-    bindTransport(transport: CommandStreamTransport): void;
+    bindTransport(transport: FalconTransport): void;
     start(): Promise<void>;
     private enrich;
     private dispatch;
@@ -100,20 +202,23 @@ declare class NanoJobWorker {
     close(): void;
 }
 
-/** auto: upgrade only on Nano. command-stream: force. rest: never upgrade. */
-type NanoTransport = "auto" | "command-stream" | "rest";
+/** auto: upgrade only on Nano. falcon: force. rest: never upgrade. embedded: in-process μ-nano. */
+type NanoTransport = "auto" | "falcon" | "rest" | "embedded";
 type AnyOpts = Parameters<typeof createCamundaClient$1>[0] & {
     config?: Record<string, unknown> & {
         CAMUNDA_TRANSPORT?: NanoTransport;
         CAMUNDA_REST_ADDRESS?: string;
+        CAMUNDA_NANO_SUBMIT_TIMEOUT_MS?: string | number;
     };
+    /** Embedded (ADR 0005) in-process engine host; required when transport is "embedded". */
+    embeddedHost?: EmbeddedHost;
 };
 /**
  * Drop-in replacement for the upstream createCamundaClient. Returns the upstream
  * client wrapped in a Proxy that upgrades createProcessInstance + createJobWorker
- * to the command stream when connected to a Nano server (overridable via the
- * CAMUNDA_TRANSPORT config: "auto" | "command-stream" | "rest").
+ * to the Falcon protocol when connected to a Nano server (overridable via the
+ * CAMUNDA_TRANSPORT config: "auto" | "falcon" | "rest").
  */
 declare function createCamundaClient(opts?: AnyOpts): ReturnType<typeof createCamundaClient$1>;
 
-export { CommandStreamTransport, type NanoInfo, NanoJobWorker, type NanoTransport, createCamundaClient, createCamundaClient as default, detectNano };
+export { type EmbeddedHost, type EmbeddedJob, EmbeddedTransport, FalconTransport, type NanoInfo, NanoJobWorker, type NanoTransport, SubmissionTimeoutError, createCamundaClient, createCamundaClient as default, detectNano };

package/dist/index.d.ts

@@ -1,10 +1,77 @@
 import { JobActionReceiptSymbol, createCamundaClient as createCamundaClient$1 } from '@camunda8/orchestration-cluster-api';
 export * from '@camunda8/orchestration-cluster-api';
 
+/** A job handed to a worker handler. */
+interface EmbeddedJob {
+    jobKey: string;
+    type: string;
+    processInstanceKey: string;
+    elementId: string;
+    retries: number;
+    variables: Record<string, unknown>;
+}
+/** The engine bridge an embedded app supplies (implemented by the app template's
+ *  Deno host around μ-nano.wasm). Engine-core stays clock-free; the host injects now(). */
+interface EmbeddedHost {
+    deploy(xml: string): Promise<{
+        processIds: string[];
+    }>;
+    createInstance(input: {
+        processDefinitionId?: string;
+        variables?: Record<string, unknown>;
+    }): Promise<{
+        processInstanceKey: string;
+    }>;
+    activateJobs(type: string, max: number, timeoutMs: number, worker: string): Promise<EmbeddedJob[]>;
+    completeJob(jobKey: string, variables?: Record<string, unknown>): Promise<void>;
+    failJob(jobKey: string, retries: number, errorMessage?: string): Promise<void>;
+    instanceCompleted(key: string): boolean;
+    instanceVariables(key: string): Record<string, unknown>;
+    /** Drive timers + dispatch at wall-clock now. Returns true if anything changed. */
+    tick(): void;
+}
+/** Pull-based dispatch over an in-process host. Structurally compatible with the
+ *  FalconTransport surface used by NanoJobWorker + the client proxy. */
+declare class EmbeddedTransport {
+    private host;
+    private pollMs;
+    private subs;
+    private timer;
+    private closed;
+    constructor(host: EmbeddedHost, pollMs?: number);
+    createInstance(input: {
+        processDefinitionId?: string;
+        variables?: Record<string, unknown>;
+        awaitCompletion?: boolean;
+    }): Promise<{
+        status: number;
+        body: unknown;
+        completion?: {
+            processCompleted: boolean;
+            variables: unknown;
+            processInstanceKey: string;
+        };
+    }>;
+    subscribe(sub: {
+        jobType: string;
+        worker: string;
+        credits: number;
+        timeoutMs: number;
+        onJob: (j: any) => void;
+    }): Promise<void>;
+    unsubscribe(jobType: string): void;
+    completeJob(jobKey: string, variables?: Record<string, unknown>): void;
+    failJob(jobKey: string, retries?: number, errorMessage?: string): void;
+    throwError(jobKey: string, _errorCode: string, errorMessage?: string): void;
+    grantCredits(jobType: string, n: number): void;
+    private pump;
+    close(): void;
+}
+
 interface NanoInfo {
     engine: string;
     version?: string;
-    commandStreamPath: string;
+    falconPath: string;
 }
 /**
  * Probes a REST address once (cached) and returns the Nano engine info if the
@@ -29,7 +96,19 @@ interface Subscription {
     fetchVariables: string[] | null;
     onJob: (job: JobFrame) => void;
 }
-declare class CommandStreamTransport {
+/**
+ * Thrown by {@link FalconTransport.createInstance} when the gateway does
+ * not acknowledge a create within `submitTimeoutMs`. On the Falcon protocol,
+ * admission backpressure is expressed by the server withholding submission
+ * credits (no `503`, no retry), so a create otherwise waits indefinitely for
+ * intake capacity. This turns that stall into a typed rejection — treat it as
+ * "the server is backpressured" and back off; do not tight-loop retry.
+ */
+declare class SubmissionTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+declare class FalconTransport {
     private url;
     private ws;
     private open;
@@ -40,13 +119,29 @@ declare class CommandStreamTransport {
     private heartbeat;
     private connectPromise;
     private closed;
-    constructor(restAddress: string, path: string);
+    private defaultSubmitTimeoutMs?;
+    /**
+     * Server-granted submission-credit window (seeded by `welcome`, topped up by
+     * `submissionCredits`). Mirrors the engine's intake metering so creates queue
+     * client-side under admission backpressure instead of flooding the gateway.
+     */
+    private credits;
+    private creditWaiters;
+    constructor(restAddress: string, path: string, defaultSubmitTimeoutMs?: number);
     private nextCorr;
     private send;
     connect(): Promise<void>;
     private reconnect;
     private handle;
     private sendSubscribe;
+    /**
+     * Take one submission credit, waiting for the gateway to replenish when the
+     * window is exhausted (admission backpressure — no 503, no retry). When
+     * `timeoutMs` elapses first, rejects with {@link SubmissionTimeoutError} and
+     * removes the queued waiter so no credit slot leaks.
+     */
+    private acquireCredit;
+    private releaseCreditWaiters;
     /** Create a process instance over the stream. */
     createInstance(input: {
         processDefinitionId?: string;
@@ -55,6 +150,13 @@ declare class CommandStreamTransport {
         awaitCompletion?: boolean;
         fetchVariables?: string[];
         requestTimeoutMs?: number;
+        /**
+         * Client-side bound (ms) on how long to wait for a submission credit before
+         * rejecting with {@link SubmissionTimeoutError}. Overrides the transport-wide
+         * default. Omit to wait indefinitely under backpressure. Never sent on the
+         * wire — the server is unaware of it.
+         */
+        submitTimeoutMs?: number;
     }): Promise<{
         status: number;
         body: unknown;
@@ -90,9 +192,9 @@ declare class NanoJobWorker {
     private stopped;
     readonly jobType: string;
     readonly name: string;
-    constructor(transport: CommandStreamTransport, cfg: NanoJobWorkerConfig);
+    constructor(transport: FalconTransport, cfg: NanoJobWorkerConfig);
     /** Bind the transport after async Nano detection. */
-    bindTransport(transport: CommandStreamTransport): void;
+    bindTransport(transport: FalconTransport): void;
     start(): Promise<void>;
     private enrich;
     private dispatch;
@@ -100,20 +202,23 @@ declare class NanoJobWorker {
     close(): void;
 }
 
-/** auto: upgrade only on Nano. command-stream: force. rest: never upgrade. */
-type NanoTransport = "auto" | "command-stream" | "rest";
+/** auto: upgrade only on Nano. falcon: force. rest: never upgrade. embedded: in-process μ-nano. */
+type NanoTransport = "auto" | "falcon" | "rest" | "embedded";
 type AnyOpts = Parameters<typeof createCamundaClient$1>[0] & {
     config?: Record<string, unknown> & {
         CAMUNDA_TRANSPORT?: NanoTransport;
         CAMUNDA_REST_ADDRESS?: string;
+        CAMUNDA_NANO_SUBMIT_TIMEOUT_MS?: string | number;
     };
+    /** Embedded (ADR 0005) in-process engine host; required when transport is "embedded". */
+    embeddedHost?: EmbeddedHost;
 };
 /**
  * Drop-in replacement for the upstream createCamundaClient. Returns the upstream
  * client wrapped in a Proxy that upgrades createProcessInstance + createJobWorker
- * to the command stream when connected to a Nano server (overridable via the
- * CAMUNDA_TRANSPORT config: "auto" | "command-stream" | "rest").
+ * to the Falcon protocol when connected to a Nano server (overridable via the
+ * CAMUNDA_TRANSPORT config: "auto" | "falcon" | "rest").
  */
 declare function createCamundaClient(opts?: AnyOpts): ReturnType<typeof createCamundaClient$1>;
 
-export { CommandStreamTransport, type NanoInfo, NanoJobWorker, type NanoTransport, createCamundaClient, createCamundaClient as default, detectNano };
+export { type EmbeddedHost, type EmbeddedJob, EmbeddedTransport, FalconTransport, type NanoInfo, NanoJobWorker, type NanoTransport, SubmissionTimeoutError, createCamundaClient, createCamundaClient as default, detectNano };

package/dist/index.js

@@ -19,11 +19,11 @@ async function detectNano(restAddress, fetchImpl = fetch) {
     if (res.ok) {
       const body = await res.json().catch(() => ({}));
       const nano = body?.nano;
-      if (nano && typeof nano.commandStreamPath === "string") {
+      if (nano && typeof nano.falconPath === "string") {
         info = {
           engine: String(nano.engine ?? "nanobpmn"),
           version: nano.version ? String(nano.version) : void 0,
-          commandStreamPath: nano.commandStreamPath
+          falconPath: nano.falconPath
         };
       }
     }
@@ -33,7 +33,7 @@ async function detectNano(restAddress, fetchImpl = fetch) {
   cache.set(base, info);
   return info;
 }
-function commandStreamUrl(restAddress, path) {
+function falconUrl(restAddress, path) {
   let base = normalizeBase(restAddress);
   if (base.startsWith("https://")) base = "wss://" + base.slice("https://".length);
   else if (base.startsWith("http://")) base = "ws://" + base.slice("http://".length);
@@ -55,7 +55,17 @@ async function getWebSocket() {
 }
 
 // src/transport.ts
-var CommandStreamTransport = class {
+var SubmissionTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(
+      `create submission stalled: no gateway ack within ${timeoutMs}ms (server is applying admission backpressure)`
+    );
+    this.timeoutMs = timeoutMs;
+    this.name = "SubmissionTimeoutError";
+  }
+  timeoutMs;
+};
+var FalconTransport = class {
   url;
   ws = null;
   open = false;
@@ -66,8 +76,17 @@ var CommandStreamTransport = class {
   heartbeat = null;
   connectPromise = null;
   closed = false;
-  constructor(restAddress, path) {
-    this.url = commandStreamUrl(restAddress, path);
+  defaultSubmitTimeoutMs;
+  /**
+   * Server-granted submission-credit window (seeded by `welcome`, topped up by
+   * `submissionCredits`). Mirrors the engine's intake metering so creates queue
+   * client-side under admission backpressure instead of flooding the gateway.
+   */
+  credits = 0;
+  creditWaiters = [];
+  constructor(restAddress, path, defaultSubmitTimeoutMs) {
+    this.url = falconUrl(restAddress, path);
+    this.defaultSubmitTimeoutMs = defaultSubmitTimeoutMs !== void 0 && defaultSubmitTimeoutMs > 0 ? defaultSubmitTimeoutMs : void 0;
   }
   nextCorr() {
     this.corr += 1;
@@ -95,12 +114,16 @@ var CommandStreamTransport = class {
           this.handle(f, resolve);
         };
         ws.onerror = () => {
-          if (!this.open) reject(new Error(`command-stream connect failed: ${this.url}`));
+          if (!this.open) reject(new Error(`falcon connect failed: ${this.url}`));
         };
         ws.onclose = () => {
           this.open = false;
+          this.credits = 0;
+          const waiters = this.creditWaiters;
+          this.creditWaiters = [];
+          for (const w of waiters) w.fail(new Error("falcon closed"));
           if (this.heartbeat) clearInterval(this.heartbeat);
-          for (const p of this.pending.values()) p.reject(new Error("command-stream closed"));
+          for (const p of this.pending.values()) p.reject(new Error("falcon closed"));
           this.pending.clear();
           if (!this.closed) setTimeout(() => void this.reconnect(), 1e3);
         };
@@ -118,12 +141,14 @@ var CommandStreamTransport = class {
     switch (f.type) {
       case "welcome": {
         this.open = true;
+        this.credits = Number(f.submissionCredits ?? 0);
         const hb = Number(f.heartbeatMs ?? 0);
         if (hb > 0) {
           if (this.heartbeat) clearInterval(this.heartbeat);
           this.heartbeat = setInterval(() => this.send({ type: "heartbeat" }), hb);
         }
         for (const sub of this.subs.values()) this.sendSubscribe(sub);
+        this.releaseCreditWaiters();
         resolveConnect();
         break;
       }
@@ -155,6 +180,11 @@ var CommandStreamTransport = class {
         }
         break;
       }
+      case "submissionCredits": {
+        this.credits += Number(f.n ?? 0);
+        this.releaseCreditWaiters();
+        break;
+      }
     }
   }
   sendSubscribe(sub) {
@@ -167,9 +197,51 @@ var CommandStreamTransport = class {
       fetchVariable: sub.fetchVariables
     });
   }
+  // ----- submission-credit gating ------------------------------------------
+  /**
+   * Take one submission credit, waiting for the gateway to replenish when the
+   * window is exhausted (admission backpressure — no 503, no retry). When
+   * `timeoutMs` elapses first, rejects with {@link SubmissionTimeoutError} and
+   * removes the queued waiter so no credit slot leaks.
+   */
+  acquireCredit(timeoutMs) {
+    if (this.credits > 0) {
+      this.credits -= 1;
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      let timer;
+      const waiter = {
+        grant: () => {
+          if (timer !== void 0) clearTimeout(timer);
+          this.credits -= 1;
+          resolve();
+        },
+        fail: (e) => {
+          if (timer !== void 0) clearTimeout(timer);
+          reject(e);
+        }
+      };
+      this.creditWaiters.push(waiter);
+      if (timeoutMs !== void 0 && timeoutMs > 0) {
+        timer = setTimeout(() => {
+          const i = this.creditWaiters.indexOf(waiter);
+          if (i >= 0) this.creditWaiters.splice(i, 1);
+          reject(new SubmissionTimeoutError(timeoutMs));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+    });
+  }
+  releaseCreditWaiters() {
+    while (this.credits > 0 && this.creditWaiters.length > 0) {
+      this.creditWaiters.shift().grant();
+    }
+  }
   /** Create a process instance over the stream. */
   async createInstance(input) {
     await this.connect();
+    await this.acquireCredit(input.submitTimeoutMs ?? this.defaultSubmitTimeoutMs);
     const corr = this.nextCorr();
     let completionResolve = null;
     const completion = input.awaitCompletion ? new Promise((r) => completionResolve = r) : null;
@@ -221,6 +293,68 @@ var CommandStreamTransport = class {
   }
 };
 
+// src/embedded.ts
+var EmbeddedTransport = class {
+  constructor(host, pollMs = 25) {
+    this.host = host;
+    this.pollMs = pollMs;
+  }
+  host;
+  pollMs;
+  subs = /* @__PURE__ */ new Map();
+  timer = null;
+  closed = false;
+  async createInstance(input) {
+    const { processInstanceKey } = await this.host.createInstance(input);
+    this.host.tick();
+    if (!input.awaitCompletion) return { status: 200, body: { processInstanceKey } };
+    while (!this.host.instanceCompleted(processInstanceKey)) {
+      this.host.tick();
+      await new Promise((r) => setTimeout(r, this.pollMs));
+    }
+    const variables = this.host.instanceVariables(processInstanceKey);
+    return { status: 200, body: { processInstanceKey, variables }, completion: { processCompleted: true, variables, processInstanceKey } };
+  }
+  async subscribe(sub) {
+    this.subs.set(sub.jobType, { worker: sub.worker, credits: sub.credits, timeoutMs: sub.timeoutMs, onJob: sub.onJob });
+    if (!this.timer) this.timer = setInterval(() => this.pump(), this.pollMs);
+  }
+  unsubscribe(jobType) {
+    this.subs.delete(jobType);
+  }
+  completeJob(jobKey, variables) {
+    void this.host.completeJob(jobKey, variables);
+  }
+  failJob(jobKey, retries, errorMessage) {
+    void this.host.failJob(jobKey, retries ?? 0, errorMessage);
+  }
+  throwError(jobKey, _errorCode, errorMessage) {
+    void this.host.failJob(jobKey, 0, errorMessage);
+  }
+  grantCredits(jobType, n) {
+    const s = this.subs.get(jobType);
+    if (s) s.credits += n;
+  }
+  pump() {
+    if (this.closed) return;
+    this.host.tick();
+    for (const [type, s] of this.subs) {
+      if (s.credits <= 0) continue;
+      void this.host.activateJobs(type, s.credits, s.timeoutMs, s.worker).then((jobs) => {
+        for (const j of jobs) {
+          if (s.credits <= 0) break;
+          s.credits--;
+          s.onJob(j);
+        }
+      });
+    }
+  }
+  close() {
+    this.closed = true;
+    if (this.timer) clearInterval(this.timer);
+  }
+};
+
 // src/nanoWorker.ts
 import { JobActionReceiptSymbol as JobActionReceipt } from "@camunda8/orchestration-cluster-api";
 var NanoJobWorker = class {
@@ -313,6 +447,11 @@ function resolveMode(opts) {
   const fromEnv = typeof process !== "undefined" ? process.env?.CAMUNDA_TRANSPORT : void 0;
   return fromOpts ?? fromEnv ?? "auto";
 }
+function resolveSubmitTimeoutMs(opts) {
+  const raw = opts?.config?.CAMUNDA_NANO_SUBMIT_TIMEOUT_MS ?? (typeof process !== "undefined" ? process.env?.CAMUNDA_NANO_SUBMIT_TIMEOUT_MS : void 0);
+  const n = typeof raw === "string" ? Number(raw) : raw;
+  return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
+}
 function baseFrom(restAddress) {
   return normalizeBase(restAddress).replace(/\/v2$/, "");
 }
@@ -320,31 +459,40 @@ function createCamundaClient(opts) {
   const client = createCamundaClientBase(opts);
   const mode = resolveMode(opts);
   if (mode === "rest") return client;
+  if (mode === "embedded") {
+    if (!opts?.embeddedHost) throw new Error("transport 'embedded' requires opts.embeddedHost");
+    const transport2 = new EmbeddedTransport(opts.embeddedHost);
+    return wrapClient(client, async () => transport2, () => transport2.close());
+  }
   const restAddress = client.getConfig().restAddress;
   const base = baseFrom(restAddress);
+  const submitTimeoutMs = resolveSubmitTimeoutMs(opts);
   let transport = null;
   let nano;
   const ensure = async () => {
     if (nano === void 0) {
-      nano = mode === "command-stream" ? { engine: "nanobpmn", commandStreamPath: "/command-stream" } : await detectNano(base);
+      nano = mode === "falcon" ? { engine: "nanobpmn", falconPath: "/falcon" } : await detectNano(base);
     }
     if (!nano) return null;
-    if (!transport) transport = new CommandStreamTransport(base, nano.commandStreamPath);
+    if (!transport) transport = new FalconTransport(base, nano.falconPath, submitTimeoutMs);
     return transport;
   };
+  return wrapClient(client, ensure, () => transport?.close());
+}
+function wrapClient(client, ensure, onStop) {
   return new Proxy(client, {
     get(target, prop, receiver) {
       if (prop === "createProcessInstance") {
         return (input, options) => {
-          const useStream = ensure();
-          return useStream.then(async (t) => {
+          return ensure().then(async (t) => {
             if (!t) return target.createProcessInstance(input, options);
             const r = await t.createInstance({
               processDefinitionId: input?.processDefinitionId,
               processDefinitionKey: input?.processDefinitionKey,
               variables: input?.variables,
               awaitCompletion: input?.awaitCompletion ?? false,
-              fetchVariables: input?.fetchVariables
+              fetchVariables: input?.fetchVariables,
+              submitTimeoutMs: input?.submitTimeoutMs
             });
             if (r.status >= 400) throw new Error(`createInstance failed: ${r.status} ${JSON.stringify(r.body)}`);
             const body = r.body ?? {};
@@ -366,7 +514,7 @@ function createCamundaClient(opts) {
       }
       if (prop === "stopAllWorkers") {
         return () => {
-          transport?.close();
+          onStop?.();
           return target.stopAllWorkers();
         };
       }
@@ -376,8 +524,10 @@ function createCamundaClient(opts) {
 }
 var index_default = createCamundaClient;
 export {
-  CommandStreamTransport,
+  EmbeddedTransport,
+  FalconTransport,
   NanoJobWorker,
+  SubmissionTimeoutError,
   createCamundaClient,
   index_default as default,
   detectNano