@pattern-js/runtime-node 0.4.0-main.f8ef342 → 0.5.0-main.79cf721

package/dist/durable/sqlite.js

@@ -0,0 +1,207 @@
+/**
+ * @pattern-js/runtime-node — the durable RunLedger on Node's `node:sqlite`.
+ *
+ * Full-fidelity run records (exact trigger input, exact node outputs) for
+ * `durable: true` workflows — the substrate resume and re-run replay from.
+ * Hand-written SQL like the trace store: WAL for multi-process access,
+ * busy_timeout so a dev-server restart waits for the lock. Lives in
+ * `.pattern-data/ledger.db` (gitignored beside the identity + document stores)
+ * because, unlike the masked trace store, it records REAL values.
+ *
+ * Rows stuck `running` after a crash become `error: "interrupted"` — a
+ * resumable record instead of a stuck one. Which rows are stuck is decided by
+ * process LIVENESS (owner heartbeats, see ./liveness.ts), never by run age: a
+ * young run of a dead process is swept, a long run of a live sibling is not.
+ */
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { Liveness } from "./liveness.js";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS ledger_runs (
+  run_id        TEXT PRIMARY KEY,
+  workflow_id   TEXT NOT NULL,
+  workflow_hash TEXT NOT NULL,
+  trigger_node  TEXT NOT NULL,
+  input         TEXT NOT NULL,
+  params        TEXT,
+  principal     TEXT NOT NULL,
+  parent_run_id TEXT,
+  resumed_from  TEXT,
+  root_run_id   TEXT,
+  owner         TEXT,
+  status        TEXT NOT NULL,
+  error         TEXT,
+  started_at    REAL NOT NULL,
+  ended_at      REAL
+);
+CREATE INDEX IF NOT EXISTS idx_ledger_runs_wf ON ledger_runs(workflow_id, started_at);
+CREATE TABLE IF NOT EXISTS ledger_nodes (
+  run_id     TEXT NOT NULL,
+  node_id    TEXT NOT NULL,
+  status     TEXT NOT NULL,
+  outputs    TEXT,
+  pulsed     TEXT,
+  streaming  INTEGER NOT NULL DEFAULT 0,
+  unserializable INTEGER NOT NULL DEFAULT 0,
+  error      TEXT,
+  started_at REAL,
+  ended_at   REAL,
+  PRIMARY KEY (run_id, node_id)
+);
+`;
+/**
+ * Additive schema evolution: columns that joined after 0.5.0's first cut. A
+ * fresh file gets them from SCHEMA; an existing one grows them here. Pre-1.0
+ * the ledger only ever ADDS columns, so a bare "is it there yet" suffices.
+ */
+const COLUMNS = [
+    ["ledger_runs", "root_run_id", "TEXT"],
+    ["ledger_runs", "owner", "TEXT"],
+    ["ledger_nodes", "error", "TEXT"],
+];
+function ensureColumns(db) {
+    ensureColumnsFor(db, COLUMNS);
+}
+export class SqliteRunLedger {
+    db;
+    opts;
+    liveness;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.opts = opts;
+        // Register as an owner and heartbeat; every beat also sweeps, so a crash
+        // shortly before this boot is caught within one stale window.
+        this.liveness = new Liveness(db, opts, () => this.sweep()).start();
+        this.sweep();
+        this.prune();
+    }
+    /**
+     * Convert runs stuck `running` under a DEAD owner into terminal, RESUMABLE
+     * records. Ownership, not age: a live sibling's long run is untouched; a
+     * young run whose process died is swept. Legacy owner-less rows use the
+     * one-minute age rule they were written under.
+     */
+    sweep() {
+        const { sql, params } = this.liveness.orphaned("owner", "started_at");
+        const res = this.db
+            .prepare(`UPDATE ledger_runs SET status = 'error', error = ?, ended_at = ? WHERE status = 'running' AND ${sql}`)
+            .run(JSON.stringify({ message: "interrupted (process exited mid-run)" }), Date.now(), ...params);
+        return Number(res.changes);
+    }
+    begin(h) {
+        this.db
+            .prepare(`INSERT OR REPLACE INTO ledger_runs
+         (run_id, workflow_id, workflow_hash, trigger_node, input, params, principal,
+          parent_run_id, resumed_from, root_run_id, owner, status, error, started_at, ended_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, NULL)`)
+            .run(h.runId, h.workflowId, h.workflowHash, h.triggerNodeId, JSON.stringify(h.input), h.params ? JSON.stringify(h.params) : null, JSON.stringify(h.principal), h.parentRunId ?? null, h.resumedFrom ?? null, h.rootRunId ?? null, this.liveness.ownerId, h.status, h.startedAt);
+    }
+    nodeStarted(runId, nodeId, at) {
+        this.db
+            .prepare("INSERT OR IGNORE INTO ledger_nodes (run_id, node_id, status, started_at) VALUES (?, ?, 'started', ?)")
+            .run(runId, nodeId, at);
+    }
+    nodeFinished(r) {
+        this.db
+            .prepare(`INSERT INTO ledger_nodes (run_id, node_id, status, outputs, pulsed, streaming, unserializable, error, started_at, ended_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (run_id, node_id) DO UPDATE SET
+           status = excluded.status, outputs = excluded.outputs, pulsed = excluded.pulsed,
+           streaming = excluded.streaming, unserializable = excluded.unserializable,
+           error = excluded.error, ended_at = excluded.ended_at`)
+            .run(r.runId, r.nodeId, r.status, r.outputs ? JSON.stringify(r.outputs) : null, r.pulsed ? JSON.stringify(r.pulsed) : null, r.streaming ? 1 : 0, r.unserializable ? 1 : 0, r.error ? JSON.stringify(r.error) : null, r.startedAt ?? null, r.endedAt ?? null);
+    }
+    end(runId, status, error) {
+        this.db
+            .prepare("UPDATE ledger_runs SET status = ?, error = ?, ended_at = ? WHERE run_id = ?")
+            .run(status, error ? JSON.stringify(error) : null, Date.now(), runId);
+        if (status !== "running")
+            this.prune();
+    }
+    async get(runId) {
+        const row = this.db.prepare("SELECT * FROM ledger_runs WHERE run_id = ?").get(runId);
+        if (!row)
+            return null;
+        const nodes = this.db.prepare("SELECT * FROM ledger_nodes WHERE run_id = ?").all(runId).map((n) => ({
+            runId,
+            nodeId: String(n.node_id),
+            status: String(n.status),
+            outputs: n.outputs ? JSON.parse(String(n.outputs)) : undefined,
+            pulsed: n.pulsed ? JSON.parse(String(n.pulsed)) : undefined,
+            streaming: Number(n.streaming) === 1 ? true : undefined,
+            unserializable: Number(n.unserializable) === 1 ? true : undefined,
+            error: n.error ? JSON.parse(String(n.error)) : undefined,
+            startedAt: n.started_at == null ? undefined : Number(n.started_at),
+            endedAt: n.ended_at == null ? undefined : Number(n.ended_at),
+        }));
+        return {
+            header: {
+                runId: String(row.run_id),
+                workflowId: String(row.workflow_id),
+                workflowHash: String(row.workflow_hash),
+                triggerNodeId: String(row.trigger_node),
+                input: JSON.parse(String(row.input)),
+                params: row.params ? JSON.parse(String(row.params)) : undefined,
+                principal: JSON.parse(String(row.principal)),
+                parentRunId: row.parent_run_id == null ? undefined : String(row.parent_run_id),
+                resumedFrom: row.resumed_from == null ? undefined : String(row.resumed_from),
+                rootRunId: row.root_run_id == null ? undefined : String(row.root_run_id),
+                status: String(row.status),
+                error: row.error ? JSON.parse(String(row.error)) : undefined,
+                startedAt: Number(row.started_at),
+                endedAt: row.ended_at == null ? undefined : Number(row.ended_at),
+            },
+            nodes,
+        };
+    }
+    prune(opts) {
+        const keep = opts?.keep ?? this.opts.keep ?? 200;
+        const excess = this.db
+            .prepare(`SELECT run_id FROM ledger_runs WHERE status != 'running'
+         ORDER BY started_at DESC LIMIT -1 OFFSET ?`)
+            .all(keep);
+        for (const r of excess) {
+            this.db.prepare("DELETE FROM ledger_nodes WHERE run_id = ?").run(r.run_id);
+            this.db.prepare("DELETE FROM ledger_runs WHERE run_id = ?").run(r.run_id);
+        }
+        return excess.length;
+    }
+    close() {
+        this.liveness.close();
+        this.db.close();
+    }
+}
+/** Open (creating if needed) the sqlite-backed RunLedger at `path`. */
+export function createRunLedger(path, opts = {}) {
+    let DatabaseSync;
+    try {
+        const mod = process.getBuiltinModule?.("node:sqlite");
+        DatabaseSync = mod?.DatabaseSync;
+    }
+    catch {
+        /* fall through */
+    }
+    if (!DatabaseSync) {
+        throw new Error("node:sqlite is not available in this Node build — the RunLedger needs Node ≥22.5 (≥24 recommended).");
+    }
+    if (path !== ":memory:")
+        mkdirSync(dirname(path), { recursive: true });
+    const db = new DatabaseSync(path);
+    // busy_timeout before the WAL switch — the switch takes locks, and a dev
+    // restart overlaps the old process's checkpoint-on-close.
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(SCHEMA);
+    ensureColumns(db);
+    return new SqliteRunLedger(db, opts);
+}
+export { ensureColumnsFor };
+/** Shared additive-migration helper (the trace store grows its `owner` column the same way). */
+function ensureColumnsFor(db, columns) {
+    for (const [table, column, ddl] of columns) {
+        const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+        if (!cols.some((c) => c.name === column))
+            db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${ddl}`);
+    }
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/durable/sqlite.js.map

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

