@nanobpm/workflow 0.6.0 → 0.7.0

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

@@ -9,4 +9,4 @@ export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./clien
 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/xml.d.ts

@@ -8,4 +8,7 @@ export declare const messageName: (workflowId: string, step: string) => string;
 export declare const orchestrateType: (workflowId: string) => string;
 export declare function assertIdent(kind: string, value: string): void;
 export declare function assertJobType(kind: string, value: string): void;
+export declare function assertTimerDuration(kind: string, value: string): void;
+export declare function assertTimerCycle(kind: string, value: string): void;
+export declare function assertTimerDate(kind: string, value: string): void;
 export declare function assertWorkflowIds(wf: Workflow): void;

package/dist/xml.js

@@ -29,6 +29,56 @@ export function assertJobType(kind, value) {
         throw new Error(`${kind} "${value}" is not a valid job type (expected a non-empty token of letters, digits, and _ . : + -)`);
     }
 }
+// --- Timer definitions (BPMN timerEventDefinition bodies) --------------------
+//
+// The engine (engine-core/src/bpmn.rs) accepts a nested `timeDuration`,
+// `timeCycle`, or `timeDate` as either a static ISO-8601 literal or a FEEL
+// expression (a leading `=`). We validate the literal forms at authoring time so
+// a malformed timer fails fast in the DSL rather than at deploy.
+/** An ISO-8601 duration with integer week/day/hour/minute/second components
+ *  (no years/months — ambiguous length — matching the engine's parser). */
+const ISO_DURATION = /^P(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$/;
+function isIsoDuration(v) {
+    if (!ISO_DURATION.test(v) || v === "P" || v === "PT" || v.endsWith("T"))
+        return false;
+    return /\d/.test(v);
+}
+/** A recurring ISO-8601 interval: an optional `R[n]/` repeat prefix + a
+ *  duration, or a bare duration (the engine repeats it unboundedly). */
+function isIsoCycle(v) {
+    const slash = v.indexOf("/");
+    if (slash < 0)
+        return isIsoDuration(v);
+    const repeat = v.slice(0, slash);
+    const interval = v.slice(slash + 1);
+    return /^R\d*$/.test(repeat) && isIsoDuration(interval);
+}
+/** An ISO-8601 date-time instant (a `timeDate`). A `timeDate` is an absolute
+ *  instant, so a zone designator (`Z` or an explicit `±HH:MM` offset) is
+ *  required — a bare local datetime like `2026-01-01T09:00:00` is ambiguous. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+/** A FEEL expression body (a leading `=`, non-empty). */
+function isFeel(v) {
+    return v.startsWith("=") && v.length > 1;
+}
+export function assertTimerDuration(kind, value) {
+    const v = typeof value === "string" ? value.trim() : "";
+    if (v === "" || (!isFeel(v) && !isIsoDuration(v))) {
+        throw new Error(`${kind} "${value}" is not an ISO-8601 duration (e.g. PT1M30S, P1DT6H) or a FEEL expression (=...)`);
+    }
+}
+export function assertTimerCycle(kind, value) {
+    const v = typeof value === "string" ? value.trim() : "";
+    if (v === "" || (!isFeel(v) && !isIsoCycle(v))) {
+        throw new Error(`${kind} "${value}" is not an ISO-8601 repeating interval (e.g. R/PT1H, R5/PT30M), a bare duration (e.g. PT1H), or a FEEL expression (=...)`);
+    }
+}
+export function assertTimerDate(kind, value) {
+    const v = typeof value === "string" ? value.trim() : "";
+    if (v === "" || (!isFeel(v) && !ISO_DATE.test(v))) {
+        throw new Error(`${kind} "${value}" is not an ISO-8601 instant (e.g. 2026-01-01T09:00:00Z) or a FEEL expression (=...)`);
+    }
+}
 export function assertWorkflowIds(wf) {
     assertIdent("workflow id", wf.id);
     if (wf.kind === "declarative") {
@@ -42,6 +92,9 @@ function assertNodeNames(nodes) {
             case "signal":
                 assertIdent("step name", node.name);
                 break;
+            case "timer":
+                assertIdent("step name", node.name);
+                break;
             case "task":
                 assertIdent("step name", node.name);
                 if (node.jobType !== undefined)

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jwulf/nano-ide.git",
+    "url": "git+https://github.com/jwulf/nano-ide.git",
     "directory": "packages/workflow"
   },
   "main": "./dist/index.js",

package/src/declarative.ts

@@ -44,9 +44,10 @@ import type {
   StepContract,
   StepHandler,
   SwitchCase,
+  TimerStart,
 } from "./types.js";
 import type { Envelope, EnvelopeField } from "./envelope.js";
-import { assertIdent, assertJobType, escapeXml, jobType, messageName } from "./xml.js";
+import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTimerDuration, escapeXml, jobType, messageName } from "./xml.js";
 
 // --- Authoring surface -------------------------------------------------------
 
@@ -100,6 +101,26 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
    * payload envelope, if any, comes from the contract's `in`.
    */
   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
@@ -132,6 +153,8 @@ interface BuilderCtx {
   handlers: Record<string, StepHandler>;
   seen: Set<string>;
   loopDepth: number;
+  /** Set by `startOn()` (root builder only); lifted onto the flow. */
+  startTimer?: TimerStart;
 }
 
 /** Ids the emitter generates for structural nodes / flows / messages. A step
@@ -163,7 +186,12 @@ function contractEnvelopes(ctx: BuilderCtx, name: string): { in?: Envelope; out?
 /** 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<C extends FlowContracts>(id: string, out: FlowNode[], ctx: BuilderCtx): FlowBuilder<C> {
+function makeBuilder<C extends FlowContracts>(
+  id: string,
+  out: FlowNode[],
+  ctx: BuilderCtx,
+  isRoot = false,
+): FlowBuilder<C> {
   const child = (fn: Block<C>, inLoop: boolean): FlowNode[] => {
     const body: FlowNode[] = [];
     const depth = inLoop ? ctx.loopDepth + 1 : ctx.loopDepth;
@@ -192,6 +220,49 @@ function makeBuilder<C extends FlowContracts>(id: string, out: FlowNode[], ctx:
       out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: ctx.contracts[name]?.in });
       return b as unknown as FlowBuilder<C>;
     },
+    timer(name: string, opts: { after?: string; at?: string }): FlowBuilder<C> {
+      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 as string).trim();
+        assertTimerDuration(`timer("${name}") after`, after);
+        out.push({ kind: "timer", name, after });
+      } else {
+        const at = (opts.at as string).trim();
+        assertTimerDate(`timer("${name}") at`, at);
+        out.push({ kind: "timer", name, at });
+      }
+      return b as unknown as FlowBuilder<C>;
+    },
+    startOn(spec: { cycle?: string; after?: string; at?: string }): FlowBuilder<C> {
+      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"] as const).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 as string).trim();
+        assertTimerDate(`startOn at`, at);
+        ctx.startTimer = { at };
+      }
+      return b as unknown as FlowBuilder<C>;
+    },
     switch(subject: string, cases: Record<string, Block<C>> & { default?: Block<C> }): FlowBuilder<C> {
       if (typeof subject !== "string" || subject.trim() === "") {
         throw new Error(`switch() needs a non-empty subject expression`);
@@ -263,9 +334,11 @@ export function defineFlow(
   const steps: FlowNode[] = [];
   const handlers: Record<string, StepHandler> = {};
   const ctx: BuilderCtx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-  build(makeBuilder<FlowContracts>(id, steps, ctx));
+  build(makeBuilder<FlowContracts>(id, steps, ctx, true));
   if (steps.length === 0) throw new Error(`flow "${id}" declared no steps`);
-  return { kind: "declarative", id, steps, handlers };
+  const flow: DeclarativeFlow = { kind: "declarative", id, steps, handlers };
+  if (ctx.startTimer) flow.startTimer = ctx.startTimer;
+  return flow;
 }
 
 // --- Tree walkers ------------------------------------------------------------
@@ -404,6 +477,24 @@ class Compiler {
     });
   }
 
+  private addTimerCatchEvent(node: { name: string; after?: string; at?: string }): void {
+    const id = node.name;
+    const body =
+      node.after !== undefined
+        ? `        <bpmn:timeDuration>${escapeXml(node.after)}</bpmn:timeDuration>\n`
+        : `        <bpmn:timeDate>${escapeXml(node.at as string)}</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>`,
+    });
+  }
+
   private addGateway(id: string, name?: string): RenderNode {
     const gwNode: RenderNode = {
       id,
@@ -441,6 +532,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);
@@ -494,11 +590,32 @@ class Compiler {
     }
   }
 
+  /** Render the Start event — a plain none start, or a timer start when the
+   *  flow declared `startOn(...)`. */
+  private renderStart(outg: string[]): string {
+    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 as string)}</bpmn:timeDate>`;
+    return (
+      `    <bpmn:startEvent id="Start">\n` +
+      `      ${outgoingOnly(outg)}\n` +
+      `      <bpmn:timerEventDefinition>\n` +
+      `        ${body}\n` +
+      `      </bpmn:timerEventDefinition>\n` +
+      `    </bpmn:startEvent>`
+    );
+  }
+
   compile(): string {
     // 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/src/index.ts

@@ -73,6 +73,7 @@ export type {
   DeclarativeStep,
   FlowNode,
   SwitchCase,
+  TimerStart,
   NodeEnvelopes,
   StepContract,
   FlowContracts,

package/src/types.ts

@@ -53,12 +53,34 @@ export type FlowNode =
   | { kind: "run"; name: string; envelopes?: NodeEnvelopes }
   | { kind: "task"; name: string; envelopes?: NodeEnvelopes; jobType?: string }
   | { kind: "signal"; name: string; correlationKey: string; payload?: Envelope }
+  | ({ kind: "timer"; name: string } & TimerAt)
   | { kind: "switch"; subject: string; cases: SwitchCase[]; default?: FlowNode[] }
   | { kind: "branch"; condition: string; then: FlowNode[]; else?: FlowNode[] }
   | { kind: "loop"; body: FlowNode[] }
   | { kind: "break" }
   | { 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;
@@ -75,6 +97,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;
 }
 
 // --- Imperative surface (Strategy B: a replayed orchestration function) -------

package/src/xml.ts

@@ -40,6 +40,68 @@ export function assertJobType(kind: string, value: string): void {
   }
 }
 
+// --- Timer definitions (BPMN timerEventDefinition bodies) --------------------
+//
+// The engine (engine-core/src/bpmn.rs) accepts a nested `timeDuration`,
+// `timeCycle`, or `timeDate` as either a static ISO-8601 literal or a FEEL
+// expression (a leading `=`). We validate the literal forms at authoring time so
+// a malformed timer fails fast in the DSL rather than at deploy.
+
+/** An ISO-8601 duration with integer week/day/hour/minute/second components
+ *  (no years/months — ambiguous length — matching the engine's parser). */
+const ISO_DURATION = /^P(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$/;
+function isIsoDuration(v: string): boolean {
+  if (!ISO_DURATION.test(v) || v === "P" || v === "PT" || v.endsWith("T")) return false;
+  return /\d/.test(v);
+}
+
+/** A recurring ISO-8601 interval: an optional `R[n]/` repeat prefix + a
+ *  duration, or a bare duration (the engine repeats it unboundedly). */
+function isIsoCycle(v: string): boolean {
+  const slash = v.indexOf("/");
+  if (slash < 0) return isIsoDuration(v);
+  const repeat = v.slice(0, slash);
+  const interval = v.slice(slash + 1);
+  return /^R\d*$/.test(repeat) && isIsoDuration(interval);
+}
+
+/** An ISO-8601 date-time instant (a `timeDate`). A `timeDate` is an absolute
+ *  instant, so a zone designator (`Z` or an explicit `±HH:MM` offset) is
+ *  required — a bare local datetime like `2026-01-01T09:00:00` is ambiguous. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/** A FEEL expression body (a leading `=`, non-empty). */
+function isFeel(v: string): boolean {
+  return v.startsWith("=") && v.length > 1;
+}
+
+export function assertTimerDuration(kind: string, value: string): void {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (v === "" || (!isFeel(v) && !isIsoDuration(v))) {
+    throw new Error(
+      `${kind} "${value}" is not an ISO-8601 duration (e.g. PT1M30S, P1DT6H) or a FEEL expression (=...)`,
+    );
+  }
+}
+
+export function assertTimerCycle(kind: string, value: string): void {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (v === "" || (!isFeel(v) && !isIsoCycle(v))) {
+    throw new Error(
+      `${kind} "${value}" is not an ISO-8601 repeating interval (e.g. R/PT1H, R5/PT30M), a bare duration (e.g. PT1H), or a FEEL expression (=...)`,
+    );
+  }
+}
+
+export function assertTimerDate(kind: string, value: string): void {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (v === "" || (!isFeel(v) && !ISO_DATE.test(v))) {
+    throw new Error(
+      `${kind} "${value}" is not an ISO-8601 instant (e.g. 2026-01-01T09:00:00Z) or a FEEL expression (=...)`,
+    );
+  }
+}
+
 export function assertWorkflowIds(wf: Workflow): void {
   assertIdent("workflow id", wf.id);
   if (wf.kind === "declarative") {
@@ -54,6 +116,9 @@ function assertNodeNames(nodes: FlowNode[]): void {
       case "signal":
         assertIdent("step name", node.name);
         break;
+      case "timer":
+        assertIdent("step name", node.name);
+        break;
       case "task":
         assertIdent("step name", node.name);
         if (node.jobType !== undefined) assertJobType("job type", node.jobType);