@nanobpm/nano-workforce 0.83.0 → 0.85.0

package/scripts/pages-contract.test.ts

@@ -112,6 +112,12 @@ function filterFields(filter: Json): string[] {
   return filter.map((f: Json) => f?.field).filter(Boolean);
 }
 
+// Pull `{{field}}` interpolation names out of a prose renderer's header template (nano-ide#274).
+function templateFields(tpl: Json): string[] {
+  if (typeof tpl !== "string") return [];
+  return [...tpl.matchAll(/\{\{([^{}]+)\}\}/g)].map((m) => m[1].trim()).filter(Boolean);
+}
+
 function collectRefs(page: string, node: Json, out: Ref[]): void {
   if (Array.isArray(node)) {
     for (const v of node) collectRefs(page, v, out);
@@ -120,10 +126,17 @@ function collectRefs(page: string, node: Json, out: Ref[]): void {
   if (!node || typeof node !== "object") return;
 
   // Top-level datasource grid: the datasource lives at `node.data`, while `columns`, `rowKey`,
-  // `filter`/`tabs`, and `detail` are siblings on the same `node` (the grid props).
+  // `filter`/`tabs`, and `detail` are siblings on the same `node` (the grid props). A `prose`
+  // renderer (nano-ide#274) binds the same `node.data` but has no `columns`: its displayed content
+  // is the header template's `{{field}}` refs plus the single `body` field, so fold those in as
+  // "columns" so the field-existence + surface guards below apply to prose sections too.
   const data = node.data;
   if (data && data.kind === "datasource" && typeof data.table === "string") {
-    const columns: string[] = (node.columns ?? []).map((c: Json) => c.field).filter(Boolean);
+    const columns: string[] = [
+      ...(node.columns ?? []).map((c: Json) => c.field),
+      ...templateFields(node.header),
+      ...(typeof node.body === "string" ? [node.body] : []),
+    ].filter(Boolean);
     // Every reference that resolves to a column on this table — the runtime 400s on any of them if
     // it names a column the migrations never created, so all must be guarded, not just displayed
     // columns. `detail.fields`/`detail.linkField` render columns of the same top-level row.
@@ -215,17 +228,19 @@ test("issue #87: plan_reviews is surfaced on the per-epic detail page", async ()
   const onEpicDetail = refs.some(
     (r) => r.page === "epic-detail.page.json" && r.table === "plan_reviews",
   );
-  assert(onEpicDetail, "epic-detail.page.json must bind a grid to plan_reviews (plan-review trace)");
+  assert(onEpicDetail, "epic-detail.page.json must bind the plan-review trace to plan_reviews");
 
-  // The trace is only useful with the verdict + critique columns, so pin them. Assert against the
-  // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) so
-  // a column silently dropped from the grid UI can't pass by being referenced elsewhere.
+  // The trace is only useful with the verdict + critique surfaced, so pin them. Assert against the
+  // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) —
+  // for the `prose` renderer (nano-ide#274) these are the header template's `{{round}}`/`{{approved}}`
+  // refs plus the `findings` body — so a field silently dropped from the UI can't pass by being
+  // referenced elsewhere.
   const required = ["round", "approved", "findings"];
   for (const r of refs.filter((x) => x.table === "plan_reviews")) {
     for (const col of required) {
       assert(
         r.columns.includes(col),
-        `${r.page}: plan_reviews grid must expose the "${col}" column`,
+        `${r.page}: plan_reviews trace must surface the "${col}" field`,
       );
     }
   }

package/workers/readiness-probe/worker.test.ts

@@ -9,7 +9,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects } from "#test-assert";
 import type { CommandResult, HttpResponse, ProbeExec, ReadinessProbe } from "../../app/readiness.ts";
 import { parseProbe } from "../../app/readiness.ts";
-import handler, { pollUntilReady, READINESS_READY_MESSAGE, readGateVars } from "./worker.ts";
+import handler, { pollUntilReady, READINESS_READY_MESSAGE, readGateVars, safeBind } from "./worker.ts";
 
 // A virtual clock: `now()` advances only when the loop's `wait(ms)` is called, so a never-ready
 // probe races to its deadline in zero real time (no setTimeout) and the test can never hang.
@@ -40,6 +40,40 @@ function execReturning(seq: Array<HttpResponse>): ProbeExec {
 const httpProbe = (poll: ReadinessProbe["poll"]): ReadinessProbe =>
   parseProbe({ kind: "http", target: "https://x/health", poll });
 
+test("safeBind: strips reserved keys (ready/detail) so a bind can only ADD outputs, never shadow the payload", () => {
+  const cleaned = safeBind({ resolvedArtifact: "@nanobpm/urban@0.54.0", ready: "false", detail: "spoofed" });
+  assertEquals(cleaned.resolvedArtifact, "@nanobpm/urban@0.54.0");
+  assertEquals("ready" in cleaned, false, "a bound 'ready' can never override the canonical payload");
+  assertEquals("detail" in cleaned, false, "a bound 'detail' can never override the canonical payload");
+  assertEquals(Object.keys(safeBind(undefined)).length, 0, "an absent bind yields an empty object");
+});
+
+test("pollUntilReady: a fallback that throws is caught, logged by class name (no leak), and stays not-ready", async () => {
+  const clock = fakeClock();
+  const seen: string[] = [];
+  let publishes = 0;
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 5, timeoutMs: 30, backoff: "fixed" }),
+    gateKey: "gate-fallback-throws",
+    exec: execReturning([{ status: 503, body: "" }]),
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async () => {
+      publishes += 1;
+    },
+    fallback: async () => {
+      throw new Error("boom at https://h/p?token=s3cr3t");
+    },
+    log: (msg) => seen.push(msg),
+  });
+  assert(!res.ready, "a throwing fallback keeps the not-ready outcome for the engine timer");
+  assertEquals(publishes, 0, "nothing is published when the fallback throws");
+  const all = seen.join("\n");
+  assert(all.includes("fallback error: Error"), "the fallback error is logged by class name");
+  assert(!all.includes("s3cr3t"), "the raw error message (with its secret) must not leak");
+});
+
 test("pollUntilReady: publishes readiness-ready once and returns ready when a probe goes green", async () => {
   const clock = fakeClock();
   const published: Array<{ detail: string }> = [];
@@ -59,6 +93,90 @@ test("pollUntilReady: publishes readiness-ready once and returns ready when a pr
   assertEquals(published.length, 1, "exactly one readiness message was published");
 });
 
+test("pollUntilReady: forwards a matcher's bind through publish into the message variables (#274 Gap B)", async () => {
+  // A capability probe resolves a version; its bind must flow through publish so the gate can surface
+  // resolvedArtifact as an output. The gh-api stub returns a release whose provenance carries #274.
+  const clock = fakeClock();
+  const published: Array<{ detail: string; bind?: Record<string, string> }> = [];
+  const payload = JSON.stringify([{ tag_name: "@nanobpm/urban@0.54.0", body: "## Provenance\n- #274\n" }]);
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(): Promise<CommandResult> {
+      return { code: 0, stdout: payload, stderr: "" };
+    },
+  };
+  const res = await pollUntilReady({
+    probe: parseProbe({
+      kind: "capability",
+      target: "github-releases:nanobpm/nano-ide",
+      match: { capabilityRef: "nano-ide#274", package: "@nanobpm/urban" },
+      poll: { everyMs: 5, timeoutMs: 5000, backoff: "fixed" },
+    }),
+    gateKey: "gate-cap",
+    exec,
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async (detail, bind) => {
+      published.push({ detail, bind });
+    },
+  });
+  assert(res.ready, "the capability edge resolved");
+  assertEquals(published.length, 1, "exactly one readiness message was published");
+  assertEquals(published[0]?.bind?.resolvedArtifact, "@nanobpm/urban@0.54.0", "the resolved artifact flowed through the bind");
+});
+
+test("pollUntilReady: the gated fallback fires ONCE at budget exhaustion and can still resolve+publish", async () => {
+  // Deterministic provenance never resolves (no matching release), so the loop exhausts its budget —
+  // the gate boundary. The fallback thunk then verifies empirically and publishes a bound version.
+  const clock = fakeClock();
+  const published: Array<{ bind?: Record<string, string> }> = [];
+  let fallbackCalls = 0;
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 5, timeoutMs: 30, backoff: "fixed" }),
+    gateKey: "gate-fallback",
+    exec: execReturning([{ status: 503, body: "" }]),
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async (_detail, bind) => {
+      published.push({ bind });
+    },
+    fallback: async () => {
+      fallbackCalls += 1;
+      return { ready: true, detail: "verified empirically", bind: { resolvedArtifact: "@nanobpm/urban@0.60.0" } };
+    },
+  });
+  assert(res.ready, "the boundary fallback resolved the edge");
+  assertEquals(fallbackCalls, 1, "the fallback fires exactly once, at the boundary — never per attempt");
+  assertEquals(published[0]?.bind?.resolvedArtifact, "@nanobpm/urban@0.60.0");
+});
+
+test("pollUntilReady: a fallback that does not resolve leaves the not-ready outcome for the engine timer", async () => {
+  const clock = fakeClock();
+  let publishes = 0;
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 5, timeoutMs: 30, backoff: "fixed" }),
+    gateKey: "gate-fallback-noop",
+    exec: execReturning([{ status: 503, body: "" }]),
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async () => {
+      publishes += 1;
+    },
+    fallback: async () => ({ ready: false, detail: "still nothing" }),
+  });
+  assert(!res.ready, "an inconclusive fallback keeps the wait bounded by the engine timer");
+  assertEquals(publishes, 0, "no readiness signal is published when the fallback does not resolve");
+  assert(
+    res.detail.includes("still nothing"),
+    "the inconclusive fallback's (redacted) diagnostic is surfaced in the returned detail, not discarded",
+  );
+});
+
 test("pollUntilReady: a never-green probe exhausts its budget and returns not-ready WITHOUT publishing", async () => {
   const clock = fakeClock();
   let publishes = 0;
@@ -79,6 +197,34 @@ test("pollUntilReady: a never-green probe exhausts its budget and returns not-re
   assert(clock.now() <= 100, "the loop stopped at (or before) its declared budget");
 });
 
+test("pollUntilReady: keeps probing up to the deadline — a flip-to-ready in the final backoff window is caught, not missed", async () => {
+  // everyMs 10, budget 25: three deterministic probes land at t=0,10,20. A full-backoff sleep from
+  // t=20 would jump to t=30 (past the 25ms bound) and stop probing early, missing a green at t=25 and
+  // forcing a spurious timeout escalation. The clamp keeps probing to the same bound the engine holds.
+  const clock = fakeClock();
+  let publishes = 0;
+  const exec = execReturning([
+    { status: 503, body: "" },
+    { status: 503, body: "" },
+    { status: 503, body: "" },
+    { status: 200, body: "ok" },
+  ]);
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 10, timeoutMs: 25, backoff: "fixed" }),
+    gateKey: "gate-final-window",
+    exec,
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async () => {
+      publishes += 1;
+    },
+  });
+  assert(res.ready, "the flip-to-ready inside the final backoff window was probed and caught");
+  assertEquals(publishes, 1, "the readiness signal was published exactly once");
+  assert(clock.now() <= 25, "the worker never probed past the engine-enforced deadline");
+});
+
 test("pollUntilReady: an I/O throw is caught and treated as not-ready (never rejects), and its raw message is not leaked", async () => {
   const clock = fakeClock();
   const seen: string[] = [];

package/workers/readiness-probe/worker.ts

@@ -16,6 +16,7 @@ import { readEnvOr } from "../../app/contracts.ts";
 import {
   DEFAULT_EVERY_MS,
   defaultProbeExec,
+  makeCapabilityFallback,
   nextDelay,
   normalizePoll,
   type ProbeExec,
@@ -40,6 +41,22 @@ export const READINESS_READY_MESSAGE = "readiness-ready";
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
+/** The canonical gate-payload keys the matcher's `bind` must never override. `bind` is the
+ * kind-agnostic emit primitive (#274 Gap B), but it flows from matcher output into both the
+ * `readiness-ready` message variables and the worker output — so a matcher that (accidentally or
+ * maliciously) binds `ready`/`detail` could shadow the canonical payload and break the gate
+ * contract. Strip them before spreading so a matcher can only ADD outputs, never overwrite the
+ * shape the gate correlates on. */
+const RESERVED_BIND_KEYS: ReadonlySet<string> = new Set(["ready", "detail"]);
+export function safeBind(bind?: Record<string, string>): Record<string, string> {
+  if (!bind) return {};
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(bind)) {
+    if (!RESERVED_BIND_KEYS.has(k)) out[k] = v;
+  }
+  return out;
+}
+
 /** The effective poll cadence: the descriptor's values, with `everyMs` defaulting through the env
  * contract (`NANO_READINESS_POLL_EVERY_MS`) when the descriptor omits it, then the built-in
  * defaults/clamps in {@link normalizePoll}. Reads the env value from the injected `env` (not the
@@ -64,7 +81,12 @@ export async function pollUntilReady(deps: {
   env: Record<string, string | undefined>;
   now: () => number;
   wait: (ms: number) => Promise<void>;
-  publish: (detail: string) => Promise<void>;
+  publish: (detail: string, bind?: Record<string, string>) => Promise<void>;
+  /** An OPTIONAL last-attempt thunk run ONCE at the gate boundary (local budget exhausted) before
+   * giving up — the seam for the gated empirical fallback (decision 5). A ready result is published
+   * (with its bind) and returned; anything else keeps the not-ready outcome so the engine timer
+   * bounds the wait as usual. Kept generic so the loop stays kind-agnostic. */
+  fallback?: () => Promise<ProbeResult | null>;
   log?: (msg: string) => void;
 }): Promise<ProbeResult> {
   const poll = effectivePoll(deps.probe.poll, deps.env);
@@ -84,15 +106,46 @@ export async function pollUntilReady(deps: {
     }));
     deps.log?.(`readiness probe ${label} attempt ${attempt + 1}: ${res.detail}`);
     if (res.ready) {
-      await deps.publish(res.detail);
+      await deps.publish(res.detail, res.bind);
       return res;
     }
     attempt += 1;
