@nanobpm/urban 0.10.0 → 0.11.1

package/README.md

@@ -78,7 +78,7 @@ console.log(app.inspect());              // { app, name, httpPort, ... }
 
 `runFromEnv` reads the engine address and transport from the environment, starts
 the app (validate → deploy → provision datasources → start workers → serve
-surfaces and webhook triggers), and installs SIGINT/SIGTERM handlers for a
+surfaces and webhook + cron triggers), and installs SIGINT/SIGTERM handlers for a
 graceful shutdown. For full control, assemble the pieces yourself:
 
 ```ts
@@ -141,6 +141,37 @@ wiring; `WorkflowClient` deploys and starts, `Worker` hosts your `run` steps.
 inspectable in a modeller/Operate — `@nanobpm/urban` bundles `bpmn-auto-layout`
 so this works out of the box.
 
+### Triggers — the inbound I/O edge
+
+Declare `triggers[]` in the app manifest to turn outside events into engine
+calls (start a process or publish a message). Two source kinds are built in:
+
+- **`webhook`** — mounts an HTTP `POST` route (`/hooks/<id>` by default), with
+  optional `hmac:<connection>` signature verification and delivery-id
+  idempotency.
+- **`cron`** — arms a background timer from a 5-field crontab `spec` (evaluated
+  in **UTC**), firing its `action` on schedule and rescheduling itself.
+
+```jsonc
+{
+  "triggers": [
+    { "id": "nightly", "type": "cron", "spec": "0 6 * * *",
+      "action": { "start": "daily-report" } },
+    { "id": "gh", "type": "webhook", "auth": "hmac:github",
+      "action": { "message": "pr-opened", "correlationKey": "= body.number" } }
+  ]
+}
+```
+
+Cron scheduling is **app-side**: per-replica, in-memory, and it stops when the
+process stops — glue for invoking handlers on a clock, not a durable clustered
+scheduler. It therefore only honours `onMissed: "skip"` (the default); a declared
+`"once"`/`"all"` catch-up needs a persisted last-fire the runtime does not keep,
+so it warns and degrades to `skip`. For **durable, clustered** scheduling that
+survives restarts, model a timer **start**/**intermediate** event instead with
+`w.startOn(...)` / `w.timer(...)` from [`@nanobpm/workflow`](../workflow) — the
+engine owns those.
+
 ## Related packages
 
 - [`@nanobpm/workflow`](../workflow) — the code-first process surface (`defineFlow`).

package/dist/runtime/core/manifest.d.ts

@@ -46,9 +46,28 @@ export interface TriggerDecl {
     type: string;
     path?: string;
     auth?: string;
+    /** cron: the 5-field crontab spec (UTC), e.g. "0 6 * * *". */
+    spec?: string;
+    /** cron catch-up policy for fires missed while the app was down. Default "skip". */
+    onMissed?: "skip" | "once" | "all";
+    /** Source-kind-specific settings (e.g. file `{ pollMs }`). */
+    config?: Record<string, unknown>;
+    /** Name of a connections[] entry supplying this source's credentials. */
+    connection?: string;
+    /** Maps the event to one engine call: start a process OR publish a message (ADR 0025 §1). */
     action?: {
+        /** Process id/name to start. */
+        start?: string;
+        /** messageName to publish as a CorrelateMessage. */
         message?: string;
+        /** correlationKey (literal, or `= body.path`) for a message action. */
         correlationKey?: string;
+        /**
+         * Variables for the started instance / published message. Per the manifest schema
+         * (`#/$defs/triggerAction.variables`) this is a FEEL string over the event body
+         * (e.g. `= body.payload`); an inline object literal is also accepted for convenience.
+         */
+        variables?: string | Record<string, unknown>;
     };
 }
 export interface SurfaceDecl {

package/dist/runtime/core/modules/cron.d.ts

@@ -0,0 +1,27 @@
+/** A parsed schedule: the allowed value set per field, plus whether dom/dow are wildcards. */
+export interface CronSchedule {
+    minutes: Set<number>;
+    hours: Set<number>;
+    daysOfMonth: Set<number>;
+    months: Set<number>;
+    daysOfWeek: Set<number>;
+    /** dom / dow were `*` (unrestricted) — controls the OR-vs-AND day rule. */
+    domWildcard: boolean;
+    dowWildcard: boolean;
+}
+/** Parse a 5-field crontab spec into a `CronSchedule`. Throws on a malformed spec. */
+export declare function parseCron(spec: string): CronSchedule;
+/** Does `date` (read in UTC) match the schedule? */
+export declare function cronMatches(s: CronSchedule, date: Date): boolean;
+/**
+ * The first fire strictly after `after`. Scans minute-by-minute (UTC) up to a bounded
+ * horizon; returns `undefined` if nothing matches within ~4 years (an impossible spec,
+ * e.g. Feb 30). The bound keeps a pathological spec from spinning forever.
+ */
+export declare function nextCronFire(s: CronSchedule, after: Date): Date | undefined;
+/**
+ * The fire instants strictly between `after` and `until` (both exclusive on `after`,
+ * inclusive on `until`). Used by the `onMissed` catch-up policy to enumerate fires that
+ * were due while the app was down. Bounded to avoid unbounded output on a huge gap.
+ */
+export declare function cronFiresBetween(s: CronSchedule, after: Date, until: Date, max?: number): Date[];

package/dist/runtime/core/modules/cron.js

@@ -0,0 +1,138 @@
+// A small, dependency-free 5-field crontab evaluator (ADR 0025 §2) — the schedule engine
+// behind `cron` triggers. Specs are evaluated in **UTC**. Fields, in order:
+//
+//   minute (0-59)  hour (0-23)  day-of-month (1-31)  month (1-12)  day-of-week (0-6, 0=Sun)
+//
+// Each field supports `*`, a number, `a-b` ranges, `*/n` and `a-b/n` steps, and comma lists
+// of any of those. Month and day-of-week also accept three-letter names (jan…dec, sun…sat).
+// Day-of-month and day-of-week follow the standard cron rule: when **both** are restricted
+// (neither is `*`), a day matches if it satisfies **either** field.
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DOWS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+function nameToNumber(token, names, offset) {
+    const i = names.indexOf(token.toLowerCase());
+    return i >= 0 ? String(i + offset) : token;
+}
+/** Parse one field into the set of matching integers in [min,max]. */
+function parseField(field, min, max, names) {
+    const out = new Set();
+    for (const partRaw of field.split(",")) {
+        const part = partRaw.trim();
+        if (part === "")
+            throw new Error(`cron: empty term in "${field}"`);
+        let step = 1;
+        let range = part;
+        const slash = part.indexOf("/");
+        if (slash >= 0) {
+            range = part.slice(0, slash);
+            if (range === "")
+                throw new Error(`cron: missing range before "/" in "${part}"`);
+            const stepText = part.slice(slash + 1);
+            step = Number(stepText);
+            if (stepText === "" || !Number.isInteger(step) || step <= 0) {
+                throw new Error(`cron: bad step in "${part}"`);
+            }
+        }
+        let lo;
+        let hi;
+        if (range === "*") {
+            lo = min;
+            hi = max;
+        }
+        else {
+            const dash = range.indexOf("-", range.startsWith("-") ? 1 : 0);
+            if (dash > 0) {
+                lo = Number(names ? nameToNumber(range.slice(0, dash), names, min) : range.slice(0, dash));
+                hi = Number(names ? nameToNumber(range.slice(dash + 1), names, min) : range.slice(dash + 1));
+            }
+            else {
+                lo = hi = Number(names ? nameToNumber(range, names, min) : range);
+            }
+        }
+        if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo < min || hi > max || lo > hi) {
+            throw new Error(`cron: value out of range [${min},${max}] in "${part}"`);
+        }
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+/** Parse a 5-field crontab spec into a `CronSchedule`. Throws on a malformed spec. */
+export function parseCron(spec) {
+    const fields = spec.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`cron: expected 5 fields, got ${fields.length} in "${spec}"`);
+    }
+    const [min, hr, dom, mon, dow] = fields;
+    // Normalise day-of-week 7 → 0 (both are Sunday in common cron dialects).
+    const daysOfWeek = parseField(dow, 0, 7, DOWS);
+    if (daysOfWeek.delete(7))
+        daysOfWeek.add(0);
+    return {
+        minutes: parseField(min, 0, 59),
+        hours: parseField(hr, 0, 23),
+        daysOfMonth: parseField(dom, 1, 31),
+        months: parseField(mon, 1, 12, MONTHS),
+        daysOfWeek,
+        // The OR-vs-AND day rule keys off whether dom/dow are "star" fields. Following Vixie
+        // cron, a field counts as a wildcard when it *starts* with `*` (so `*` and `*/n` both
+        // qualify); an explicit full range like `1-31` is a restricted field, not a wildcard.
+        domWildcard: dom.trim().startsWith("*"),
+        dowWildcard: dow.trim().startsWith("*"),
+    };
+}
+/** Does `date` (read in UTC) match the schedule? */
+export function cronMatches(s, date) {
+    if (!s.minutes.has(date.getUTCMinutes()))
+        return false;
+    if (!s.hours.has(date.getUTCHours()))
+        return false;
+    if (!s.months.has(date.getUTCMonth() + 1))
+        return false;
+    const domHit = s.daysOfMonth.has(date.getUTCDate());
+    const dowHit = s.daysOfWeek.has(date.getUTCDay());
+    // Standard cron day rule: both restricted → OR; otherwise the restricted one(s) must hit.
+    if (!s.domWildcard && !s.dowWildcard)
+        return domHit || dowHit;
+    if (!s.domWildcard)
+        return domHit;
+    if (!s.dowWildcard)
+        return dowHit;
+    return true;
+}
+/** Ceiling to the start of the next minute (UTC), so scheduling lands on minute boundaries. */
+function nextMinute(after) {
+    const d = new Date(after.getTime());
+    d.setUTCSeconds(0, 0);
+    d.setUTCMinutes(d.getUTCMinutes() + 1);
+    return d;
+}
+/**
+ * The first fire strictly after `after`. Scans minute-by-minute (UTC) up to a bounded
+ * horizon; returns `undefined` if nothing matches within ~4 years (an impossible spec,
+ * e.g. Feb 30). The bound keeps a pathological spec from spinning forever.
+ */
+export function nextCronFire(s, after) {
+    let cur = nextMinute(after);
+    const limit = 4 * 366 * 24 * 60; // minutes in ~4 years
+    for (let i = 0; i < limit; i++) {
+        if (cronMatches(s, cur))
+            return cur;
+        cur = new Date(cur.getTime() + 60_000);
+    }
+    return undefined;
+}
+/**
+ * The fire instants strictly between `after` and `until` (both exclusive on `after`,
+ * inclusive on `until`). Used by the `onMissed` catch-up policy to enumerate fires that
+ * were due while the app was down. Bounded to avoid unbounded output on a huge gap.
+ */
+export function cronFiresBetween(s, after, until, max = 10_000) {
+    const fires = [];
+    let next = nextCronFire(s, after);
+    while (next && next.getTime() <= until.getTime() && fires.length < max) {
+        fires.push(next);
+        next = nextCronFire(s, next);
+    }
+    return fires;
+}

