@pattern-js/runtime-node 0.2.0

package/dist/load/report.js

@@ -0,0 +1,84 @@
+/**
+ * Stage statistics + the terminal report. Latency percentiles come from the
+ * SCHEDULED-time deltas (queueing included); the flight recording, when
+ * present, is printed beneath each stage so the bottleneck reads next to the
+ * symptom.
+ */
+const pct = (sorted, p) => {
+    if (!sorted.length)
+        return 0;
+    const i = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+    return Math.round(sorted[i] * 100) / 100;
+};
+export function summarize(stage, samples, flight) {
+    const lat = samples.map((s) => s.endedAt - s.scheduledAt).sort((a, b) => a - b);
+    const ok = samples.filter((s) => s.ok).length;
+    const span = samples.length ? (Math.max(...samples.map((s) => s.endedAt)) - Math.min(...samples.map((s) => s.scheduledAt))) / 1000 : 0;
+    const byStatus = {};
+    for (const s of samples) {
+        const key = s.status === 0 ? "ERR" : String(s.status);
+        byStatus[key] = (byStatus[key] ?? 0) + 1;
+    }
+    return {
+        stage,
+        requests: samples.length,
+        ok,
+        errors: samples.length - ok,
+        achievedRate: span > 0 ? Math.round(samples.length / span) : samples.length,
+        p50: pct(lat, 50),
+        p90: pct(lat, 90),
+        p99: pct(lat, 99),
+        max: Math.round((lat.at(-1) ?? 0) * 100) / 100,
+        mean: lat.length ? Math.round((lat.reduce((s, v) => s + v, 0) / lat.length) * 100) / 100 : 0,
+        bytesTotal: samples.reduce((s, v) => s + v.bytes, 0),
+        byStatus,
+        flight,
+    };
+}
+const c = {
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+};
+const ms = (n) => `${n}ms`;
+export function printStage(s) {
+    const errRate = s.requests ? s.errors / s.requests : 0;
+    const head = `${c.bold(`${s.stage.rate}/s`)} ${c.dim(`for ${s.stage.durationMs / 1000}s`)} → ${s.requests} reqs, ${c.bold(`${s.achievedRate}/s`)} achieved`;
+    console.log(`\n  ${head}`);
+    const statusStr = Object.entries(s.byStatus)
+        .map(([k, v]) => (k.startsWith("2") ? c.green(`${k}×${v}`) : c.red(`${k}×${v}`)))
+        .join(" ");
+    console.log(`    ${c.dim("status:")} ${statusStr}${errRate > 0.01 ? c.red(`  (${(errRate * 100).toFixed(1)}% errors)`) : ""}`);
+    console.log(`    ${c.dim("latency:")} p50 ${c.cyan(ms(s.p50))}  p90 ${c.cyan(ms(s.p90))}  p99 ${c.yellow(ms(s.p99))}  max ${ms(s.max)}  ${c.dim(`mean ${ms(s.mean)}`)}`);
+    if (s.flight && s.flight.spans > 0) {
+        const f = s.flight;
+        console.log(`    ${c.dim("engine:")} ${f.runs} runs, peak concurrency ${c.bold(String(f.maxConcurrency))}${f.runErrors ? c.red(`, ${f.runErrors} run errors`) : ""}`);
+        const top = f.ops.slice(0, 5);
+        const totalOp = f.ops.reduce((sum, o) => sum + o.totalMs, 0) || 1;
+        console.log(`    ${c.dim("where the time went (by op, total span ms):")}`);
+        for (const o of top) {
+            const share = Math.round((o.totalMs / totalOp) * 100);
+            const bar = "█".repeat(Math.max(1, Math.round(share / 5)));
+            console.log(`      ${c.cyan(o.op.padEnd(26))} ${c.dim(`${bar} ${share}%`)}  ${o.count}× · p99 ${ms(o.p99)}${o.errors ? c.red(` · ${o.errors} err`) : ""}`);
+        }
+    }
+}
+/** The saturation verdict: the last stage whose p99 + error rate stayed sane. */
+export function printSweepVerdict(stages, p99BudgetMs) {
+    const knee = stages.find((s) => s.p99 > p99BudgetMs || s.errors / Math.max(1, s.requests) > 0.02);
+    const sustainable = knee ? stages[stages.indexOf(knee) - 1] : stages.at(-1);
+    console.log(`\n  ${c.bold("Saturation sweep")}`);
+    if (sustainable) {
+        console.log(`    max sustainable ≈ ${c.green(c.bold(`${sustainable.achievedRate}/s`))} ${c.dim(`(p99 ${ms(sustainable.p99)}, ${(sustainable.errors / Math.max(1, sustainable.requests) * 100).toFixed(1)}% err)`)}`);
+    }
+    if (knee) {
+        console.log(`    knee at ${c.yellow(`${knee.stage.rate}/s`)}: ${c.dim(`p99 jumped to ${ms(knee.p99)}`)}${knee.flight ? c.dim(`, top op ${knee.flight.ops[0]?.op ?? "?"}`) : ""}`);
+    }
+    else {
+        console.log(`    ${c.dim(`no knee within the swept range — budget p99 ${ms(p99BudgetMs)} never exceeded`)}`);
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/load/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/load/report.ts"],"names":[],"mappings":"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"}

package/dist/load/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @pattern-js/runtime-node — load-testing scenario schema (`pattern load`).
+ *
+ * A scenario is DATA (like everything in Pattern): versioned, diffable,
+ * committable. v1 fires HTTP requests at a workflow app under an OPEN-LOOP
+ * arrival schedule (requests launch at a fixed rate regardless of how many are
+ * in flight — closed-loop concurrency self-throttles and lies about capacity).
+ * The differentiator is the engine FLIGHT RECORDER: when the app boots
+ * in-process, a trace sink attributes client latency to per-node span time, so
+ * the report says *where* the pressure is, not just that there is some.
+ */
+import { z } from "@pattern-js/core";
+/** One request shape the generator can fire (chosen by weight). */
+export declare const LoadRequestSchema: z.ZodObject<{
+    weight: z.ZodDefault<z.ZodNumber>;
+    method: z.ZodDefault<z.ZodString>;
+    path: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodUnknown>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LoadRequest = z.infer<typeof LoadRequestSchema>;
+/** A constant-rate phase: `rate` requests/second for `durationMs`. */
+export declare const LoadStageSchema: z.ZodObject<{
+    rate: z.ZodNumber;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+export type LoadStage = z.infer<typeof LoadStageSchema>;
+export declare const LoadScenarioSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<1>>;
+    entry: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    warmup: z.ZodOptional<z.ZodObject<{
+        rate: z.ZodNumber;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>;
+    stages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        rate: z.ZodNumber;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>>;
+    requests: z.ZodArray<z.ZodObject<{
+        weight: z.ZodDefault<z.ZodNumber>;
+        method: z.ZodDefault<z.ZodString>;
+        path: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    maxInflight: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type LoadScenario = z.infer<typeof LoadScenarioSchema>;
+/** One completed request observation. */
+export interface RequestSample {
+    /** When this request was SCHEDULED to fire (open-loop reference). */
+    scheduledAt: number;
+    /** When it actually went out (scheduledAt + scheduling lag). */
+    sentAt: number;
+    endedAt: number;
+    status: number;
+    ok: boolean;
+    bytes: number;
+    label: string;
+    error?: string;
+}
+/** Per-op rollup from the flight recorder (one window). */
+export interface OpStat {
+    op: string;
+    count: number;
+    totalMs: number;
+    selfMs: number;
+    p50: number;
+    p99: number;
+    errors: number;
+}
+/** What the recorder observed during a window. */
+export interface FlightRecording {
+    spans: number;
+    runs: number;
+    runErrors: number;
+    maxConcurrency: number;
+    ops: OpStat[];
+    /** Wall time the window covered (ms). */
+    windowMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/load/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/load/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAErC,mEAAmE;AACnE,eAAO,MAAM,iBAAiB;;;;;;;iBAW5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,sEAAsE;AACtE,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;iBAmB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2DAA2D;AAC3D,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/load/types.js

@@ -0,0 +1,51 @@
+/**
+ * @pattern-js/runtime-node — load-testing scenario schema (`pattern load`).
+ *
+ * A scenario is DATA (like everything in Pattern): versioned, diffable,
+ * committable. v1 fires HTTP requests at a workflow app under an OPEN-LOOP
+ * arrival schedule (requests launch at a fixed rate regardless of how many are
+ * in flight — closed-loop concurrency self-throttles and lies about capacity).
+ * The differentiator is the engine FLIGHT RECORDER: when the app boots
+ * in-process, a trace sink attributes client latency to per-node span time, so
+ * the report says *where* the pressure is, not just that there is some.
+ */
+import { z } from "@pattern-js/core";
+/** One request shape the generator can fire (chosen by weight). */
+export const LoadRequestSchema = z.object({
+    /** Relative pick weight among requests (default 1). */
+    weight: z.number().positive().default(1),
+    method: z.string().default("GET"),
+    /** Path or absolute URL. Relative paths resolve against the target base URL. */
+    path: z.string(),
+    headers: z.record(z.string(), z.string()).optional(),
+    /** Request body — a string sent as-is, or an object sent as JSON. */
+    body: z.unknown().optional(),
+    /** A label for the report (defaults to "METHOD path"). */
+    label: z.string().optional(),
+});
+/** A constant-rate phase: `rate` requests/second for `durationMs`. */
+export const LoadStageSchema = z.object({
+    rate: z.number().positive(),
+    durationMs: z.number().int().positive(),
+});
+export const LoadScenarioSchema = z.object({
+    version: z.literal(1).default(1),
+    /**
+     * Project entry to BOOT in-process (default "src/index.ts" when present).
+     * Booting in-process is what unlocks the flight recorder. Set `false` to
+     * skip booting and fire at an already-running `baseUrl` (client metrics
+     * only — no span attribution).
+     */
+    entry: z.union([z.string(), z.literal(false)]).optional(),
+    /** Where to fire. Defaults to the booted host's first port. */
+    baseUrl: z.string().optional(),
+    /** A gentle phase before measurement (JIT warmup, pool spin-up). */
+    warmup: LoadStageSchema.optional(),
+    /** The measured phases, run in order. */
+    stages: z.array(LoadStageSchema).default([{ rate: 50, durationMs: 10_000 }]),
+    /** The request mix. */
+    requests: z.array(LoadRequestSchema).min(1),
+    /** Safety cap on simultaneously in-flight requests (default 10k). */
+    maxInflight: z.number().int().positive().default(10_000),
+});
+//# sourceMappingURL=types.js.map

package/dist/load/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/load/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAErC,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,uDAAuD;IACvD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACjC,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpD,qEAAqE;IACrE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5B,0DAA0D;IAC1D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAGH,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAChC;;;;;OAKG;IACH,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzD,+DAA+D;IAC/D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,oEAAoE;IACpE,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE;IAClC,yCAAyC;IACzC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5E,uBAAuB;IACvB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,qEAAqE;IACrE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;CACzD,CAAC,CAAC"}

package/dist/mods.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @pattern-js/runtime-node — mod loading (§13, §16/14).
+ *
+ * Loads "mods" (plugins) and installs them into an engine. A mod is any module
+ * that exports a `PatternMod` (default export, or named `mod`). Three sources,
+ * all the same mechanism:
+ *
+ *  - **1st-party** mods in this monorepo (`@pattern-js/mod-*`) — a bare specifier.
+ *  - **3rd-party** mods published to npm — a bare specifier (an npm dependency).
+ *  - **app-local** mods — a relative path (`./mods/foo.ts`), resolved against a
+ *    base dir (the app root / config location).
+ *
+ * Mods may contribute ops, workflows, auth providers, and hooks; bringing a
+ * frontend app is a future field on `PatternMod`.
+ */
+import type { Engine, PatternMod } from "@pattern-js/core";
+export interface LoadModsOptions {
+    /** Base dir for resolving relative (app-local) mod specifiers. Default cwd. */
+    baseDir?: string;
+}
+/** Dynamically import each specifier and install the exported mod. */
+export declare function loadMods(engine: Engine, specifiers: string[], opts?: LoadModsOptions): Promise<PatternMod[]>;
+//# sourceMappingURL=mods.d.ts.map

package/dist/mods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mods.d.ts","sourceRoot":"","sources":["../src/mods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAUD,sEAAsE;AACtE,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,UAAU,EAAE,CAAC,CAqBvB"}

package/dist/mods.js

@@ -0,0 +1,48 @@
+/**
+ * @pattern-js/runtime-node — mod loading (§13, §16/14).
+ *
+ * Loads "mods" (plugins) and installs them into an engine. A mod is any module
+ * that exports a `PatternMod` (default export, or named `mod`). Three sources,
+ * all the same mechanism:
+ *
+ *  - **1st-party** mods in this monorepo (`@pattern-js/mod-*`) — a bare specifier.
+ *  - **3rd-party** mods published to npm — a bare specifier (an npm dependency).
+ *  - **app-local** mods — a relative path (`./mods/foo.ts`), resolved against a
+ *    base dir (the app root / config location).
+ *
+ * Mods may contribute ops, workflows, auth providers, and hooks; bringing a
+ * frontend app is a future field on `PatternMod`.
+ */
+import { pathToFileURL } from "node:url";
+import { resolve, isAbsolute } from "node:path";
+/** Resolve a mod specifier to something `import()` accepts. */
+function resolveSpecifier(spec, baseDir) {
+    if (spec.startsWith(".") || isAbsolute(spec)) {
+        return pathToFileURL(resolve(baseDir, spec)).href;
+    }
+    return spec; // bare npm/workspace specifier
+}
+/** Dynamically import each specifier and install the exported mod. */
+export async function loadMods(engine, specifiers, opts = {}) {
+    const baseDir = opts.baseDir ?? process.cwd();
+    const loaded = [];
+    for (const spec of specifiers) {
+        const mod = await import(resolveSpecifier(spec, baseDir));
+        const def = mod.default ?? mod.mod;
+        if (!def || !def.name) {
+            throw new Error(`"${spec}" does not export a PatternMod (default export or named "mod")`);
+        }
+        // Await the mod's async `setup` — `start()` must observe installed mods.
+        // `ready` is deferred: it runs once ALL mods are in (see below).
+        await engine.useAsync(def, { deferReady: true });
+        loaded.push(def);
+    }
+    // Second phase: every mod is installed (all ops registered) — now run the
+    // `ready` hooks. This is what lets the admin's control plane bootstrap
+    // stored workflows that use ops from mods listed *after* it in the config.
+    for (const def of loaded) {
+        await def.ready?.(engine);
+    }
+    return loaded;
+}
+//# sourceMappingURL=mods.js.map

package/dist/mods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mods.js","sourceRoot":"","sources":["../src/mods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAQhD,+DAA+D;AAC/D,SAAS,gBAAgB,CAAC,IAAY,EAAE,OAAe;IACrD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,OAAO,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,+BAA+B;AAC9C,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAc,EACd,UAAoB,EACpB,OAAwB,EAAE;IAE1B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1D,MAAM,GAAG,GAA2B,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC;QAC3D,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,gEAAgE,CAAC,CAAC;QAC5F,CAAC;QACD,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,0EAA0E;IAC1E,uEAAuE;IACvE,2EAA2E;IAC3E,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/project.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @pattern-js/runtime-node — project loader.
+ *
+ * A Pattern app is configured declaratively (`pattern.config.json`): which mods
+ * to load and where the workflow JSON files live. `loadProject` builds an engine,
+ * installs the mods (so their ops are available), loads every workflow `.json`
+ * from disk, and returns the engine plus a ready HTTP host.
+ *
+ * This is the seam for the runtime-dynamic future: workflows are data on disk
+ * now, but the same `engine.registerWorkflow` / `updateWorkflow` /
+ * `unregisterWorkflow` calls accept workflows from a DB or an admin API later —
+ * the HTTP host re-derives its routes live on every change.
+ */
+import { Engine, type Workflow } from "@pattern-js/core";
+import { HttpHost } from "./http.js";
+import { WsHost } from "./ws.js";
+export interface PatternConfig {
+    /** Mod specifiers: npm packages and/or app-local paths ("./mods/foo.ts"). */
+    mods?: string[];
+    /** Directory of workflow `.json` files. Default "./workflows". */
+    workflows?: string;
+    /** HTTP host defaults. */
+    http?: {
+        port?: number;
+        host?: string;
+    };
+    /**
+     * Off-loop execution for workflows flagged `offload`. A worker-thread pool
+     * runs those runs so their CPU-heavy compute can't stall the host event loop;
+     * everything else stays inline. `number` = pool size; the object form also
+     * picks which mods each worker loads (default: this project's `mods`). Omit
+     * to keep everything inline — an `offload` flag then degrades to a no-op.
+     *
+     * Exclude heavy / host-only mods from the worker set via the `{ mods }` form
+     * — e.g. drop `@pattern-js/mod-admin` so the admin's control-plane setup doesn't
+     * run in every worker (workers execute domain ops, not the admin).
+     */
+    workers?: number | {
+        size?: number;
+        mods?: string[];
+    };
+    /**
+     * WebSocket upgrades on the HTTP servers. Default true: `boundary.ws.*`
+     * trigger workflows bind declaratively (live, like HTTP routes) and
+     * authenticated clients can subscribe to `core.ws.notify` pushes even with
+     * no WS workflows at all. Set false to refuse upgrades entirely.
+     */
+    ws?: boolean | {
+        path?: string;
+    };
+    /**
+     * Run telemetry persistence. Durable SQLite by default so runs survive
+     * restarts and any process writing the same DB (host, workers, `pattern run`)
+     * shows up in the admin. `persist: false` keeps it in-memory (ephemeral);
+     * `path` overrides the default `<project>/.pattern/traces.db`. Degrades to
+     * in-memory automatically when `node:sqlite` is unavailable.
+     */
+    trace?: {
+        persist?: boolean;
+        path?: string;
+        capacity?: number;
+    };
+}
+/** Identity helper for authoring `pattern.config.ts` with type-checking. */
+export declare function defineConfig(config: PatternConfig): PatternConfig;
+export interface LoadedProject {
+    engine: Engine;
+    http: HttpHost;
+    /** The auto-wired WS host (absent when `config.ws === false`). */
+    ws?: WsHost;
+    config: PatternConfig;
+    /** Start the HTTP host (opens a server per declared port). */
+    start: () => Promise<{
+        ports: number[];
+        close: () => Promise<void>;
+    }>;
+}
+/**
+ * Load `.env` from the project dir into process.env (already-set variables
+ * win — the real environment outranks the file, dotenv-style). Hand-rolled
+ * on purpose: KEY=VALUE lines, # comments, optional single/double quotes.
+ * This is where PATTERN_VAULT_KEY / OPENAI_API_KEY live in dev.
+ */
+export declare function loadDotEnv(baseDir: string, file?: string): void;
+/** Read & parse every `*.json` workflow in a directory. */
+export declare function loadWorkflowDir(dir: string): Promise<Workflow[]>;
+/**
+ * Build a project from a `PatternConfig` (or a path to `pattern.config.json`).
+ * Mods load first (they register ops), then workflows are registered.
+ */
+export declare function loadProject(configOrPath?: PatternConfig | string, opts?: {
+    engine?: Engine;
+}): Promise<LoadedProject>;
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,MAAM,EAAgC,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGvF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtD;;;;;OAKG;IACH,EAAE,CAAC,EAAE,OAAO,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAEjE;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,kEAAkE;IAClE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,CAAC;IACtB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,IAAI,CAoB/D;AAED,2DAA2D;AAC3D,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CActE;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,YAAY,GAAE,aAAa,GAAG,MAA8B,EAC5D,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAAC,aAAa,CAAC,CA8FxB"}

package/dist/project.js

@@ -0,0 +1,168 @@
+/**
+ * @pattern-js/runtime-node — project loader.
+ *
+ * A Pattern app is configured declaratively (`pattern.config.json`): which mods
+ * to load and where the workflow JSON files live. `loadProject` builds an engine,
+ * installs the mods (so their ops are available), loads every workflow `.json`
+ * from disk, and returns the engine plus a ready HTTP host.
+ *
+ * This is the seam for the runtime-dynamic future: workflows are data on disk
+ * now, but the same `engine.registerWorkflow` / `updateWorkflow` /
+ * `unregisterWorkflow` calls accept workflows from a DB or an admin API later —
+ * the HTTP host re-derives its routes live on every change.
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { Engine, TRACE_STORE } from "@pattern-js/core";
+import { loadMods } from "./mods.js";
+import { createTraceStore } from "./trace/index.js";
+import { HttpHost } from "./http.js";
+import { WsHost } from "./ws.js";
+import { NodeConnectionRegistry } from "./ws-registry.js";
+import { WorkerPoolTransport } from "./worker-pool.js";
+/** Identity helper for authoring `pattern.config.ts` with type-checking. */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Load `.env` from the project dir into process.env (already-set variables
+ * win — the real environment outranks the file, dotenv-style). Hand-rolled
+ * on purpose: KEY=VALUE lines, # comments, optional single/double quotes.
+ * This is where PATTERN_VAULT_KEY / OPENAI_API_KEY live in dev.
+ */
+export function loadDotEnv(baseDir, file = ".env") {
+    const path = resolve(baseDir, file);
+    if (!existsSync(path))
+        return;
+    const text = readFileSync(path, "utf8");
+    for (const rawLine of text.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (process.env[key] === undefined)
+            process.env[key] = value;
+    }
+}
+/** Read & parse every `*.json` workflow in a directory. */
+export async function loadWorkflowDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    const workflows = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const text = await readFile(join(dir, entry.name), "utf8");
+        try {
+            workflows.push(JSON.parse(text));
+        }
+        catch (err) {
+            throw new Error(`failed to parse workflow ${entry.name}: ${err.message}`);
+        }
+    }
+    return workflows;
+}
+/**
+ * Build a project from a `PatternConfig` (or a path to `pattern.config.json`).
+ * Mods load first (they register ops), then workflows are registered.
+ */
+export async function loadProject(configOrPath = "pattern.config.json", opts = {}) {
+    let config;
+    let baseDir;
+    if (typeof configOrPath === "string") {
+        const configPath = resolve(process.cwd(), configOrPath);
+        baseDir = dirname(configPath);
+        config = existsSync(configPath) ? JSON.parse(await readFile(configPath, "utf8")) : {};
+    }
+    else {
+        config = configOrPath;
+        baseDir = process.cwd();
+    }
+    // `.env` first (existing env wins), so mods' setup — the vault reading
+    // PATTERN_VAULT_KEY, agents reading OPENAI_API_KEY — and `$env` config
+    // interpolation all see it, whatever entry point launched us.
+    loadDotEnv(baseDir);
+    // Off-loop pool for `offload`-flagged workflows (opt-in via `workers`). Built
+    // here so it can be handed to the engine as `offloadTransport`; when the
+    // caller brought their own engine, they own its transports (so we skip it).
+    let offloadPool;
+    let traceStore;
+    // Inject process.env so workflow config can use `$env` / `${VAR}` references.
+    // The node connection registry up-front means `core.ws.*` ops (notify,
+    // broadcast…) reach the same sockets the WS host accepts.
+    const engine = opts.engine ?? new Engine({ env: process.env, connections: new NodeConnectionRegistry() });
+    if (!opts.engine && config.workers !== undefined) {
+        const w = typeof config.workers === "number" ? { size: config.workers } : config.workers;
+        // Forward each worker's trace into this engine's sink so offloaded runs land
+        // in the admin's Runs view (and the rest of the trace surfaces) like inline
+        // ones, tagged with which worker ran them.
+        offloadPool = new WorkerPoolTransport({
+            size: w.size,
+            mods: w.mods ?? config.mods,
+            onTrace: (evt) => engine.ingestTrace(evt),
+        });
+        engine.setOffloadTransport(offloadPool);
+    }
+    // Durable run telemetry. Created here (before the mods' setup) and provided as
+    // a service so the admin reads it instead of spinning up its own in-memory
+    // store — runs persist across restarts and any process writing the same DB
+    // shows up. Off only when the caller brought their own engine (they own it).
+    if (!opts.engine && config.trace?.persist !== false) {
+        traceStore = await createTraceStore({
+            kind: "sqlite",
+            path: config.trace?.path ?? resolve(baseDir, ".pattern/traces.db"),
+            capacity: config.trace?.capacity,
+        });
+        engine.onTrace(traceStore);
+        engine.provideService(TRACE_STORE, traceStore);
+    }
+    if (config.mods?.length) {
+        await loadMods(engine, config.mods, { baseDir });
+    }
+    const wfDir = resolve(baseDir, config.workflows ?? "workflows");
+    for (const wf of await loadWorkflowDir(wfDir)) {
+        // Async: runs the resolve phase for any boundary config ports (e.g. a route
+        // port fed by core.env). Plain `$env` config still works synchronously.
+        await engine.registerWorkflowAsync(wf);
+    }
+    const http = new HttpHost(engine, { defaultPort: config.http?.port, host: config.http?.host });
+    // WS rides the same servers (auto mode: boundary.ws.* workflows bind live;
+    // bare connections still serve as the notification channel). One WsHost
+    // attaches to every port the route reconciler opens, now or later.
+    let ws;
+    if (config.ws !== false) {
+        ws = new WsHost(engine, typeof config.ws === "object" ? { path: config.ws.path } : {});
+        const attached = new Set();
+        http.onServer((server) => {
+            if (attached.has(server))
+                return;
+            attached.add(server);
+            ws.attach(server);
+        });
+    }
+    return {
+        engine,
+        http,
+        ws,
+        config,
+        start: async () => {
+            const { ports, close } = await http.start();
+            // The returned close tears down the worker pool too (idempotent with
+            // engine.close(), which also owns it). No pool → a no-op.
+            return { ports, close: async () => void (await close(), await offloadPool?.close(), await traceStore?.close()) };
+        },
+    };
+}
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAkC,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAsCvD,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,IAAI,GAAG,MAAM;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,EAAE,IAAI,CAAC;YAAE,SAAS;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,SAAS;QACpD,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,IACE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC9C,CAAC;YACD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC/C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QAC/D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAa,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,CAAC,IAAI,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,eAAuC,qBAAqB,EAC5D,OAA4B,EAAE;IAE9B,IAAI,MAAqB,CAAC;IAC1B,IAAI,OAAe,CAAC;IACpB,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;QACxD,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QAC9B,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3G,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,YAAY,CAAC;QACtB,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,CAAC;IAED,uEAAuE;IACvE,uEAAuE;IACvE,8DAA8D;IAC9D,UAAU,CAAC,OAAO,CAAC,CAAC;IAEpB,8EAA8E;IAC9E,yEAAyE;IACzE,4EAA4E;IAC5E,IAAI,WAA4C,CAAC;IACjD,IAAI,UAAkC,CAAC;IAEvC,8EAA8E;IAC9E,uEAAuE;IACvE,0DAA0D;IAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,sBAAsB,EAAE,EAAE,CAAC,CAAC;IAE1G,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACzF,6EAA6E;QAC7E,4EAA4E;QAC5E,2CAA2C;QAC3C,WAAW,GAAG,IAAI,mBAAmB,CAAC;YACpC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI;YAC3B,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC;SAC1C,CAAC,CAAC;QACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC1C,CAAC;IAED,+EAA+E;IAC/E,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;QACpD,UAAU,GAAG,MAAM,gBAAgB,CAAC;YAClC,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,oBAAoB,CAAC;YAClE,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ;SACjC,CAAC,CAAC;QACH,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC3B,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QACxB,MAAM,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,IAAI,WAAW,CAAC,CAAC;IAChE,KAAK,MAAM,EAAE,IAAI,MAAM,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,4EAA4E;QAC5E,wEAAwE;QACxE,MAAM,MAAM,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/F,2EAA2E;IAC3E,wEAAwE;IACxE,mEAAmE;IACnE,IAAI,EAAsB,CAAC;IAC3B,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACxB,EAAE,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAW,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE;YACvB,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO;YACjC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACrB,EAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,MAAM;QACN,IAAI;QACJ,EAAE;QACF,MAAM;QACN,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5C,qEAAqE;YACrE,0DAA0D;YAC1D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,MAAM,WAAW,EAAE,KAAK,EAAE,EAAE,MAAM,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACnH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/schedule.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @pattern-js/runtime-node — schedule host (§7, §12).
+ *
+ * Fires `boundary.schedule` triggers on an interval or a 5-field cron. Results
+ * are discarded or traced. Cron is evaluated once per minute against the local
+ * clock (no external dependency).
+ */
+import type { Engine, Workflow } from "@pattern-js/core";
+/** Parse "m h dom mon dow" into per-field matchers. `*`, ranges, lists, steps. */
+declare function cronMatcher(expr: string): (d: Date) => boolean;
+export declare class ScheduleHost {
+    private readonly engine;
+    /** Timers keyed by workflow id, so a redeploy/remove reconciles cleanly. */
+    private timers;
+    private unsubscribe?;
+    constructor(engine: Engine);
+    /**
+     * Schedule every `boundary.schedule` trigger. With no argument it watches the
+     * engine and **reacts to workflow changes at runtime** — a workflow deployed,
+     * updated, or removed (e.g. from an admin) re-reconciles its timers live.
+     * Passing an explicit list disables the live watch (one-shot scheduling).
+     */
+    start(workflows?: Workflow[]): this;
+    private scheduleWorkflow;
+    private clearWorkflow;
+    private fire;
+    private everyInterval;
+    private everyCron;
+    stop(): void;
+}
+export declare function createScheduleHost(engine: Engine): ScheduleHost;
+export { cronMatcher };
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAMzD,kFAAkF;AAClF,iBAAS,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,KAAK,OAAO,CAiBvD;AAoBD,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,4EAA4E;IAC5E,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,WAAW,CAAC,CAAa;gBAEJ,MAAM,EAAE,MAAM;IAE3C;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI;IAanC,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,SAAS;IAgBjB,IAAI,IAAI,IAAI;CAMb;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAE/D;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}