-    const wait = nextDelay(attempt, poll);
-    if (deps.now() + wait >= deadline) {
-      return { ready: false, detail: "probe budget exhausted; engine timer bounds the wait" };
+    const remaining = deadline - deps.now();
+    if (remaining <= 0) {
+      // The gate boundary: the deterministic poll is exhausted. Give the gated fallback (if any) ONE
+      // empirical attempt before conceding to the engine timer — a capability provenance under-reports
+      // can still resolve here, exactly once, never per unrelated release.
+      const settled = deps.fallback
+        ? await deps.fallback().catch((err) => {
+            // Never swallow a fallback failure silently — it degrades to "not ready" and is hard
+            // to diagnose. Log only the error class name (no message), consistent with the main
+            // probeOnce error handling, so a target URL/token in the message never leaks.
+            deps.log?.(
+              `readiness probe ${label} fallback error: ${err instanceof Error ? err.name : "Error"}`,
+            );
+            return null;
+          })
+        : null;
+      if (settled?.ready) {
+        deps.log?.(`readiness probe ${label} fallback: ${settled.detail}`);
+        await deps.publish(settled.detail, settled.bind);
+        return settled;
+      }
+      // Surface the fallback's (already-redacted) diagnostic when one ran and reported not-ready, so a
+      // timeout escalation is actionable instead of a generic "budget exhausted". `settled` is null when
+      // there is no fallback or it threw (logged above), in which case only the generic detail applies.
+      return {
+        ready: false,
+        detail: settled
+          ? `probe budget exhausted; engine timer bounds the wait (fallback: ${settled.detail})`
+          : "probe budget exhausted; engine timer bounds the wait",
+      };
     }
-    await deps.wait(wait);
+    // Clamp the sleep to the time left until `deadline` so the worker keeps probing right up to the
+    // SAME bound the engine timer enforces. Sleeping a full `nextDelay` unconditionally would stop
+    // probing up to one backoff early — a window where readiness could flip to ready but no
+    // `readiness-ready` message is published, forcing a spurious timeout escalation.
+    await deps.wait(Math.min(nextDelay(attempt, poll), remaining));
   }
 }
 