package/dist/runtime/core/modules/triggers.d.ts

@@ -1,15 +1,49 @@
-import type { AppApi, RuntimeContext } from "../context.ts";
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import { type Route } from "../router.ts";
-export interface TriggersHandle {
-    readonly name: string;
+import type { TriggerDecl } from "../manifest.ts";
+export interface TriggersHandle extends Mounted {
     routes: Route[];
-    describe(): Record<string, unknown>;
 }
-/** Evaluate a tiny correlation expression: `= body.a.b`, or a literal string. */
-export declare function evalCorrelation(expr: string | undefined, scope: {
+/** Injectable timer + clock seam so cron scheduling is deterministic under test. */
+export interface SchedulerDeps {
+    setTimer: (fn: () => void, delayMs: number) => unknown;
+    clearTimer: (handle: unknown) => void;
+    /** Current wall-clock time in ms since epoch. */
+    now: () => number;
+}
+type Scope = {
     body: unknown;
     headers: Record<string, string>;
     query: Record<string, string>;
-}): string | undefined;
-/** Mount webhook triggers and return their routes. */
-export declare function mountTriggers(ctx: RuntimeContext, app: AppApi): TriggersHandle;
+};
+/**
+ * Resolve a tiny FEEL-ish expression against the event scope: a `= body.a.b` path walk
+ * returns the raw value at that path (or `undefined` if any segment is missing); a literal
+ * (non-`=`) string is returned verbatim.
+ */
+export declare function resolveExpr(expr: string, scope: Scope): unknown;
+/** Evaluate a correlation expression to a string key: `= body.a.b`, or a literal string. */
+export declare function evalCorrelation(expr: string | undefined, scope: Scope): string | undefined;
+/**
+ * Resolve `action.variables` to the record handed to the engine (schema: a FEEL string over
+ * the event body — `#/$defs/triggerAction.variables`). A `= body.<path>` expression must
+ * resolve to an object; a plain object literal is accepted for convenience; anything else
+ * (missing, or a non-object result) falls back to the raw event body when that is an object,
+ * else `{}`.
+ */
+export declare function resolveActionVariables(expr: unknown, scope: Scope): Record<string, unknown>;
+/**
+ * Fire a trigger's action against the engine: start a process or publish a message
+ * (ADR 0025 §1). `scope` supplies the event body/headers/query for FEEL-ish resolution
+ * of `correlationKey`/`variables`; cron passes a minimal `{ firedAt }` body. Returns what
+ * was done.
+ */
+export declare function runTriggerAction(app: AppApi, action: TriggerDecl["action"], scope: Scope): Promise<{
+    kind: "start" | "message" | "none";
+    target?: string;
+    correlationKey?: string;
+}>;
+/** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
+ *  background timers that fire their action on schedule. `stop()` clears every timer. */
+export declare function mountTriggers(ctx: RuntimeContext, app: AppApi, sched?: SchedulerDeps): TriggersHandle;
+export {};

package/dist/runtime/core/modules/triggers.js

@@ -3,24 +3,54 @@
 // message to the engine for correlation. HMAC verification uses Web Crypto (global in both
 // Node 18+ and Deno), so this stays runtime-agnostic.
 import { json, normalizeRoutePath } from "../router.js";
-/** Evaluate a tiny correlation expression: `= body.a.b`, or a literal string. */
-export function evalCorrelation(expr, scope) {
-    if (!expr)
-        return undefined;
+import { nextCronFire, parseCron } from "./cron.js";
+/**
+ * Resolve a tiny FEEL-ish expression against the event scope: a `= body.a.b` path walk
+ * returns the raw value at that path (or `undefined` if any segment is missing); a literal
+ * (non-`=`) string is returned verbatim.
+ */
+export function resolveExpr(expr, scope) {
     const trimmed = expr.trim();
     if (!trimmed.startsWith("="))
         return trimmed; // literal
     const pathExpr = trimmed.slice(1).trim(); // e.g. "body.taskId"
     let cur = scope;
     for (const seg of pathExpr.split(".")) {
-        if (cur && typeof cur === "object" && seg in cur) {
+        if (cur && typeof cur === "object" && Object.prototype.hasOwnProperty.call(cur, seg)) {
             cur = cur[seg];
         }
         else {
             return undefined;
         }
     }
-    return cur == null ? undefined : String(cur);
+    return cur;
+}
+/** Evaluate a correlation expression to a string key: `= body.a.b`, or a literal string. */
+export function evalCorrelation(expr, scope) {
+    if (!expr)
+        return undefined;
+    const cur = resolveExpr(expr, scope);
+    // A correlation key must be scalar; a non-scalar (object/array) is not a usable key —
+    // return undefined rather than forcing a "[object Object]" string.
+    if (typeof cur === "string" || typeof cur === "number" || typeof cur === "boolean") {
+        return String(cur);
+    }
+    return undefined;
+}
+/**
+ * Resolve `action.variables` to the record handed to the engine (schema: a FEEL string over
+ * the event body — `#/$defs/triggerAction.variables`). A `= body.<path>` expression must
+ * resolve to an object; a plain object literal is accepted for convenience; anything else
+ * (missing, or a non-object result) falls back to the raw event body when that is an object,
+ * else `{}`.
+ */
+export function resolveActionVariables(expr, scope) {
+    const asRecord = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+    if (typeof expr === "string") {
+        return asRecord(resolveExpr(expr, scope)) ?? asRecord(scope.body) ?? {};
+    }
+    // Back-compat: an inline object literal used directly as the variables.
+    return asRecord(expr) ?? asRecord(scope.body) ?? {};
 }
 async function verifyHmac(secret, body, signature) {
     const enc = new TextEncoder();
@@ -45,12 +75,136 @@ function headerRecord(req) {
     req.headers.forEach((v, k) => (out[k.toLowerCase()] = v));
     return out;
 }
-/** Mount webhook triggers and return their routes. */
-export function mountTriggers(ctx, app) {
+/**
+ * Fire a trigger's action against the engine: start a process or publish a message
+ * (ADR 0025 §1). `scope` supplies the event body/headers/query for FEEL-ish resolution
+ * of `correlationKey`/`variables`; cron passes a minimal `{ firedAt }` body. Returns what
+ * was done.
+ */
+export async function runTriggerAction(app, action, scope) {
+    if (!action)
+        return { kind: "none" };
+    const variables = resolveActionVariables(action.variables, scope);
+    if (action.start) {
+        await app.engine.createInstance({ processDefinitionId: action.start, variables });
+        return { kind: "start", target: action.start };
+    }
+    if (action.message) {
+        const correlationKey = evalCorrelation(action.correlationKey, scope);
+        await app.engine.publishMessage({ name: action.message, correlationKey, variables });
+        return { kind: "message", target: action.message, correlationKey };
+    }
+    return { kind: "none" };
+}
+const emptyScope = { body: {}, headers: {}, query: {} };
+/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Default (live) scheduler seam, backed by the global timer functions. */
+function defaultScheduler() {
+    return {
+        setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+        clearTimer: (h) => globalThis.clearTimeout(h),
+        now: () => Date.now(),
+    };
+}
+/** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
+ *  background timers that fire their action on schedule. `stop()` clears every timer. */
+export function mountTriggers(ctx, app, sched = defaultScheduler()) {
     const routes = [];
     const mounted = [];
+    const scheduled = [];
     const seenDeliveries = new Set();
+    const timers = new Set();
+    let stopped = false;
+    // Arm a cron trigger: compute the next UTC fire, sleep until it, fire the action, repeat.
+    const armCron = (trig) => {
+        const spec = trig.spec;
+        if (!spec) {
+            ctx.host.log("warn", `trigger "${trig.id}": cron trigger has no spec, skipped`);
+            return;
+        }
+        let schedule;
+        try {
+            schedule = parseCron(spec);
+        }
+        catch (e) {
+            app.log("error", `trigger "${trig.id}": invalid cron spec "${spec}": ${String(e)}`);
+            return;
+        }
+        if (!trig.action?.start && !trig.action?.message) {
+            // A timer that can never do anything is pure waste — don't arm it (unlike a webhook,
+            // which is request-driven and costs nothing while idle).
+            app.log("warn", `trigger "${trig.id}": cron trigger has no action.start/message; not scheduled`);
+            return;
+        }
+        if (trig.onMissed && trig.onMissed !== "skip") {
+            // once/all catch-up needs a durable last-fire timestamp the runtime does not persist;
+            // without it, honour the safe default (skip) and say so rather than silently dropping.
+            app.log("warn", `trigger "${trig.id}": onMissed="${trig.onMissed}" not supported without ` +
+                `durable trigger state; scheduling forward as "skip"`);
+        }
+        // Probe the first fire before recording the trigger as scheduled, so an impossible spec
+        // (e.g. Feb 30) is reported honestly and never shows up in describe()/startup logs.
+        if (!nextCronFire(schedule, new Date(sched.now()))) {
+            app.log("warn", `trigger "${trig.id}": cron spec "${spec}" never fires; not scheduled`);
+            return;
+        }
+        scheduled.push(`${trig.id}@${spec}`);
+        const arm = () => {
+            if (stopped)
+                return;
+            // Capture the clock once so `next` and `delay` are derived from the same instant.
+            const nowMs = sched.now();
+            const next = nextCronFire(schedule, new Date(nowMs));
+            if (!next)
+                return; // spec became unsatisfiable (defensive; the probe above already vetted it)
+            const remaining = Math.max(0, next.getTime() - nowMs);
+            // setTimeout delays are clamped to a 32-bit signed int (~24.8 days); a larger delay
+            // overflows and fires immediately. For far-future fires (monthly/annual specs), sleep in
+            // bounded chunks and re-arm — without firing — until the real deadline is within range.
+            if (remaining > MAX_TIMER_DELAY_MS) {
+                let chunk;
+                chunk = sched.setTimer(() => {
+                    timers.delete(chunk);
+                    if (stopped)
+                        return;
+                    arm();
+                }, MAX_TIMER_DELAY_MS);
+                timers.add(chunk);
+                return;
+            }
+            // Declare `handle` before arming so the callback can reference it even if a scheduler
+            // double invokes it synchronously (avoids a TDZ ReferenceError on `timers.delete`).
+            let handle;
+            handle = sched.setTimer(() => {
+                timers.delete(handle);
+                if (stopped)
+                    return;
+                void (async () => {
+                    try {
+                        const res = await runTriggerAction(app, trig.action, {
+                            ...emptyScope,
+                            body: { firedAt: next.toISOString() },
+                        });
+                        app.log("info", `trigger "${trig.id}" fired`, { firedAt: next.toISOString(), ...res });
+                    }
+                    catch (err) {
+                        app.log("error", `trigger "${trig.id}": action failed`, { error: String(err) });
+                    }
+                    finally {
+                        arm(); // reschedule regardless of success (at-least-once, idempotent handlers)
+                    }
+                })();
+            }, remaining);
+            timers.add(handle);
+        };
+        arm();
+    };
     for (const trig of (ctx.manifest.triggers ?? [])) {
+        if (trig.type === "cron") {
+            armCron(trig);
+            continue;
+        }
         if (trig.type !== "webhook") {
             ctx.host.log("warn", `trigger "${trig.id}": type "${trig.type}" not implemented, skipped`);
             continue;
@@ -94,26 +248,31 @@ export function mountTriggers(ctx, app) {
                 catch {
                     return json({ error: "body must be JSON" }, 400);
                 }
-                const message = trig.action?.message;
-                if (!message) {
-                    app.log("warn", `trigger "${trig.id}": no action.message; nothing published`);
-                    return json({ ok: true, published: false });
+                if (!trig.action?.message && !trig.action?.start) {
+                    app.log("warn", `trigger "${trig.id}": no action.message/start; nothing to do`);
+                    return json({ ok: true, fired: false });
                 }
-                const correlationKey = evalCorrelation(trig.action?.correlationKey, {
+                const res = await runTriggerAction(app, trig.action, {
                     body,
                     headers,
                     query: Object.fromEntries(req.query),
                 });
-                await app.engine.publishMessage({
-                    name: message,
-                    correlationKey,
-                    variables: (body && typeof body === "object" ? body : {}),
-                });
-                app.log("info", `trigger "${trig.id}" published`, { message, correlationKey });
-                return json({ ok: true, published: true, message, correlationKey });
+                // `res.kind` is the honest verb (start | message); don't hard-code "published".
+                app.log("info", `trigger "${trig.id}" fired`, { ...res });
+                return json({ ok: true, fired: true, ...res });
             },
         });
     }
-    ctx.host.log("info", "triggers mounted", { mounted });
-    return { name: "triggers", routes, describe: () => ({ mounted }) };
+    ctx.host.log("info", "triggers mounted", { mounted, scheduled });
+    return {
+        name: "triggers",
+        routes,
+        describe: () => ({ mounted, scheduled }),
+        async stop() {
+            stopped = true;
+            for (const h of timers)
+                sched.clearTimer(h);
+            timers.clear();
+        },
+    };
 }

package/dist/runtime/core/runtime.js

@@ -132,7 +132,8 @@ export async function createUrbanApp(opts) {
                 if (flags.triggers) {
                     const t = mountTriggers(ctx, api);
                     routes.push(...t.routes);
-                    describe.triggers = t.describe();
+                    mounted.push(t);
+                    describe.triggers = t.describe?.();
                 }
                 if (security)
                     describe.security = security.describe();

package/dist/runtime/engine/nanosdk.d.ts

@@ -26,7 +26,8 @@ export interface NanoSdkJobWorkerConfig {
     jobTimeoutMs?: number;
     pollTimeoutMs?: number;
     fetchVariables?: string[];
-    /** Start polling immediately. This adapter sets it false and starts explicitly. */
+    /** Start polling immediately (the SDK default). The adapter leaves this unset so the
+     * SDK owns the start lifecycle after its async Nano/Falcon transport detection. */
     autoStart?: boolean;
 }
 /** The handle returned by `createJobWorker`. */
@@ -69,6 +70,10 @@ export interface NanoSdkClient {
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
     createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
+    /** Stop every worker created on this client. Used on teardown to also drain a
+     * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
+     * and does not hand back. Optional: not every injected client implements it. */
+    stopAllWorkers?(): void | Promise<void>;
     close?(): void | Promise<void>;
 }
 type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;

package/dist/runtime/engine/nanosdk.js

@@ -103,9 +103,6 @@ export class SdkEngineClient {
             workerName: options?.workerName ?? `urban:${jobType}`,
             maxParallelJobs: options?.maxParallelJobs ?? 8,
             fetchVariables: options?.fetchVariables,
-            // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
-            // default, so nothing polls until `start()` is called below.
-            autoStart: false,
             jobHandler: async (job) => {
                 const rawKey = job.jobKey;
                 if (rawKey == null || rawKey === "") {
@@ -138,7 +135,11 @@ export class SdkEngineClient {
                 }
             },
         });
-        await worker.start();
+        // The nano-sdk job worker owns its own start lifecycle: `createJobWorker` runs
+        // async Nano/Falcon detection and, once the transport is bound, starts polling
+        // itself (Falcon) or hands off to an auto-started REST worker. Calling `start()`
+        // here would race that detection and dereference a still-null transport, so we
+        // don't — the worker autostarts.
         this.workers.add(worker);
         return {
             jobType,
@@ -162,6 +163,14 @@ export class SdkEngineClient {
         for (const w of this.workers)
             await this.stopWorker(w);
         this.workers.clear();
+        try {
+            // Also drain any REST-fallback worker the SDK started internally (its handle is
+            // not the one we hold), which `stopWorker` above cannot reach.
+            await this.client.stopAllWorkers?.();
+        }
+        catch {
+            /* no workers running / already stopped */
+        }
         try {
             await this.client.close?.();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",

package/src/runtime/core/manifest.ts

@@ -55,7 +55,29 @@ export interface TriggerDecl {
   type: string;
   path?: string;
   auth?: string;
-  action?: { message?: string; correlationKey?: string };
+  /** cron: the 5-field crontab spec (UTC), e.g. "0 6 * * *". */
+  spec?: string;
+  /** cron catch-up policy for fires missed while the app was down. Default "skip". */
+  onMissed?: "skip" | "once" | "all";
+  /** Source-kind-specific settings (e.g. file `{ pollMs }`). */
+  config?: Record<string, unknown>;
+  /** Name of a connections[] entry supplying this source's credentials. */
+  connection?: string;
+  /** Maps the event to one engine call: start a process OR publish a message (ADR 0025 §1). */
+  action?: {
+    /** Process id/name to start. */
+    start?: string;
+    /** messageName to publish as a CorrelateMessage. */
+    message?: string;
+    /** correlationKey (literal, or `= body.path`) for a message action. */
+    correlationKey?: string;
+    /**
+     * Variables for the started instance / published message. Per the manifest schema
+     * (`#/$defs/triggerAction.variables`) this is a FEEL string over the event body
+     * (e.g. `= body.payload`); an inline object literal is also accepted for convenience.
+     */
+    variables?: string | Record<string, unknown>;
+  };
 }
 
 export interface SurfaceDecl {