package/dist/http.d.ts

@@ -10,8 +10,8 @@
  *
  * Response modes: `buffered`, `sse` (Server-Sent Events), `chunked`.
  */
-import { type Server } from "node:http";
-import { type Engine } from "@pattern-js/core";
+import { type IncomingMessage, type Server } from "node:http";
+import { RateLimiter, type Engine } from "@pattern-js/core";
 export interface HttpHostOptions {
     /**
      * Default port for routes that don't declare their own `port`. If omitted,
@@ -25,7 +25,19 @@ export interface HttpHostOptions {
      * Routes with `bodyMode: "stream"` are exempt — they never buffer.
      */
     maxBodyBytes?: number;
+    /**
+     * How many reverse proxies in front of this host append to X-Forwarded-For.
+     * 0 (default) trusts no header: the client IP is the socket peer. Behind one
+     * load balancer, 1: the IP is the entry that proxy appended (the rightmost),
+     * which a client cannot forge. Defaults to the PATTERN_TRUST_PROXY env var.
+     */
+    trustProxy?: number;
 }
+/**
+ * The client's address. Only the last `trustProxy` X-Forwarded-For hops are
+ * believed: anything to their left was written by the client and is forgeable.
+ */
+export declare function clientIp(req: IncomingMessage, trustProxy: number): string;
 export declare class HttpHost {
     private readonly engine;
     private readonly opts;
@@ -39,6 +51,25 @@ export declare class HttpHost {
     private readonly defaultPort;
     private readonly serverListeners;
     constructor(engine: Engine, opts?: HttpHostOptions);
+    /** Forwarded hops believed when resolving the client IP (see HttpHostOptions.trustProxy). */
+    private readonly trustProxy;
+    /** Per-route request budgets (`rateLimit` on boundary.http.request). */
+    readonly rateLimiter: RateLimiter;
+    /**
+     * Refuse a request the route's `requireAuth` doesn't admit (§9):
+     * - anonymous → 401; a browser GET asking for HTML is bounced to the
+     *   advertised login page (identity registers AUTH_LOGIN_URL) with `next`;
+     * - signed in but missing a scope → 403, so a client can tell "sign in"
+     *   from "upgrade".
+     * The body is a line of text when the client asks for HTML, else JSON
+     * (`{ error, reason }`), the same rule as the 429 answer.
+     */
+    private deny;
+    /**
+     * Count one request against the route's budget; past it, answer 429 with
+     * Retry-After and report true so the caller stops before the run.
+     */
+    private limited;
     /** Derive routes from registered workflows, open servers, and watch for changes. */
     start(): Promise<{
         ports: number[];
@@ -46,9 +77,11 @@ export declare class HttpHost {
     }>;
     /**
      * Loud, honest signal: with NO auth provider installed, any route that
-     * *declares* `requireAuth` can't be enforced (nobody can authenticate) — the
-     * engine serves it open (advisory). Say so plainly at boot so it's never a
-     * silent surprise. Add a provider and the same declarations are enforced.
+     * *declares* `requireAuth` can't be enforced (nobody can authenticate). By
+     * default the engine DENIES those requests (the refusal names the fix); with
+     * the explicit `auth.unenforced: "open"` opt-in it serves them open. Say
+     * which at boot so neither is a silent surprise. Add a provider and the same
+     * declarations are enforced.
      */
     private warnIfUnenforceableAuth;
     /** Tail of the rebuild queue — see `rebuild()`. */

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAIjG,OAAO,EAKL,KAAK,MAAM,EAMZ,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+KD,qBAAa,QAAQ;IAYjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZvB,OAAO,CAAC,OAAO,CAA6B;IAC5C;iFAC6E;IAC7E,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqD;gBAGlE,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB;IAQ7C,oFAAoF;IAC9E,KAAK,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IASvE;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAY/B,mDAAmD;IACnD,OAAO,CAAC,UAAU,CAAoC;IAEtD;;;;;OAKG;IACH,OAAO,CAAC,OAAO;YAOD,UAAU;IAexB,gEAAgE;IAChE,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,UAAU;IAgClB;;;;;;OAMG;YACW,QAAQ;IAuCtB,qEAAqE;IACrE,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAoClB,2EAA2E;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAMhE,OAAO,CAAC,KAAK;YAaC,MAAM;IAyIpB,+EAA+E;YACjE,QAAQ;IAgFtB,OAAO,CAAC,SAAS;IAYX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B;AAsLD,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,QAAQ,CAE/E"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAIjG,OAAO,EAGL,WAAW,EAKX,KAAK,MAAM,EAMZ,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUzE;AAiLD,qBAAa,QAAQ;IAYjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZvB,OAAO,CAAC,OAAO,CAA6B;IAC5C;iFAC6E;IAC7E,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqD;gBAGlE,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB;IAU7C,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,cAAqB;IAEzC;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI;IAsBZ;;;OAGG;IACH,OAAO,CAAC,OAAO;IAkBf,oFAAoF;IAC9E,KAAK,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IASvE;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAsB/B,mDAAmD;IACnD,OAAO,CAAC,UAAU,CAAoC;IAEtD;;;;;OAKG;IACH,OAAO,CAAC,OAAO;YAOD,UAAU;IAexB,gEAAgE;IAChE,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,UAAU;IAmClB;;;;;;OAMG;YACW,QAAQ;IAuCtB,qEAAqE;IACrE,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAoClB,2EAA2E;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAMhE,OAAO,CAAC,KAAK;YAaC,MAAM;IA+IpB,+EAA+E;YACjE,QAAQ;IAmEtB,OAAO,CAAC,SAAS;IAYX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B;AAiMD,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,QAAQ,CAE/E"}

package/dist/http.js

@@ -14,8 +14,24 @@ import { Buffer } from "node:buffer";
 import { createServer } from "node:http";
 import { extname } from "node:path";
 import { Readable } from "node:stream";
-import { ANONYMOUS, AUTH_LOGIN_URL, jsonSchemaToZod, principalToUser, } from "@pattern-js/core";
+import { ANONYMOUS, AUTH_LOGIN_URL, RateLimiter, RunCanceled, jsonSchemaToZod, parseDurationMs, principalToUser, } from "@pattern-js/core";
 import { filesystems } from "./filesystem.js";
+/**
+ * The client's address. Only the last `trustProxy` X-Forwarded-For hops are
+ * believed: anything to their left was written by the client and is forgeable.
+ */
+export function clientIp(req, trustProxy) {
+    const peer = (req.socket?.remoteAddress ?? "").replace(/^::ffff:/, "") || "unknown";
+    if (trustProxy <= 0)
+        return peer;
+    const raw = req.headers["x-forwarded-for"];
+    const hops = (Array.isArray(raw) ? raw.join(",") : (raw ?? ""))
+        .split(",")
+        .map((h) => h.trim())
+        .filter(Boolean);
+    const ip = hops[hops.length - trustProxy];
+    return ip ? ip.replace(/^::ffff:/, "") : peer;
+}
 const DEFAULT_MAX_BODY = 10 * 1024 * 1024;
 /** Thrown by `readBody` when a buffered body exceeds the configured cap. */
 class BodyTooLargeError extends Error {
@@ -161,6 +177,62 @@ export class HttpHost {
         // Default = explicit `defaultPort` (e.g. from pattern.config.json http.port),
         // else the PORT env var, else 3000.
         this.defaultPort = opts.defaultPort ?? envPort() ?? 3000;
+        const envTrust = Number(process.env.PATTERN_TRUST_PROXY);
+        this.trustProxy = opts.trustProxy ?? (Number.isInteger(envTrust) && envTrust > 0 ? envTrust : 0);
+    }
+    /** Forwarded hops believed when resolving the client IP (see HttpHostOptions.trustProxy). */
+    trustProxy;
+    /** Per-route request budgets (`rateLimit` on boundary.http.request). */
+    rateLimiter = new RateLimiter();
+    /**
+     * Refuse a request the route's `requireAuth` doesn't admit (§9):
+     * - anonymous → 401; a browser GET asking for HTML is bounced to the
+     *   advertised login page (identity registers AUTH_LOGIN_URL) with `next`;
+     * - signed in but missing a scope → 403, so a client can tell "sign in"
+     *   from "upgrade".
+     * The body is a line of text when the client asks for HTML, else JSON
+     * (`{ error, reason }`), the same rule as the 429 answer.
+     */
+    deny(req, res, principal, reason, mayRedirect) {
+        const accept = String(req.headers["accept"] ?? "");
+        const anonymous = principal.kind === "anonymous";
+        if (anonymous && mayRedirect && accept.includes("text/html")) {
+            const loginUrl = this.engine.service(AUTH_LOGIN_URL);
+            if (loginUrl) {
+                res.writeHead(302, { location: `${loginUrl}?next=${encodeURIComponent(req.url ?? "/")}` }).end();
+                return;
+            }
+        }
+        const status = anonymous ? 401 : 403;
+        if (accept.includes("text/html")) {
+            res
+                .writeHead(status, { "content-type": "text/plain; charset=utf-8" })
+                .end(`${anonymous ? "Unauthorized" : "Forbidden"}: ${reason}`);
+            return;
+        }
+        res
+            .writeHead(status, { "content-type": "application/json" })
+            .end(JSON.stringify({ error: anonymous ? "unauthorized" : "forbidden", reason }));
+    }
+    /**
+     * Count one request against the route's budget; past it, answer 429 with
+     * Retry-After and report true so the caller stops before the run.
+     */
+    limited(res, route, client, req) {
+        const rule = route.rateLimit;
+        const v = this.rateLimiter.hit(`${route.workflowId}:${route.trigger}:${client}`, rule);
+        if (v.ok)
+            return false;
+        const retryAfter = Math.max(1, Math.ceil(v.retryAfterMs / 1000));
+        const html = String(req.headers.accept ?? "").includes("text/html");
+        res.writeHead(429, {
+            "content-type": html ? "text/plain; charset=utf-8" : "application/json",
+            "retry-after": String(retryAfter),
+        });
+        res.end(html
+            ? `Too many requests. Try again in ${retryAfter} seconds.`
+            : JSON.stringify({ error: "rate_limited", retryAfter }));
+        return true;
     }
     /** Derive routes from registered workflows, open servers, and watch for changes. */
     async start() {
@@ -173,20 +245,30 @@ export class HttpHost {
     }
     /**
      * Loud, honest signal: with NO auth provider installed, any route that
-     * *declares* `requireAuth` can't be enforced (nobody can authenticate) — the
-     * engine serves it open (advisory). Say so plainly at boot so it's never a
-     * silent surprise. Add a provider and the same declarations are enforced.
+     * *declares* `requireAuth` can't be enforced (nobody can authenticate). By
+     * default the engine DENIES those requests (the refusal names the fix); with
+     * the explicit `auth.unenforced: "open"` opt-in it serves them open. Say
+     * which at boot so neither is a silent surprise. Add a provider and the same
+     * declarations are enforced.
      */
     warnIfUnenforceableAuth() {
-        if (this.engine.hasAuthProvider())
+        const posture = this.engine.authPosture();
+        if (posture === "enforced")
             return;
         const gated = [...this.routes, ...this.apps].filter((r) => r.requireAuth).length;
         if (!gated)
             return;
+        if (posture === "open") {
+            console.warn(`\n[pattern] ⚠ ${gated} route(s) declare requireAuth but NO auth provider is installed —\n` +
+                `[pattern]   auth.unenforced is "open", so they serve UNAUTHENTICATED (anyone who can reach\n` +
+                `[pattern]   the port has access). Add an auth provider (e.g. @pattern-js/mod-identity) to\n` +
+                `[pattern]   enforce them. Routes without requireAuth are unaffected.\n`);
+            return;
+        }
         console.warn(`\n[pattern] ⚠ ${gated} route(s) declare requireAuth but NO auth provider is installed —\n` +
-            `[pattern]   they are NOT enforced and serve UNAUTHENTICATED (anyone who can reach the\n` +
-            `[pattern]   port has access). Add an auth provider (e.g. @pattern-js/mod-identity) to enforce\n` +
-            `[pattern]   them. Routes without requireAuth are unaffected.\n`);
+            `[pattern]   they REFUSE every request (401) until you add one (e.g. @pattern-js/mod-identity).\n` +
+            `[pattern]   For local work without sign-in, set "auth": { "unenforced": "open" } in\n` +
+            `[pattern]   pattern.config.json. Routes without requireAuth are unaffected.\n`);
     }
     /** Tail of the rebuild queue — see `rebuild()`. */
     rebuilding = Promise.resolve();
@@ -254,6 +336,9 @@ export class HttpHost {
                     paramsSchema: cfg.params ? jsonSchemaToZod(cfg.params, { coerce: true }) : undefined,
                     requireAuth: cfg.requireAuth,
                     cancelOnDisconnect: Boolean(cfg.cancelOnDisconnect),
+                    rateLimit: cfg.rateLimit
+                        ? { max: cfg.rateLimit.max, windowMs: parseDurationMs(cfg.rateLimit.window ?? "1m"), by: cfg.rateLimit.by ?? "ip" }
+                        : undefined,
                 });
             }
         }