@@ -123,24 +176,31 @@ export function readGateVars(vars: { gateKey?: unknown; probeTimeout?: unknown }
 const handler: AppJobHandler<In, Out> = async (job, app) => {
   const probe = parseProbe(job.variables.probe);
   const { gateKey, probeTimeout } = readGateVars(job.variables);
+  const exec = defaultProbeExec();
   const result = await pollUntilReady({
     probe,
     gateKey,
     probeTimeout,
-    exec: defaultProbeExec(),
+    exec,
     env: process.env,
     now: () => Date.now(),
     wait: sleep,
-    publish: async (detail) => {
+    // The gated empirical fallback (decision 5) — a no-op for every kind but a `capability` probe
+    // that declares a `verifyCommand`, so the deterministic provenance lookup stays the default.
+    fallback: makeCapabilityFallback(probe, exec, process.env),
+    publish: async (detail, bind) => {
       await app.engine.publishMessage({
         name: READINESS_READY_MESSAGE,
         correlationKey: gateKey,
-        variables: { ready: true, detail },
+        // `bind` is the kind-agnostic emit primitive (#274 Gap B): forward whatever the matcher
+        // discovered (e.g. `resolvedArtifact`) into the message so the gate surfaces it as output.
+        // Reserved keys are stripped so a bind can only ADD outputs, never shadow `ready`/`detail`.
+        variables: { ready: true, detail, ...safeBind(bind) },
       });
     },
     log: (msg) => app.log.info(msg),
   });
-  return { ready: result.ready, detail: result.detail };
+  return { ready: result.ready, detail: result.detail, ...safeBind(result.bind) };
 };
 
 export default handler;