@nanobpm/workflow 0.5.0 → 0.7.0

package/dist/client.d.ts

@@ -16,34 +16,101 @@ export declare function toBpmn(wf: Workflow): string;
 export declare function toDeployableBpmn(wf: Workflow, opts?: {
     layout?: boolean;
 }): Promise<string>;
-type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-export interface WorkflowClientOptions {
-    /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. */
-    baseUrl: string;
-    /** Injectable fetch (defaults to the global). Useful for tests/proxies. */
-    fetch?: FetchLike;
+/**
+ * The subset of the `@nanobpm/nano-sdk` (Camunda orchestration-cluster) client
+ * that the workflow surface uses. `createCamundaClient` returns a superset of
+ * this, so a test — or an author bringing their own transport (e.g. the embedded
+ * engine) — can inject any object satisfying it.
+ */
+export interface NanoSdkClient {
+    createDeployment(input: {
+        resources: File[];
+        [k: string]: unknown;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    createProcessInstance(input: {
+        processDefinitionId: string;
+        variables?: JsonObject;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    correlateMessage(input: {
+        name: string;
+        correlationKey: string;
+        variables?: JsonObject;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    getProcessInstance(input: {
+        processInstanceKey: string;
+    }, consistency: {
+        consistency: {
+            waitUpToMs: number;
+        };
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    createJobWorker(cfg: JobWorkerConfig): NanoJobWorker;
 }
-export interface ActivateOptions {
-    worker: string;
-    maxJobsToActivate?: number;
-    /** Job timeout in ms (how long the worker holds the job). Default 30000. */
-    timeout?: number;
-    /** Long-poll timeout in ms; `< 0` disables long-poll. Default 15000. */
-    requestTimeout?: number;
+/** Config for a nano-sdk job worker (the subset the Worker runtime sets). */
+export interface JobWorkerConfig {
+    jobType: string;
+    jobHandler: (job: ActivatedJob) => Promise<unknown> | unknown;
+    workerName?: string;
+    maxParallelJobs?: number;
+    /** Job lock timeout in ms. */
+    jobTimeoutMs?: number;
+    /** Long-poll timeout in ms. */
+    pollTimeoutMs?: number;
+    /** Start polling immediately. The Worker runtime sets this false and starts explicitly. */
+    autoStart?: boolean;
 }
+/** The handle returned by `createJobWorker`. */
+export interface NanoJobWorker {
+    start(): void;
+    stop(): void | Promise<void>;
+    stopGracefully?(opts?: {
+        waitUpToMs?: number;
+    }): Promise<void>;
+}
+/** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
+ *  fields plus the acknowledgement actions. */
+export type ActivatedJob = Job & {
+    complete(variables?: JsonObject): Promise<unknown>;
+    fail(body: {
+        errorMessage: string;
+        retries?: number;
+    }): Promise<unknown>;
+};
+/** Options common to both ways of building a `WorkflowClient`. */
+interface WorkflowClientCommon {
+    /** Auth token for the gateway (CAMUNDA_TOKEN). */
+    token?: string;
+    /** Transport mode passed to `createCamundaClient`: "auto" | "falcon" | "rest".
+     *  Default "auto" (Falcon on a Nano server, REST elsewhere). */
+    transport?: "auto" | "falcon" | "rest";
+}
+/** Construct a `WorkflowClient` from **either** a `baseUrl` (a nano-sdk client is
+ *  built for you) **or** a pre-built `client`. The union makes TypeScript enforce
+ *  that exactly one is supplied, matching the constructor's runtime requirement. */
+export type WorkflowClientOptions = (WorkflowClientCommon & {
+    /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. The
+     *  nano-sdk client normalises this to the `/v2` REST address. */
+    baseUrl: string;
+    client?: never;
+}) | (WorkflowClientCommon & {
+    /** Inject a pre-built nano-sdk client (or a compatible fake) instead of
+     *  constructing one from `baseUrl`. Useful for tests, the embedded
+     *  transport, and advanced authors who build the client themselves. */
+    client: NanoSdkClient;
+    baseUrl?: never;
+});
 export declare class WorkflowError extends Error {
     readonly status?: number | undefined;
     readonly body?: string | undefined;
     constructor(message: string, status?: number | undefined, body?: string | undefined);
 }
 export declare class WorkflowClient {
-    private readonly baseUrl;
-    private readonly fetchImpl;
+    /** The underlying nano-sdk client, exposed so the Worker runtime and app
+     *  authors can reach the engine through the same transport (ADR 0055). The
+     *  exported `NanoSdkClient` type intentionally models only the subset of
+     *  methods this package uses (deploy, create, correlate, get, job workers);
+     *  the runtime value is the full nano-sdk client. */
+    readonly sdk: NanoSdkClient;
     constructor(opts: WorkflowClientOptions);
-    private json;
-    /** Perform a request, throwing WorkflowError on transport error or !ok, and
-     *  return the raw Response (for endpoints with an empty/no-content body). */
-    private send;
     /**
      * Deploy a workflow's derived BPMN model. The deployed model includes
      * auto-generated diagram interchange (DI) so it is inspectable in a
@@ -64,10 +131,8 @@ export declare class WorkflowClient {
      *  unknown signal name (a typo would otherwise send an uncorrelatable message
      *  that the gateway silently drops). */
     signal(flow: DeclarativeFlow, signalName: string, correlationKey: string, variables?: JsonObject): Promise<JsonObject>;
-    /** Fetch an instance (used by demos/tests to observe completion). */
+    /** Fetch an instance (used by demos/tests to observe completion). Reads with
+     *  zero-wait consistency; returns null when the instance is not (yet) visible. */
     getInstance(processInstanceKey: string): Promise<JsonObject | null>;
-    activateJobs(type: string, opts: ActivateOptions): Promise<Job[]>;
-    completeJob(jobKey: string, variables?: JsonObject): Promise<void>;
-    failJob(jobKey: string, errorMessage: string, retries?: number): Promise<void>;
 }
 export {};

package/dist/client.js

@@ -1,6 +1,9 @@
-// A thin, dependency-free client for a running nanobpmn gateway (REST v2):
-// deploy a workflow's derived model, start instances, correlate signals, and the
-// low-level job activate/complete/fail used by the Worker runtime.
+// A client for a running nanobpmn gateway, built on `@nanobpm/nano-sdk` (the
+// single engine-transport spine — ADR 0055). It derives a workflow's model,
+// deploys it (with diagram interchange), starts instances, and correlates
+// signals; the low-level job protocol used by the Worker runtime is the SDK's
+// own job worker, reached through the exposed `sdk` client.
+import { createCamundaClient } from "@nanobpm/nano-sdk";
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { layoutBpmn } from "./layout.js";
@@ -57,37 +60,36 @@ export class WorkflowError extends Error {
         this.name = "WorkflowError";
     }
 }
+/** Normalise a thrown SDK/transport error into a WorkflowError, preserving an
+ *  HTTP status when the SDK attached one. */
+function asWorkflowError(e, what) {
+    if (e instanceof WorkflowError)
+        return e;
+    const err = e;
+    const status = err?.status ?? err?.response?.status;
+    return new WorkflowError(`${what} failed: ${err?.message ?? String(e)}`, status);
+}
 export class WorkflowClient {
-    baseUrl;
-    fetchImpl;
+    /** The underlying nano-sdk client, exposed so the Worker runtime and app
+     *  authors can reach the engine through the same transport (ADR 0055). The
+     *  exported `NanoSdkClient` type intentionally models only the subset of
+     *  methods this package uses (deploy, create, correlate, get, job workers);
+     *  the runtime value is the full nano-sdk client. */
+    sdk;
     constructor(opts) {
-        if (!opts?.baseUrl)
-            throw new Error("WorkflowClient needs a baseUrl");
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-        const f = opts.fetch ?? globalThis.fetch;
-        if (!f)
-            throw new Error("no fetch available; pass options.fetch (Node < 18)");
-        this.fetchImpl = f;
-    }
-    async json(path, init, what) {
-        const res = await this.send(path, init, what);
-        return (await res.json());
-    }
-    /** Perform a request, throwing WorkflowError on transport error or !ok, and
-     *  return the raw Response (for endpoints with an empty/no-content body). */
-    async send(path, init, what) {
-        let res;
-        try {
-            res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
-        }
-        catch (e) {
-            throw new WorkflowError(`${what} transport error: ${e.message}`);
+        if (opts?.client) {
+            this.sdk = opts.client;
+            return;
         }
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new WorkflowError(`${what} failed: ${res.status}`, res.status, body);
-        }
-        return res;
+        if (!opts?.baseUrl)
+            throw new Error("WorkflowClient needs a baseUrl or a client");
+        this.sdk = createCamundaClient({
+            config: {
+                CAMUNDA_REST_ADDRESS: opts.baseUrl.replace(/\/+$/, ""),
+                ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
+                CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+            },
+        });
     }
     /**
      * Deploy a workflow's derived BPMN model. The deployed model includes
@@ -98,9 +100,13 @@ export class WorkflowClient {
      */
     async deploy(wf, opts = {}) {
         const xml = await toDeployableBpmn(wf, opts);
-        const form = new FormData();
-        form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
-        return this.json(`/v2/deployments`, { method: "POST", body: form }, "deploy");
+        const file = new File([xml], `${wf.id}.bpmn`, { type: "text/xml" });
+        try {
+            return (await this.sdk.createDeployment({ resources: [file] }));
+        }
+        catch (e) {
+            throw asWorkflowError(e, "deploy");
+        }
     }
     /**
      * Start a workflow instance. For imperative workflows the engine variables are
@@ -109,11 +115,15 @@ export class WorkflowClient {
      */
     async start(wf, input = {}) {
         const variables = wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
-        return this.json(`/v2/process-instances`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ processDefinitionId: wf.id, variables }),
-        }, "start");
+        try {
+            return (await this.sdk.createProcessInstance({
+                processDefinitionId: wf.id,
+                variables,
+            }));
+        }
+        catch (e) {
+            throw asWorkflowError(e, "start");
+        }
     }
     /** Correlate a signal to a parked declarative `signal` step. Fails fast on an
      *  unknown signal name (a typo would otherwise send an uncorrelatable message
@@ -129,40 +139,25 @@ export class WorkflowClient {
         if (!signals.includes(signalName)) {
             throw new WorkflowError(`unknown signal "${signalName}" on flow "${flow.id}" — declared signals: ${signals.length ? signals.map((s) => `"${s}"`).join(", ") : "(none)"}`);
         }
-        return this.json(`/v2/messages/correlation`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ name: messageName(flow.id, signalName), correlationKey, variables }),
-        }, `signal "${signalName}"`);
+        try {
+            return (await this.sdk.correlateMessage({
+                name: messageName(flow.id, signalName),
+                correlationKey,
+                variables,
+            }));
+        }
+        catch (e) {
+            throw asWorkflowError(e, `signal "${signalName}"`);
+        }
     }
-    /** Fetch an instance (used by demos/tests to observe completion). */
+    /** Fetch an instance (used by demos/tests to observe completion). Reads with
+     *  zero-wait consistency; returns null when the instance is not (yet) visible. */
     async getInstance(processInstanceKey) {
         try {
-            const res = await this.fetchImpl(`${this.baseUrl}/v2/process-instances/${processInstanceKey}`);
-            if (!res.ok)
-                return null;
-            return (await res.json());
+            return (await this.sdk.getProcessInstance({ processInstanceKey }, { consistency: { waitUpToMs: 0 } }));
         }
         catch {
             return null;
         }
     }
-    // --- low-level job protocol (used by the Worker runtime) -------------------
-    async activateJobs(type, opts) {
-        const body = {
-            type,
-            worker: opts.worker,
-            maxJobsToActivate: opts.maxJobsToActivate ?? 1,
-            timeout: opts.timeout ?? 30000,
-            requestTimeout: opts.requestTimeout ?? 15000,
-        };
-        const res = await this.json(`/v2/jobs/activation`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, `activate ${type}`);
-        return res.jobs ?? [];
-    }
-    async completeJob(jobKey, variables = {}) {
-        await this.send(`/v2/jobs/${jobKey}/completion`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) }, "complete job");
-    }
-    async failJob(jobKey, errorMessage, retries = 0) {
-        await this.send(`/v2/jobs/${jobKey}/failure`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ errorMessage, retries }) }, "fail job");
-    }
 }

package/dist/declarative.d.ts

@@ -55,6 +55,36 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
     signal<K extends string>(name: K, opts: {
         correlationKey: string;
     }): FlowBuilder<C>;
+    /**
+     * A durable wait for a point in time (a BPMN timer intermediate catch event).
+     * Pass exactly one of `{ after }` — an ISO-8601 delay (`PT1M30S`, `P1DT6H`) or
+     * FEEL `=`-expression measured from when the token arrives — or `{ at }` — an
+     * absolute ISO-8601 instant (or FEEL expression). The engine holds the token
+     * durably until the timer fires, then continues. Use it for in-flow delays and
+     * scheduled continuations (e.g. "wait 24h, then re-poll").
+     */
+    timer<K extends string>(name: K, opts: {
+        after: string;
+    } | {
+        at: string;
+    }): FlowBuilder<C>;
+    /**
+     * Make this flow's start event a durable TIMER start rather than an explicit
+     * `client.start(...)`. Must be the first statement, at the top level. Pass
+     * exactly one of `{ cycle }` — a recurring ISO-8601 interval (`R/PT1H`,
+     * `R5/PT30M`) the engine re-fires each period — `{ after }` — a one-shot delay
+     * from deployment — or `{ at }` — a one-shot absolute instant. A `cycle` start
+     * is the model-native, durable, single-fire-per-cluster replacement for an
+     * app-side cron: the schedule lives in the deployable model, and the engine
+     * (not each app replica) owns firing it exactly once.
+     */
+    startOn(spec: {
+        cycle: string;
+    } | {
+        after: string;
+    } | {
+        at: string;
+    }): FlowBuilder<C>;
     /**
      * A multi-way exclusive choice (a BPMN exclusive gateway). `subject` is a FEEL
      * expression (usually a variable name); each case routes when `subject` equals

package/dist/declarative.js

@@ -34,7 +34,7 @@
 // Typed data envelopes are LIFTED into the model (nano:shape + dataEnvelope
 // zeebe:property), so the generated .bpmn is ejectable to model-first with its
 // typed contracts intact.
-import { assertIdent, assertJobType, escapeXml, jobType, messageName } from "./xml.js";
+import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTimerDuration, escapeXml, jobType, messageName } from "./xml.js";
 /** Ids the emitter generates for structural nodes / flows / messages. A step
  *  name that collides with one of these would produce a duplicate BPMN id and an
  *  invalid model, so reject them at authoring time. */
@@ -61,7 +61,7 @@ function contractEnvelopes(ctx, name) {
 /** Build a FlowBuilder that appends its nodes to `out`, sharing the flow-wide
  *  `ctx` (contracts, handler registry, name set, loop nesting). Structural
  *  combinators recurse with a fresh `out` array for each nested body. */
-function makeBuilder(id, out, ctx) {
+function makeBuilder(id, out, ctx, isRoot = false) {
     const child = (fn, inLoop) => {
         const body = [];
         const depth = inLoop ? ctx.loopDepth + 1 : ctx.loopDepth;
@@ -93,6 +93,54 @@ function makeBuilder(id, out, ctx) {
             out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: ctx.contracts[name]?.in });
             return b;
         },
+        timer(name, opts) {
+            claimName(ctx, id, name);
+            const hasAfter = typeof opts?.after === "string";
+            const hasAt = typeof opts?.at === "string";
+            if (hasAfter === hasAt) {
+                throw new Error(`timer("${name}") needs exactly one of { after } (a delay) or { at } (an instant)`);
+            }
+            if (hasAfter) {
+                const after = opts.after.trim();
+                assertTimerDuration(`timer("${name}") after`, after);
+                out.push({ kind: "timer", name, after });
+            }
+            else {
+                const at = opts.at.trim();
+                assertTimerDate(`timer("${name}") at`, at);
+                out.push({ kind: "timer", name, at });
+            }
+            return b;
+        },
+        startOn(spec) {
+            if (!isRoot) {
+                throw new Error(`startOn() is only valid at the top level of flow "${id}" (not inside switch/branch/loop)`);
+            }
+            if (out.length !== 0)
+                throw new Error(`startOn() must be the first statement in flow "${id}"`);
+            if (ctx.startTimer)
+                throw new Error(`startOn() may be called only once in flow "${id}"`);
+            const set = ["cycle", "after", "at"].filter((k) => typeof spec?.[k] === "string");
+            if (set.length !== 1) {
+                throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${id}"`);
+            }
+            if (spec.cycle !== undefined) {
+                const cycle = spec.cycle.trim();
+                assertTimerCycle(`startOn cycle`, cycle);
+                ctx.startTimer = { cycle };
+            }
+            else if (spec.after !== undefined) {
+                const after = spec.after.trim();
+                assertTimerDuration(`startOn after`, after);
+                ctx.startTimer = { after };
+            }
+            else {
+                const at = spec.at.trim();
+                assertTimerDate(`startOn at`, at);
+                ctx.startTimer = { at };
+            }
+            return b;
+        },
         switch(subject, cases) {
             if (typeof subject !== "string" || subject.trim() === "") {
                 throw new Error(`switch() needs a non-empty subject expression`);
@@ -153,10 +201,13 @@ export function defineFlow(id, second, third) {
     const steps = [];
     const handlers = {};
     const ctx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-    build(makeBuilder(id, steps, ctx));
+    build(makeBuilder(id, steps, ctx, true));
     if (steps.length === 0)
         throw new Error(`flow "${id}" declared no steps`);
-    return { kind: "declarative", id, steps, handlers };
+    const flow = { kind: "declarative", id, steps, handlers };
+    if (ctx.startTimer)
+        flow.startTimer = ctx.startTimer;
+    return flow;
 }
 // --- Tree walkers ------------------------------------------------------------
 /** Depth-first visit of every node in a flow tree (structural combinators
@@ -269,6 +320,21 @@ class Compiler {
                 `    </bpmn:intermediateCatchEvent>`,
         });
     }
+    addTimerCatchEvent(node) {
+        const id = node.name;
+        const body = node.after !== undefined
+            ? `        <bpmn:timeDuration>${escapeXml(node.after)}</bpmn:timeDuration>\n`
+            : `        <bpmn:timeDate>${escapeXml(node.at)}</bpmn:timeDate>\n`;
+        this.nodes.push({
+            id,
+            render: (inc, outg) => `    <bpmn:intermediateCatchEvent id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
+                incomingOutgoing(inc, outg) +
+                `      <bpmn:timerEventDefinition>\n` +
+                body +
+                `      </bpmn:timerEventDefinition>\n` +
+                `    </bpmn:intermediateCatchEvent>`,
+        });
+    }
     addGateway(id, name) {
         const gwNode = {
             id,
@@ -303,6 +369,11 @@ class Compiler {
                 this.recordEnvelope(node.payload);
                 return [this.newEdge(node.name)];
             }
+            case "timer": {
+                this.addTimerCatchEvent(node);
+                this.connect(incoming, node.name);
+                return [this.newEdge(node.name)];
+            }
             case "switch": {
                 const id = `Gw_${this.gw++}`;
                 const gw = this.addGateway(id, node.subject);
@@ -357,11 +428,29 @@ class Compiler {
             }
         }
     }
+    /** Render the Start event — a plain none start, or a timer start when the
+     *  flow declared `startOn(...)`. */
+    renderStart(outg) {
+        const t = this.flow.startTimer;
+        if (!t)
+            return `    <bpmn:startEvent id="Start">${outgoingOnly(outg)}</bpmn:startEvent>`;
+        const body = t.cycle !== undefined
+            ? `<bpmn:timeCycle>${escapeXml(t.cycle)}</bpmn:timeCycle>`
+            : t.after !== undefined
+                ? `<bpmn:timeDuration>${escapeXml(t.after)}</bpmn:timeDuration>`
+                : `<bpmn:timeDate>${escapeXml(t.at)}</bpmn:timeDate>`;
+        return (`    <bpmn:startEvent id="Start">\n` +
+            `      ${outgoingOnly(outg)}\n` +
+            `      <bpmn:timerEventDefinition>\n` +
+            `        ${body}\n` +
+            `      </bpmn:timerEventDefinition>\n` +
+            `    </bpmn:startEvent>`);
+    }
     compile() {
         // Start → top-level sequence → End.
         this.nodes.push({
             id: "Start",
-            render: (_inc, outg) => `    <bpmn:startEvent id="Start">${outgoingOnly(outg)}</bpmn:startEvent>`,
+            render: (_inc, outg) => this.renderStart(outg),
         });
         const s0 = this.newEdge("Start");
         const finalDanglers = this.emitList(this.flow.steps, [s0], null);

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type { Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, ScalarTs, FieldTs, } from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
-export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
+export type { WorkflowClientOptions, NanoSdkClient, NanoJobWorker, JobWorkerConfig, ActivatedJob, } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";
-export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, FlowNode, SwitchCase, NodeEnvelopes, StepContract, FlowContracts, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";
+export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, FlowNode, SwitchCase, TimerStart, NodeEnvelopes, StepContract, FlowContracts, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";

package/dist/types.d.ts

@@ -52,7 +52,10 @@ export type FlowNode = {
     name: string;
     correlationKey: string;
     payload?: Envelope;
-} | {
+} | ({
+    kind: "timer";
+    name: string;
+} & TimerAt) | {
     kind: "switch";
     subject: string;
     cases: SwitchCase[];
@@ -70,6 +73,38 @@ export type FlowNode = {
 } | {
     kind: "continue";
 };
+/** A timer intermediate-catch definition: exactly one of `after` (an ISO-8601
+ *  delay or FEEL expression) or `at` (an absolute instant or FEEL expression).
+ *  Encoded as an XOR so downstream consumers can rely on exactly-one. */
+export type TimerAt = {
+    after: string;
+    at?: never;
+} | {
+    at: string;
+    after?: never;
+};
+/** A flow's start-timer: the plain none start event becomes a durable timer
+ *  start the engine fires on schedule. Exactly one of:
+ *  - `cycle` — a recurring ISO-8601 interval (`R/PT1H`, `R5/PT30M`) or bare
+ *    duration; the engine re-fires on each period. This is the model-native,
+ *    durable, single-fire-per-cluster replacement for an app-side cron.
+ *  - `after` — a one-shot ISO-8601 delay (`PT10S`) measured from deployment.
+ *  - `at`    — a one-shot absolute instant (an ISO-8601 date-time, or a FEEL
+ *    `=` expression).
+ *  Encoded as an XOR so the exactly-one invariant holds at the type level. */
+export type TimerStart = {
+    cycle: string;
+    after?: never;
+    at?: never;
+} | {
+    after: string;
+    cycle?: never;
+    at?: never;
+} | {
+    at: string;
+    cycle?: never;
+    after?: never;
+};
 /** One case of a `switch`: routed when `subject = value` (FEEL equality). */
 export interface SwitchCase {
     value: string;
@@ -84,6 +119,9 @@ export interface DeclarativeFlow {
     /** The flow's node tree (top-level sequence). */
     steps: FlowNode[];
     handlers: Record<string, StepHandler>;
+    /** When set, the flow's start event is a durable timer start (see
+     *  {@link TimerStart}) rather than a plain none start. */
+    startTimer?: TimerStart;
 }
 /** The context passed to an imperative orchestration function. */
 export interface WorkflowContext {

package/dist/worker.d.ts

@@ -9,36 +9,53 @@ export interface ActivityEvent {
     /** For an imperative orchestrator turn: the journalled step key, or "__done". */
     step?: string;
 }
-export interface WorkerOptions {
-    /** Provide a baseUrl (a client is created) or an existing client. */
-    baseUrl?: string;
-    client?: WorkflowClient;
+/** Options common to both ways of building a `Worker`. */
+interface WorkerCommon {
     workflows: Workflow[];
     /** Worker name reported to the gateway. Default "nanobpm-workflow". */
     name?: string;
+    /** Transport for the worker's own client (used only when `client` is not
+     *  supplied): "auto" | "falcon" | "rest". Defaults to "rest" — job serving is
+     *  resilience-critical, and REST long-poll reconnects with backoff after an
+     *  engine restart (the ADR 0044 property), whereas the Falcon push transport
+     *  does not recover a mid-stream disconnect. Instance creation, by contrast,
+     *  defaults to Falcon on its own `WorkflowClient` for throughput. */
+    transport?: "auto" | "falcon" | "rest";
     /** Long-poll timeout per activation, ms. Also bounds stop() latency. Default 10000. */
     pollTimeoutMs?: number;
     /** Job lock timeout, ms. Default 30000. */
     jobTimeoutMs?: number;
-    /** Backoff after a transport error, ms. Default 500. */
-    backoffMs?: number;
+    /** Max jobs handled in parallel per derived job type. Default 1. */
+    maxParallelJobs?: number;
     onActivity?: (e: ActivityEvent) => void | Promise<void>;
     onError?: (err: Error, context: {
         type: string;
     }) => void;
 }
+/** Build a `Worker` from **either** a `baseUrl` (a `WorkflowClient` is created)
+ *  **or** an existing `client`. The union makes TypeScript enforce that exactly
+ *  one is supplied, matching the constructor's runtime requirement. */
+export type WorkerOptions = (WorkerCommon & {
+    /** Base URL of the nanobpmn gateway; a `WorkflowClient` is created for you. */
+    baseUrl: string;
+    client?: never;
+}) | (WorkerCommon & {
+    /** An existing `WorkflowClient` to serve jobs through. */
+    client: WorkflowClient;
+    baseUrl?: never;
+});
 export declare class Worker {
     private readonly client;
     private readonly name;
     private readonly pollTimeoutMs;
     private readonly jobTimeoutMs;
-    private readonly backoffMs;
+    private readonly maxParallelJobs;
     private readonly onActivity?;
     private readonly onError?;
     /** job type → { workflowId, handle } */
     private readonly routes;
     private running;
-    private loops;
+    private workers;
     constructor(opts: WorkerOptions);
     private register;
     /** Register a derived job type, failing fast on a collision. Two workflows can
@@ -55,9 +72,18 @@ export declare class Worker {
     private emitActivity;
     /** The derived job types this worker serves. */
     get servedTypes(): string[];
-    /** Begin polling. Resolves once the loops are running (they run until stop()). */
+    /** Begin serving. Creates one nano-sdk job worker per derived job type with
+     *  `autoStart: false`, then starts each explicitly, so the poll lifecycle is
+     *  deterministic and owned here rather than left to the SDK's auto-start
+     *  default (matching the `JobWorkerConfig.autoStart` contract). Nothing polls
+     *  before `start()` is called. */
     start(): void;
-    /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+    /** Stop serving and wait for in-flight jobs to drain. Stopping is best-effort
+     *  per worker: the Falcon worker's `stop` throws if it never bound a transport
+     *  (detection still pending), which must not fail the whole shutdown. */
     stop(): Promise<void>;
-    private pollLoop;
+    /** Dispatch one activated job to its route handler and acknowledge it. Returns
+     *  the nano-sdk action receipt (its `complete`/`fail` result). */
+    private handleJob;
 }
+export {};