@@ -410,6 +495,10 @@ export class HttpHost {
             res.writeHead(500).end("workflow not registered");
             return;
         }
+        // ── Rate limit (by IP: before any auth or body work is spent) ──
+        const ip = clientIp(req, this.trustProxy);
+        if (route.rateLimit?.by === "ip" && this.limited(res, route, `ip:${ip}`, req))
+            return;
         // ── Auth (§9) ──
         const headers = new Headers();
         for (const [k, v] of Object.entries(req.headers)) {
@@ -420,9 +509,12 @@ export class HttpHost {
         }
         const principal = await this.engine.authenticate({ headers, raw: req });
         const auth = this.engine.authorize(principal, route.requireAuth);
-        if (!auth.ok) {
-            res.writeHead(401, { "content-type": "text/plain" }).end(`Unauthorized: ${auth.reason}`);
-            return;
+        if (!auth.ok)
+            return this.deny(req, res, principal, auth.reason, method === "GET");
+        if (route.rateLimit?.by === "user") {
+            const who = principal.kind === "user" ? `user:${principal.id}` : `ip:${ip}`;
+            if (this.limited(res, route, who, req))
+                return;
         }
         // ── Validate params, query & body against the declared JSON Schemas (§7) ──
         const headersObj = {};
@@ -469,6 +561,7 @@ export class HttpHost {
             path: url.pathname,
             headers: headersObj,
             cookies: parseCookies(headersObj.cookie),
+            ip,
             query,
             params: routeParams,
             body,
@@ -490,7 +583,7 @@ export class HttpHost {
         if (route.cancelOnDisconnect) {
             res.on("close", () => {
                 if (!delivered)
-                    ac.abort(new Error("client disconnected"));
+                    ac.abort(new RunCanceled("client disconnected"));
             });
         }
         let result;
@@ -503,7 +596,7 @@ export class HttpHost {
         }
         if (result.status === "error") {
             delivered = true;
-            return writeError(res, result.error);
+            return writeError(res, result.error, result.runId);
         }
         const payload = firstOutgate(result, workflow, "boundary.http.response");
         if (!payload) {
@@ -534,20 +627,8 @@ export class HttpHost {
             }
             const principal = await this.engine.authenticate({ headers, raw: req });
             const auth = this.engine.authorize(principal, app.requireAuth);
-            if (!auth.ok) {
-                // A browser asking for HTML gets bounced to the advertised login page
-                // (§9) — the identity mod registers AUTH_LOGIN_URL; fetch/XHR callers
-                // still get the bare 401 and handle it client-side.
-                const loginUrl = this.engine.service(AUTH_LOGIN_URL);
-                const accept = String(req.headers["accept"] ?? "");
-                if (loginUrl && accept.includes("text/html")) {
-                    const next = encodeURIComponent(req.url ?? "/");
-                    res.writeHead(302, { location: `${loginUrl}?next=${next}` }).end();
-                    return;
-                }
-                res.writeHead(401, { "content-type": "text/plain" }).end(`Unauthorized: ${auth.reason}`);
-                return;
-            }
+            if (!auth.ok)
+                return this.deny(req, res, principal, auth.reason, true);
         }
         const fs = filesystems(this.engine).get(app.filesystem);
         if (!fs) {
@@ -779,11 +860,18 @@ async function* streamIter(stream) {
         reader.releaseLock();
     }
 }
-function writeError(res, err) {
+/**
+ * A failed run's HTTP answer. In development the error message helps; in
+ * production (NODE_ENV=production) it can carry internals (config names,
+ * account ids, paths) to an unauthenticated caller, so the client gets a
+ * generic error and the run id, and the operator reads the rest in the trace.
+ */
+function writeError(res, err, runId) {
     const message = err instanceof Error ? err.message : String(err);
+    const production = process.env.NODE_ENV === "production";
     if (!res.headersSent)
         res.writeHead(500, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: message }));
+    res.end(JSON.stringify(production ? { error: "internal_error", ...(runId ? { runId } : {}) } : { error: message, ...(runId ? { runId } : {}) }));
 }
 function firstOutgate(result, workflow, opType) {
     for (const [nodeId, payload] of Object.entries(result.outputs)) {