@nanobpm/urban 0.48.0 → 0.49.0

package/src/runtime/core/modules/deploy.test.ts

@@ -4,7 +4,6 @@ import type { RuntimeContext } from "../context.ts";
 import type { HostContext } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
 import { deployModels } from "./deploy.ts";
-import { applyTemplates, resolveTemplates, type TemplateSource } from "./templates.ts";
 
 const ROOT = "/app";
 
@@ -25,14 +24,23 @@ interface Harness {
   deployed: DeployedResource[];
 }
 
-/** A virtual-filesystem host over `files` (keyed by absolute path) plus a recording engine. */
-function makeHarness(
-  files: Record<string, string>,
-  manifest: Partial<AppManifest>,
-  templates?: TemplateSource,
-): Harness {
+/** A virtual-filesystem host over `files` (keyed by absolute path) plus a recording engine. The
+ *  host implements `listDir` (files under a dir) and `listSubdirs` (immediate sub-directories), so
+ *  the convention walk (`resources/*` + `resources/<subdir>/*`) can be exercised. */
+function makeHarness(files: Record<string, string>, manifest: Partial<AppManifest>): Harness {
   const logs: Harness["logs"] = [];
   const deployed: DeployedResource[] = [];
+  const dirsUnder = (dir: string): Set<string> => {
+    const out = new Set<string>();
+    const prefix = `${dir.replace(/\/+$/, "")}/`;
+    for (const f of Object.keys(files)) {
+      if (!f.startsWith(prefix)) continue;
+      const rest = f.slice(prefix.length);
+      const slash = rest.indexOf("/");
+      if (slash > 0) out.add(rest.slice(0, slash));
+    }
+    return out;
+  };
   // biome-ignore lint/plugin: HostContext test double implementing only the fs/log members deployModels exercises; the rest are intentionally absent.
   const host: HostContext = {
     runtime: "node",
@@ -48,6 +56,7 @@ function makeHarness(
       Object.keys(files)
         .filter((f) => dirname(f) === dir)
         .map((f) => f.slice(f.lastIndexOf("/") + 1)),
+    listSubdirs: async (dir: string) => [...dirsUnder(dir)],
   } as unknown as HostContext;
   const engine = {
     deployResources: async (resources: DeployedResource[]) => {
@@ -63,196 +72,123 @@ function makeHarness(
     // biome-ignore lint/plugin: EngineClient test double implementing only deployResources (the sole method deployModels calls).
     engine: engine as unknown as RuntimeContext["engine"],
     host,
-    templates,
   } as unknown as RuntimeContext;
   return { ctx, logs, deployed };
 }
 
-// ── applyTemplates ─────────────────────────────────────────────────────────
-
-test("applyTemplates substitutes a named placeholder", () => {
-  const { content, unresolved } = applyTemplates("<a>{{greet}}</a>", "text/xml", {
-    greet: "hello",
-  });
-  assert.equal(content, "<a>hello</a>");
-  assert.deepEqual(unresolved, []);
-});
-
-test("applyTemplates tolerates inner whitespace in the placeholder", () => {
-  const { content } = applyTemplates("{{  greet  }}", "text/xml", { greet: "hi" });
-  assert.equal(content, "hi");
-});
-
-test("applyTemplates encodes newlines/tabs as XML character references (survives attr normalization)", () => {
-  const { content } = applyTemplates('value="{{p}}"', "text/xml", {
-    p: "line1\nline2\twith <b> & 'q'",
-  });
-  assert.equal(content, 'value="line1&#10;line2&#9;with &lt;b&gt; &amp; &apos;q&apos;"');
-  // Critically, no literal newline/tab remains (those would collapse to spaces in an attribute).
-  assert.ok(!/[\n\t]/.test(content));
-});
-
-test("applyTemplates escapes JSON-string content for .form resources", () => {
-  const { content } = applyTemplates('{"q":"{{p}}"}', "application/json", {
-    p: 'a\nb"c',
-  });
-  assert.equal(content, '{"q":"a\\nb\\"c"}');
-  assert.deepEqual(JSON.parse(content), { q: 'a\nb"c' });
-});
-
-test("applyTemplates leaves unknown placeholders verbatim and reports them once", () => {
-  const { content, unresolved } = applyTemplates("{{x}} {{y}} {{x}}", "text/xml", {});
-  assert.equal(content, "{{x}} {{y}} {{x}}");
-  assert.deepEqual(unresolved, ["x", "y"]);
-});
-
-test("applyTemplates is non-recursive: a template's own braces are not re-expanded", () => {
-  const { content, unresolved } = applyTemplates("{{a}}", "text/xml", {
-    a: "{{b}}",
-    b: "SHOULD-NOT-APPEAR",
-  });
-  assert.equal(content, "{{b}}");
-  assert.deepEqual(unresolved, []);
-});
-
-// ── resolveTemplates ─────────────────────────────────────────────────────────
+// ── models.* override (explicit globs, unchanged behavior) ───────────────────
 
-test("resolveTemplates reads a glob source, keying by file stem", async () => {
-  const { ctx } = makeHarness(
-    { "/app/prompts/review.md": "REVIEW", "/app/prompts/fix-ci.md": "FIXCI" },
-    {},
+test("deployModels uses the manifest models globs when declared, keyed by basename", async () => {
+  const { ctx, deployed } = makeHarness(
+    {
+      "/app/processes/agent.bpmn": "<x/>",
+      "/app/forms/greet.form": "{}",
+      "/app/resources/ignored.bpmn": "<should-not-deploy/>",
+    },
+    { models: { processes: ["processes/*.bpmn"], forms: ["forms/*.form"] } },
   );
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/*.md"]]);
-  assert.deepEqual({ ...map }, { review: "REVIEW", "fix-ci": "FIXCI" });
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 2);
+  const byName = Object.fromEntries(deployed.map((d) => [d.name, d]));
+  assert.equal(byName["agent.bpmn"].contentType, "text/xml");
+  assert.equal(byName["greet.form"].contentType, "application/json");
+  // With an explicit override, the convention `resources/` walk is skipped entirely.
+  assert.ok(!deployed.some((d) => d.name === "ignored.bpmn"));
 });
 
-test("resolveTemplates scans a bare directory entry", async () => {
-  const { ctx } = makeHarness(
-    { "/app/prompts/a.md": "A", "/app/prompts/b.md": "B" },
-    {},
+test("deployModels deploys content verbatim (no {{name}} substitution remains)", async () => {
+  const { ctx, deployed } = makeHarness(
+    { "/app/processes/agent.bpmn": '<x value="{{review}}" />' },
+    { models: { processes: ["processes/*.bpmn"] } },
   );
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts"]]);
-  assert.deepEqual({ ...map }, { a: "A", b: "B" });
-});
-
-test("resolveTemplates resolves a literal file entry", async () => {
-  const { ctx } = makeHarness({ "/app/prompts/one.md": "ONE" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/one.md"]]);
-  assert.deepEqual({ ...map }, { one: "ONE" });
-});
-
-test("resolveTemplates ignores a directory with no readable files without warning", async () => {
-  // A directory that exists (has nested content) but no files directly under it: previously the
-  // non-glob fallback treated it as a literal file and logged a misleading "unreadable entry" warn.
-  const { ctx, logs } = makeHarness({ "/app/prompts/nested/x.md": "X" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts"]]);
-  assert.deepEqual({ ...map }, {});
-  assert.equal(logs.filter((l) => l.level === "warn").length, 0);
-});
-
-test("resolveTemplates merges a programmatic map, letting later sources win", async () => {
-  const { ctx } = makeHarness({ "/app/prompts/review.md": "FROM-FILE" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [
-    ["prompts/*.md"],
-    { review: "FROM-MAP", extra: "X" },
-  ]);
-  assert.deepEqual({ ...map }, { review: "FROM-MAP", extra: "X" });
-});
-
-test("resolveTemplates returns a null-prototype map so `__proto__` keys can't pollute", async () => {
-  // A template file literally named `__proto__.md`, or a programmatic map keyed by `__proto__`,
-  // must set a plain own property rather than trip the magic prototype setter on `{}`.
-  const { ctx } = makeHarness({ "/app/prompts/__proto__.md": "PWN" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [
-    ["prompts/__proto__.md"],
-    { extra: "X" },
-  ]);
-  assert.equal(Object.getPrototypeOf(map), null);
-  assert.equal(Object.getPrototypeOf({}), Object.prototype, "global prototype untouched");
-  assert.equal(map.extra, "X");
-  assert.equal(Object.prototype.hasOwnProperty.call(map, "__proto__"), true);
+  await deployModels(ctx);
+  assert.equal(deployed[0].content, '<x value="{{review}}" />');
 });
 
-test("resolveTemplates skips a file whose stem is not a valid placeholder name, with a warning", async () => {
-  // `spaced name.md` yields the stem `spaced name`, which the `{{…}}` placeholder charset (`[\w.-]`)
-  // can never match — so it would be unreferenceable and silently ignored. Fail loudly instead.
-  const { ctx, logs } = makeHarness(
-    { "/app/prompts/spaced name.md": "NOPE", "/app/prompts/ok.md": "YES" },
-    {},
+test("deployModels treats a declared-but-empty models block as an override, not convention", async () => {
+  // A present `models` block that resolves to zero files is an explicit override: it must NOT
+  // silently fall back to the `resources/` convention walk (would deploy resources the author
+  // never opted into). Keyed off the block's *presence*, not an empty pattern set.
+  const { ctx, deployed, logs } = makeHarness(
+    { "/app/resources/order.bpmn": "<should-not-deploy/>" },
+    { models: { processes: [] } },
   );
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/*.md"]]);
-  assert.deepEqual({ ...map }, { ok: "YES" });
-  const warn = logs.find((l) => l.level === "warn" && l.msg === "template: skipped unsupported name");
-  assert.ok(warn, "expected an unsupported-name warning");
-  assert.equal(warn?.fields?.name, "spaced name");
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 0);
+  assert.deepEqual(deployed, []);
+  // No-model-files log (override path), NOT the "no resources found by convention" log.
+  assert.ok(logs.some((l) => l.msg.includes("no model files matched")));
+  assert.ok(!logs.some((l) => l.msg.includes("no resources found by convention")));
 });
 
-// ── deployModels integration ─────────────────────────────────────────────────
+// ── deploy-by-convention (no models declared) ────────────────────────────────
 
-test("deployModels substitutes manifest templates into deployed model content", async () => {
-  const { ctx, deployed } = makeHarness(
+test("deployModels discovers resources/ by convention when no models are declared", async () => {
+  const { ctx, deployed, logs } = makeHarness(
     {
-      "/app/processes/agent.bpmn": '<x value="{{review}}" />',
-      "/app/prompts/review.md": "Do the review",
+      "/app/resources/order.bpmn": "<p/>",
+      "/app/resources/decide.dmn": "<d/>",
+      "/app/resources/prompts/review.md": "Do the review",
+      "/app/resources/forms/greet.form": "{}",
+      // Docs live OUTSIDE resources/ and must never deploy.
+      "/app/docs/guide.md": "# docs",
+      "/app/AGENTS.md": "# agents",
+      "/app/README.md": "# readme",
     },
-    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+    {},
   );
   const res = await deployModels(ctx);
-  assert.equal(res.deployed, 1);
-  assert.equal(deployed[0].name, "agent.bpmn");
-  assert.equal(deployed[0].content, '<x value="Do the review" />');
+  const names = deployed.map((d) => d.name).sort();
+  assert.deepEqual(names, ["decide.dmn", "greet.form", "order.bpmn", "review.md"]);
+  assert.equal(res.deployed, 4);
+  // A prompt (.md under resources/) is a GenericScript resource → octet-stream content type.
+  const prompt = deployed.find((d) => d.name === "review.md");
+  assert.equal(prompt?.contentType, "application/octet-stream");
+  assert.equal(prompt?.content, "Do the review");
+  assert.ok(logs.some((l) => l.fields?.byConvention === true));
 });
 
-test("deployModels lets the programmatic templates option win over the manifest", async () => {
+test("deployModels convention walk is shallow — one level deep only", async () => {
   const { ctx, deployed } = makeHarness(
     {
-      "/app/processes/agent.bpmn": '<x value="{{review}}" />',
-      "/app/prompts/review.md": "FROM-MANIFEST",
+      "/app/resources/top.bpmn": "<a/>",
+      "/app/resources/sub/one.bpmn": "<b/>",
+      // Two levels deep: NOT swept in (shallow-by-convention).
+      "/app/resources/sub/deeper/two.bpmn": "<c/>",
     },
-    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
-    { review: "FROM-OPTION" },
+    {},
   );
   await deployModels(ctx);
-  assert.equal(deployed[0].content, '<x value="FROM-OPTION" />');
+  const names = deployed.map((d) => d.name).sort();
+  assert.deepEqual(names, ["one.bpmn", "top.bpmn"]);
 });
 
-test("deployModels warns on an unresolved placeholder but still deploys", async () => {
-  const { ctx, deployed, logs } = makeHarness(
+test("deployModels errors on a basename collision across resources/ subdirs", async () => {
+  const { ctx } = makeHarness(
     {
-      "/app/processes/agent.bpmn": '<x a="{{present}}" b="{{missing}}" />',
-      "/app/prompts/present.md": "HERE",
+      "/app/resources/a/order.bpmn": "<a/>",
+      "/app/resources/b/order.bpmn": "<b/>",
     },
-    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+    {},
   );
-  const res = await deployModels(ctx);
-  assert.equal(res.deployed, 1);
-  assert.equal(deployed[0].content, '<x a="HERE" b="{{missing}}" />');
-  const warn = logs.find((l) => l.msg.includes("unresolved template placeholders"));
-  assert.ok(warn, "expected an unresolved-placeholder warning");
-  assert.deepEqual(warn?.fields?.unresolved, ["missing"]);
+  await assert.rejects(deployModels(ctx), /basename collision/);
 });
 
-test("deployModels leaves unknown-extension resources untouched (no XML escaping)", async () => {
-  // Unknown extensions (application/octet-stream) have no safe escaper, so substitution must be
-  // skipped rather than run the default XML escaper and risk corrupting the resource.
-  const { ctx, deployed } = makeHarness(
+test("deployModels errors on a basename collision under an explicit override too", async () => {
+  const { ctx } = makeHarness(
     {
-      "/app/models/notes.txt": "raw {{review}} & <stuff>",
-      "/app/prompts/review.md": "R",
+      "/app/processes/order.bpmn": "<a/>",
+      "/app/extra/order.bpmn": "<b/>",
     },
-    { models: { processes: ["models/*.txt"], templates: ["prompts/*.md"] } },
+    { models: { processes: ["processes/*.bpmn", "extra/*.bpmn"] } },
   );
-  await deployModels(ctx);
-  assert.equal(deployed[0].contentType, "application/octet-stream");
-  assert.equal(deployed[0].content, "raw {{review}} & <stuff>");
+  await assert.rejects(deployModels(ctx), /basename collision/);
 });
 
-test("deployModels is a no-op on content when no templates are configured", async () => {
-  const { ctx, deployed } = makeHarness(
-    { "/app/processes/agent.bpmn": '<x value="{{review}}" />' },
-    { models: { processes: ["processes/*.bpmn"] } },
-  );
-  await deployModels(ctx);
-  // With no templates, placeholders are left untouched (no substitution pass runs).
-  assert.equal(deployed[0].content, '<x value="{{review}}" />');
+test("deployModels is a no-op when resources/ is empty and no models are declared", async () => {
+  const { ctx, deployed, logs } = makeHarness({ "/app/docs/x.md": "y" }, {});
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 0);
+  assert.deepEqual(deployed, []);
+  assert.ok(logs.some((l) => l.msg.includes("no resources found by convention")));
 });

package/src/runtime/core/modules/deploy.ts

@@ -1,9 +1,22 @@
-// deploy — resolve the manifest `models` patterns and deploy the resources to the engine,
-// substituting any `{{name}}` templates into each resource first (see templates.ts).
+// deploy — resolve the app's deployable resources and send them to the engine.
+//
+// Resources are found by ONE of two paths:
+//   1. Convention (the default, ADR 0062): when the manifest declares no `models`, deployables are
+//      discovered by walking `resources/` — shallow, one level deep. `resources/` is deploy-only:
+//      everything under it (and nothing outside it) is deployed. Docs (`docs/`, `AGENTS.md`,
+//      top-level `*.md`) live outside `resources/` and are never swept in.
+//   2. Explicit override: when the manifest declares `models` globs, those are used exactly (the
+//      convention walk is skipped) — the escape hatch for a non-convention layout.
+//
+// Either way the deploy dedupe key is the resource's basename (filename only), so a basename
+// collision — two files with the same name in different directories — would silently clobber one
+// resource with another at the engine. We detect that up front and fail loudly instead.
 
 import type { RuntimeContext } from "../context.ts";
-import { expandPatterns } from "../glob.ts";
-import { applyTemplates, resolveTemplates } from "./templates.ts";
+import { discoverResources, expandPatterns } from "../glob.ts";
+
+/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+export const RESOURCES_DIR = "resources";
 
 function contentTypeFor(path: string): string {
   if (path.endsWith(".bpmn")) return "text/xml";
@@ -17,47 +30,66 @@ function baseName(path: string): string {
   return i >= 0 ? path.slice(i + 1) : path;
 }
 
-/** Deploy all processes, decisions and forms declared under `models`. Each resource has its
- *  `{{name}}` placeholders substituted (manifest `models.templates`, then the programmatic
- *  `ctx.templates`, the latter winning) before it is sent to the engine. */
+/** Fail loudly when two resolved files share a basename (the deploy dedupe key), naming the
+ *  colliding paths so the author can rename or relocate one. */
+function assertNoBasenameCollisions(files: string[]): void {
+  const byName = new Map<string, string[]>();
+  for (const path of files) {
+    const name = baseName(path);
+    const list = byName.get(name);
+    if (list) list.push(path);
+    else byName.set(name, [path]);
+  }
+  const collisions = [...byName.entries()].filter(([, paths]) => paths.length > 1);
+  if (collisions.length === 0) return;
+  const detail = collisions
+    .map(([name, paths]) => `  ${name}: ${paths.slice().sort().join(", ")}`)
+    .join("\n");
+  throw new Error(
+    "deploy: basename collision — resources are deployed keyed by filename, so two files with " +
+      `the same name would clobber each other. Rename or relocate one of:\n${detail}`,
+  );
+}
+
+/**
+ * Deploy the app's processes, decisions and forms.
+ *
+ * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
+ * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
+ * hard error in either mode.
+ */
 export async function deployModels(ctx: RuntimeContext): Promise<{ deployed: number; files: string[] }> {
-  const models = ctx.manifest.models ?? {};
+  const models = ctx.manifest.models;
   const patterns = [
-    ...(models.processes ?? []),
-    ...(models.decisions ?? []),
-    ...(models.forms ?? []),
+    ...(models?.processes ?? []),
+    ...(models?.decisions ?? []),
+    ...(models?.forms ?? []),
   ];
-  const files = await expandPatterns(ctx.host, ctx.root, patterns);
+  // Convention is keyed off the *absence* of the `models` block, not an empty pattern set: a
+  // declared `models` (even one resolving to zero files) is an explicit override that must NOT
+  // silently fall back to the `resources/` walk (ADR 0062: "no `models` block → convention;
+  // `models` present → exact override").
+  const byConvention = models === undefined;
+  const files = byConvention
+    ? await discoverResources(ctx.host, ctx.root, RESOURCES_DIR)
+    : await expandPatterns(ctx.host, ctx.root, patterns);
   if (files.length === 0) {
-    ctx.host.log("info", "deploy: no model files matched", { patterns });
+    if (byConvention) {
+      ctx.host.log("info", "deploy: no resources found by convention", { dir: RESOURCES_DIR });
+    } else {
+      ctx.host.log("info", "deploy: no model files matched", { patterns });
+    }
     return { deployed: 0, files: [] };
   }
-  // Resolve templates once (manifest globs/dirs, then the programmatic deploy option). An empty
-  // map makes substitution a no-op, so apps that use no templates are unaffected.
-  const templates = await resolveTemplates(ctx.host, ctx.root, [models.templates, ctx.templates]);
-  const hasTemplates = Object.keys(templates).length > 0;
+  assertNoBasenameCollisions(files);
   const resources = await Promise.all(
-    files.map(async (path) => {
-      const contentType = contentTypeFor(path);
-      let content = await ctx.host.readTextFile(path);
-      // Only substitute into the model content types we know how to escape (XML for .bpmn/.dmn,
-      // JSON for .form). Unknown extensions map to application/octet-stream; running the default
-      // XML escaper over them could deterministically corrupt a non-XML/JSON resource that a
-      // manifest pattern matched by accident, so leave those files untouched.
-      if (hasTemplates && contentType !== "application/octet-stream") {
-        const applied = applyTemplates(content, contentType, templates);
-        content = applied.content;
-        if (applied.unresolved.length > 0) {
-          ctx.host.log("warn", "deploy: unresolved template placeholders", {
-            file: path,
-            unresolved: applied.unresolved,
-          });
-        }
-      }
-      return { name: baseName(path), content, contentType };
-    }),
+    files.map(async (path) => ({
+      name: baseName(path),
+      content: await ctx.host.readTextFile(path),
+      contentType: contentTypeFor(path),
+    })),
   );
   const { deployed } = await ctx.engine.deployResources(resources);
-  ctx.host.log("info", "deploy: models deployed", { deployed, files });
+  ctx.host.log("info", "deploy: resources deployed", { deployed, files, byConvention });
   return { deployed, files };
 }

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -96,6 +96,7 @@ function fakeEngine(states: Record<string, ProcessInstanceSnapshot["state"]>): {
     cancelInstance: notUsed("cancelInstance"),
     publishMessage: notUsed("publishMessage"),
     searchUserTasks: notUsed("searchUserTasks"),
+    getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
@@ -285,6 +286,95 @@ test("without statusField/activeStatuses, polls every row", async () => {
   await h.close();
 });
 
+test("terminalStatuses: reconciles a TERMINATED row in an un-enumerated non-terminal status (the allow-list regression)", async () => {
+  // The row's status ("awaiting_operator") is listed in NEITHER activeStatuses nor terminalStatuses
+  // — the exact drift an allow-list misses. A fail-open terminalStatuses selector still polls it.
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ activeStatuses: undefined, terminalStatuses: ["abandoned"] });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // it WAS polled despite not being in any enumerated list
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "abandoned"); // …and reconciled
+  await handle.stop();
+  await h.close();
+});
+
+test("terminalStatuses: a row already in a terminal status is not polled", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "abandoned", note: null }); // terminal
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ activeStatuses: undefined, terminalStatuses: ["abandoned"] });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // pi2 was already terminal, excluded from the poll
+  await handle.stop();
+  await h.close();
+});
+
+test("terminalStatuses wins when a binding somehow declares both selectors (fail-open)", async () => {
+  // Validation rejects declaring both, but a hand-built binding must still behave predictably:
+  // terminalStatuses (the fail-open selector) takes precedence over activeStatuses.
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    // status is NOT in activeStatuses — an allow-list would skip it — but IS non-terminal.
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: null });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ activeStatuses: ["planning"], terminalStatuses: ["abandoned"] });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // polled via the terminalStatuses selector
+  assert.equal((await h.table.get("pi1"))?.status, "abandoned");
+  await handle.stop();
+  await h.close();
+});
+
+test("a malformed (non-array) terminalStatuses degrades to fail-open poll-all, not a Set-of-characters filter", async () => {
+  // A hand-built/JSON binding could carry a bare string. The buggy path (`new Set("ab")`) would
+  // filter rows by whether their status is one of those *characters* — silently dropping rows.
+  // The shared `isConfiguredStatusSelector` gate makes a malformed selector fall through to the
+  // fail-open poll-all path instead. Build the invalid fixture via JSON.parse (no `as` cast).
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    // Both statuses are single characters that appear in "abandoned" — the buggy Set-of-chars
+    // filter would exclude them, polling nothing; the fail-open path polls both.
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "a", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "b", note: null });
+  });
+  const malformed = JSON.parse('{"terminalStatuses":"abandoned","activeStatuses":null}');
+  const sched = fakeScheduler();
+  const binding = planBinding(malformed);
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries[0]?.sort(), ["pi1", "pi2"]); // fail-open: every row polled
+  await handle.stop();
+  await h.close();
+});
+
+test("a malformed (non-array) activeStatuses degrades to fail-open poll-all instead of crashing .map", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "planning", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "dispatched", note: null });
+  });
+  const malformed = JSON.parse('{"activeStatuses":"planning","terminalStatuses":null}');
+  const sched = fakeScheduler();
+  const binding = planBinding(malformed);
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries[0]?.sort(), ["pi1", "pi2"]); // no crash; fail-open poll-all
+  await handle.stop();
+  await h.close();
+});
+
 test("defaults pollMs when the binding omits it", async () => {
   const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
   const h = await withHarness(engine, PLANS_DDL, async (t) => {

package/src/runtime/core/modules/instance-tracking.ts

@@ -14,7 +14,7 @@
 // row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
 
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
-import type { InstanceTracking } from "../manifest.ts";
+import { type InstanceTracking, isConfiguredStatusSelector } from "../manifest.ts";
 import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
 
 /** Default poll interval when a binding does not set `pollMs`. */
@@ -65,13 +65,26 @@ async function reconcileOnce(
 ): Promise<{ scanned: number; reconciled: number }> {
   const table = api.data.table<Row>(binding.table, binding.keyField);
 
-  // Select the rows worth polling. With a statusField + activeStatuses, only rows in an
-  // active status are candidates, so a row already in a terminal status is skipped; without
-  // them every row is polled and a terminal instance's row is idempotently re-patched (the
-  // engine query returns only TERMINATED instances and the patch is a no-op once applied).
+  // Select the rows worth polling. Three modes, in precedence order:
+  //  - `terminalStatuses` (fail-open exclusion): poll every row whose `statusField` is NOT
+  //    a terminal value. A newly-added non-terminal status is polled by default, so it can't
+  //    silently fall out of reconciliation; only already-terminal rows are excluded (bounded).
+  //  - `activeStatuses` (fail-closed allow-list): poll only rows in an enumerated active status.
+  //  - neither: poll every row; a terminal instance's row is idempotently re-patched (the engine
+  //    query returns only TERMINATED instances and the patch is a no-op once applied).
+  // `terminalStatuses` and `activeStatuses` are mutually exclusive per binding (validation rejects
+  // both); if both are somehow present, `terminalStatuses` wins (the fail-open selector). Each
+  // selector is gated through the shared `isConfiguredStatusSelector` predicate (a non-empty array
+  // of non-empty strings) — the same one validation uses — so a malformed value (a bare string, an
+  // empty array) degrades to the fail-open poll-all path here instead of `new Set("abandoned")`
+  // silently filtering by character, or a non-array crashing `activeStatuses.map(...)`.
   let candidates: Row[];
   const statusField = binding.statusField;
-  if (statusField && binding.activeStatuses && binding.activeStatuses.length > 0) {
+  if (statusField && isConfiguredStatusSelector(binding.terminalStatuses)) {
+    const terminal = new Set(binding.terminalStatuses);
+    const all = await table.all();
+    candidates = all.filter((row) => !terminal.has(String(row[statusField])));
+  } else if (statusField && isConfiguredStatusSelector(binding.activeStatuses)) {
     const perStatus = await Promise.all(
       binding.activeStatuses.map((s): Promise<Row[]> => table.find({ [statusField]: s })),
     );