@nanobpm/workflow 0.5.0 → 0.7.0

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

@@ -55,7 +55,13 @@ export type {
   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 {
@@ -67,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/worker.ts

@@ -1,6 +1,7 @@
 // The Worker runtime — hosts one or more workflows against a gateway and drives
-// them: long-polls each derived job type, dispatches jobs to handlers, completes
-// them. It generalises the two surfaces:
+// them: it registers one nano-sdk job worker per derived job type, dispatches
+// each activated job to its handler, and completes it. It generalises the two
+// surfaces:
 //
 //   - a declarative flow contributes one job type per `run` step, dispatched to
 //     the user handler (external `task` steps are intentionally NOT hosted here —
@@ -8,11 +9,13 @@
 //   - an imperative workflow contributes its single orchestrator job type,
 //     dispatched to the replay engine (which advances the journal one step).
 //
-// It is resilient to the gateway disappearing (each poll loop backs off and
-// reconnects on its own), so it survives an engine crash/restart — the property
-// the ADR 0044 spike proved.
+// Transport (activation, completion, failure, long-poll, backoff/reconnect) is
+// the nano-sdk job worker (ADR 0055), reached through `WorkflowClient.sdk`. The
+// nano-sdk worker reschedules its poll on an activation error, so the runtime
+// survives an engine crash/restart — the property the ADR 0044 spike proved.
 
 import { WorkflowClient } from "./client.js";
+import type { ActivatedJob, NanoJobWorker } from "./client.js";
 import { replayOnce } from "./imperative.js";
 import { walkNodes } from "./declarative.js";
 import type { Job, JsonObject, Workflow } from "./types.js";
@@ -28,46 +31,66 @@ export interface ActivityEvent {
   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;
 }
 
-type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
+/** 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;
+    });
 
-const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
 
 export class Worker {
   private readonly client: WorkflowClient;
   private readonly name: string;
   private readonly pollTimeoutMs: number;
   private readonly jobTimeoutMs: number;
-  private readonly backoffMs: number;
+  private readonly maxParallelJobs: number;
   private readonly onActivity?: WorkerOptions["onActivity"];
   private readonly onError?: WorkerOptions["onError"];
   /** job type → { workflowId, handle } */
   private readonly routes = new Map<string, { workflowId: string; handle: Handler }>();
   private running = false;
-  private loops: Promise<void>[] = [];
+  private workers: NanoJobWorker[] = [];
 
   constructor(opts: WorkerOptions) {
-    this.client = opts.client ?? new WorkflowClient({ baseUrl: requireBaseUrl(opts) });
+    this.client =
+      opts.client ??
+      new WorkflowClient({ baseUrl: requireBaseUrl(opts), transport: opts.transport ?? "rest" });
     this.name = opts.name ?? "nanobpm-workflow";
     this.pollTimeoutMs = opts.pollTimeoutMs ?? 10000;
     this.jobTimeoutMs = opts.jobTimeoutMs ?? 30000;
-    this.backoffMs = opts.backoffMs ?? 500;
+    this.maxParallelJobs = opts.maxParallelJobs ?? 1;
     this.onActivity = opts.onActivity;
     this.onError = opts.onError;
     for (const wf of opts.workflows) this.register(wf);
@@ -152,61 +175,84 @@ export class Worker {
     return [...this.routes.keys()];
   }
 
-  /** 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 {
     if (this.running) return;
     this.running = true;
-    this.loops = [...this.routes.entries()].map(([type, route]) => this.pollLoop(type, route));
+    this.workers = [...this.routes.entries()].map(([type, route]) => {
+      const worker = this.client.sdk.createJobWorker({
+        jobType: type,
+        workerName: this.name,
+        maxParallelJobs: this.maxParallelJobs,
+        jobTimeoutMs: this.jobTimeoutMs,
+        pollTimeoutMs: this.pollTimeoutMs,
+        autoStart: false,
+        jobHandler: (job) => this.handleJob(type, route, job),
+      });
+      worker.start();
+      return worker;
+    });
   }
 
-  /** 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. */
   async stop(): Promise<void> {
     this.running = false;
-    await Promise.all(this.loops);
-    this.loops = [];
+    await Promise.all(
+      this.workers.map(async (w) => {
+        try {
+          await (w.stopGracefully
+            ? w.stopGracefully({ waitUpToMs: this.pollTimeoutMs })
+            : w.stop());
+        } catch {
+          /* worker never fully started (transport unbound); nothing to drain */
+        }
+      }),
+    );
+    this.workers = [];
   }
 
-  private async pollLoop(type: string, route: { workflowId: string; handle: Handler }): Promise<void> {
-    while (this.running) {
-      let jobs: Job[] = [];
+  /** Dispatch one activated job to its route handler and acknowledge it. Returns
+   *  the nano-sdk action receipt (its `complete`/`fail` result). */
+  private async handleJob(
+    type: string,
+    route: { workflowId: string; handle: Handler },
+    job: ActivatedJob,
+  ): Promise<unknown> {
+    try {
+      const { variables, step } = await route.handle(job);
+      const receipt = await job.complete(variables);
+      // Job is now completed; the observer hook is isolated (emitActivity
+      // swallows its own errors) so it can never fall into the failure path.
+      await this.emitActivity({
+        workflowId: route.workflowId,
+        type,
+        jobKey: job.jobKey,
+        elementId: job.elementId,
+        step,
+      });
+      return receipt;
+    } catch (e) {
+      // A handler or completion failed. Report; the engine will redeliver the
+      // job after its lock times out (at-least-once → handlers must be
+      // idempotent). Best-effort surface it as an incident-worthy failure.
+      // Normalise non-Error throws (strings, objects) so emitError always gets
+      // an Error and errorMessage is never undefined in the failure report.
+      const err = e instanceof Error ? e : new Error(String(e));
+      this.emitError(err, type);
       try {
-        jobs = await this.client.activateJobs(type, {
-          worker: this.name,
-          maxJobsToActivate: 1,
-          timeout: this.jobTimeoutMs,
-          requestTimeout: this.pollTimeoutMs,
-        });
-      } catch (e) {
-        // Transport/gateway error (e.g. engine restarting): back off, reconnect.
-        this.emitError(e as Error, type);
-        await sleep(this.backoffMs);
-        continue;
-      }
-      for (const job of jobs) {
-        if (!this.running) break;
-        try {
-          const { variables, step } = await route.handle(job);
-          await this.client.completeJob(job.jobKey, variables);
-          // Job is now completed; the observer hook is isolated (emitActivity
-          // swallows its own errors) so it can never fall into the failure path.
-          await this.emitActivity({
-            workflowId: route.workflowId,
-            type,
-            jobKey: job.jobKey,
-            elementId: job.elementId,
-            step,
-          });
-        } catch (e) {
-          // A handler or completion failed. Report; the engine will redeliver the
-          // job after its lock times out (at-least-once → handlers must be
-          // idempotent). Best-effort surface it as an incident-worthy failure.
-          this.emitError(e as Error, type);
-          try {
-            await this.client.failJob(job.jobKey, (e as Error).message, 0);
-          } catch {
-            /* engine may be down; the lock will expire and redeliver */
-          }
-        }
+        return await job.fail({ errorMessage: err.message, retries: 0 });
+      } catch {
+        // Even reporting the failure failed (e.g. the gateway is unreachable).
+        // Awaited + swallowed so a rejected `fail` can't escape as an unhandled
+        // rejection out of the SDK worker's handler; the engine redelivers the
+        // job once its lock times out regardless.
+        return undefined;
       }
     }
   }

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);