@nanobpm/nano-workforce 0.116.0 → 0.117.0

package/.github/workflows/renovate.yml

@@ -0,0 +1,72 @@
+name: Renovate
+
+# Self-hosted Renovate (issue #406). renovate.json declares the policy — auto-merge
+# non-major @nanobpm/* updates once CI is green, majors need a human — but nothing was
+# ever running it, so the config sat dormant and nwf stayed pinned to old @nanobpm/urban.
+# This workflow IS the runner: on a schedule (and on demand) it opens update PRs and, on a
+# later pass once the PR's CI is green, merges the automerge ones itself. We self-host via
+# GitHub Actions rather than the Mend hosted app so the whole capability is in-repo and
+# reproducible, with no external app-install state to drift.
+on:
+  schedule:
+    # Every 3 hours. Renovate needs to run periodically not just to DISCOVER new versions,
+    # but to COME BACK and merge automerge PRs: renovate.json sets platformAutomerge:false
+    # (main is unprotected, so GitHub-native auto-merge is unavailable), which means Renovate
+    # performs the merge itself on a subsequent run once the PR's branch status is green.
+    # A few-hourly cadence keeps that merge latency low without burning Actions minutes.
+    - cron: "0 */3 * * *"
+  # On-demand runs for immediate pickup (e.g. right after a new urban publishes) and for
+  # debugging with a raised log level.
+  workflow_dispatch:
+    inputs:
+      logLevel:
+        description: "Renovate log level"
+        default: "info"
+        type: choice
+        options:
+          - debug
+          - info
+          - warn
+  # Re-run whenever the policy or this runner itself changes, so config edits take effect
+  # without waiting for the next scheduled tick.
+  push:
+    branches: [main]
+    paths:
+      - renovate.json
+      - .github/workflows/renovate.yml
+
+# Renovate authenticates with RENOVATE_TOKEN (a PAT) for all git/PR/merge operations, so the
+# job's GITHUB_TOKEN needs no elevated scope.
+permissions:
+  contents: read
+
+# Never let two Renovate passes run concurrently — overlapping runs race on the same branches
+# and can double-open PRs. cancel-in-progress:false lets an in-flight pass (which may be mid-merge)
+# finish rather than being killed by a newer trigger.
+concurrency:
+  group: renovate
+  cancel-in-progress: false
+
+jobs:
+  renovate:
+    name: renovate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Renovate
+        uses: renovatebot/github-action@v46.2.2
+        with:
+          # A Personal Access Token (repo scope), NOT the default GITHUB_TOKEN. This is required,
+          # not a preference: PRs opened by GITHUB_TOKEN do not trigger `on: pull_request`, so CI
+          # would never run on them and the green-gated automerge in renovate.json could never fire.
+          # A PAT-authored PR triggers CI normally, which is what makes "merge when green" work.
+          token: ${{ secrets.RENOVATE_TOKEN }}
+        env:
+          # Only ever operate on this repo (no org-wide autodiscovery).
+          RENOVATE_REPOSITORIES: ${{ github.repository }}
+          RENOVATE_AUTODISCOVER: "false"
+          # Renovate reads the repo's own renovate.json as its config automatically once it
+          # clones the repo above — no global configurationFile needed.
+          LOG_LEVEL: ${{ inputs.logLevel || 'info' }}

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.117.0](https://github.com/nanobpm/nano-workforce/compare/v0.116.0...v0.117.0) (2026-08-21)
+
+
+### Features
+
+* **delivery-graph:** gated startDeliveryGraph dispatch door (ADR 0005 S5) ([#405](https://github.com/nanobpm/nano-workforce/issues/405)) ([dc7c78e](https://github.com/nanobpm/nano-workforce/commit/dc7c78e03ef1a3a8cfb70e4e51b721a4419c8962)), closes [#380](https://github.com/nanobpm/nano-workforce/issues/380)
+
 # [0.116.0](https://github.com/nanobpm/nano-workforce/compare/v0.115.0...v0.116.0) (2026-08-20)
 
 

package/README.md

@@ -441,6 +441,23 @@ returns `401` without the matching header; unset = open. The source lives in
   model, **generate** the diagram — CI enforces DI freshness), migration policy, and
   the CI gates.
 
+### Dependency updates (Renovate)
+
+First-party `@nanobpm/*` packages (notably `@nanobpm/urban`) are kept current by a
+self-hosted [Renovate](https://docs.renovatebot.com/) runner:
+[`.github/workflows/renovate.yml`](.github/workflows/renovate.yml) runs on a schedule (and
+`workflow_dispatch`), opens update PRs, and — per [`renovate.json`](renovate.json) — merges
+non-major `@nanobpm/*` bumps once CI is green while leaving majors for a human.
+
+It requires a repository secret **`RENOVATE_TOKEN`**: a Personal Access Token with `repo` +
+`workflow` scope (or a fine-grained PAT with *Contents: read & write*, *Pull requests: read &
+write*, *Issues: read & write* — the Dependency Dashboard is a GitHub Issue — and *Workflows:
+read & write*, so Renovate can update files under `.github/workflows`). A PAT is
+mandatory rather than the built-in `GITHUB_TOKEN` because PRs opened by `GITHUB_TOKEN` do not
+trigger `on: pull_request` CI — so the "merge when green" gate would never fire. Set it via
+`gh secret set RENOVATE_TOKEN --repo nanobpm/nano-workforce` (or repo → Settings → Secrets →
+Actions), then trigger a first run from the Actions tab.
+
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE).

package/app/deliveryGraphRun.test.ts

@@ -0,0 +1,249 @@
+// Unit coverage for the S5 dispatch-door aggregate (ADR 0005 Decision 7) — the pure decision helpers
+// (the idempotency key, the approval gate, the parked human-label map, the derived parked-node phase),
+// plus the durable at-most-once launch-claim fence (`claimRunForLaunch`) exercised against the real
+// provisioned SQLite data layer so its actual `status <> 'running'` compare-and-swap SQL is validated,
+// not just modelled. The integration test (operations/startDeliveryGraph.integration.test.ts) proves
+// the COMPOSED behaviour at the edge.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import {
+  buildDeliveryGraphRunRow,
+  buildHumanLabels,
+  claimRunForLaunch,
+  computeRunKey,
+  deriveDeliveryPhase,
+  DELIVERY_PHASE,
+  deliveryGraphRuns,
+  humanTaskElementId,
+  isDeliveryGraphApproved,
+  parkRunFencedAgainstLaunch,
+  parseHumanLabels,
+} from "./deliveryGraphRun.ts";
+import { pollDeliveryGraphPhase } from "./service.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+/** Boot an app purely for its provisioned data layer (migration 058 applied), run `fn`, tear down. */
+async function withData(fn: (data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dgrun-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const claimRow = (status: "awaiting-approval" | "running") =>
+  buildDeliveryGraphRunRow({
+    runKey: "rk",
+    digest: "d",
+    status,
+    sideEffecting: true,
+    nodeCount: 1,
+    humanNodeCount: 0,
+    sideEffectCount: 1,
+    title: "t",
+    phase: status === "running" ? DELIVERY_PHASE.RUNNING : DELIVERY_PHASE.AWAITING_APPROVAL,
+    processKey: null,
+  });
+
+test("claimRunForLaunch: an empty slot is won by INSERT; a second racer that also read empty loses the run_key PK fence", async () => {
+  await withData(async (data) => {
+    const claim = claimRow("running");
+    assertEquals(await claimRunForLaunch(data, false, claim), true); // inserted the claim → this caller launches
+    assertEquals(await claimRunForLaunch(data, false, claim), false); // the row now exists → PK fence, no second launch
+    assertEquals((await deliveryGraphRuns(data).get("rk"))?.status, "running");
+  });
+});
+
+test("claimRunForLaunch: a parked awaiting-approval row is claimed by ONE compare-and-swap — a second approved racer loses the `status <> 'running'` guard, so a graph launches at most once", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    await runs.insert(claimRow("awaiting-approval")); // a prior unapproved POST parked this run
+    const claim = claimRow("running");
+    assertEquals(await claimRunForLaunch(data, true, claim), true); // CAS flips awaiting-approval → running
+    assertEquals(await claimRunForLaunch(data, true, claim), false); // already running → guard blocks the double-launch
+    assertEquals((await runs.get("rk"))?.status, "running");
+  });
+});
+
+test("claimRunForLaunch: a TERMINAL row re-runs — the CAS flips it to running, and a concurrent re-run racer loses the guard", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    await runs.insert({ ...claimRow("running"), status: "failed" }); // a completed/terminal prior run
+    const claim = claimRow("running");
+    assertEquals(await claimRunForLaunch(data, true, claim), true); // re-run: failed <> running → flips
+    assertEquals(await claimRunForLaunch(data, true, claim), false); // now running → no second launch
+    assertEquals((await runs.get("rk"))?.status, "running");
+  });
+});
+
+test("claimRunForLaunch: re-running a terminal row clears the PRIOR instance key in the SAME atomic flip — a claimed `running` row is never visible pointing at a stale process_key", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    // A terminal prior run still carrying its old instance key + parked-node projection.
+    await runs.insert({
+      ...claimRow("running"),
+      status: "failed",
+      process_key: "OLD-PI",
+      process_definition_id: "OLD-DEF",
+      phase: "Parked on human node: publish",
+      phase_node_id: "delivery-human-task__n1",
+    });
+    // The fresh launch claim carries no instance key yet (processKey: null).
+    assertEquals(await claimRunForLaunch(data, true, claimRow("running")), true);
+    const row = await runs.get("rk");
+    assertEquals(row?.status, "running");
+    assertEquals(row?.process_key, null); // stale key cleared atomically with the flip — not left as "OLD-PI"
+    assertEquals(row?.process_definition_id, null);
+    assertEquals(row?.phase_node_id, null);
+    assertEquals(row?.phase, DELIVERY_PHASE.RUNNING);
+  });
+});
+
+// ── pollDeliveryGraphPhase: engine-key coercion ───────────────────────────────
+test("pollDeliveryGraphPhase: a numeric engine processInstanceKey still matches the string process_key, so a COMPLETED instance reconciles to done", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    await runs.insert({ ...claimRow("running"), process_key: "12345" });
+    // The engine can yield a NUMERIC key; the poller compares against the string process_key.
+    const engine = {
+      searchProcessInstances: async () => [{ processInstanceKey: 12345, state: "COMPLETED" }],
+      searchUserTasks: async () => [],
+    };
+    await pollDeliveryGraphPhase(data, engine as never);
+    assertEquals((await runs.get("rk"))?.status, "done");
+  });
+});
+
+// ── parkRunFencedAgainstLaunch: the approval-park write never clobbers a launched claim ────────────
+test("parkRunFencedAgainstLaunch: an approval-park write onto a launched `running` claim is a no-op — the at-most-once dispatch fence survives (no clobber back to awaiting-approval, no nulled process_key)", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    // A concurrent APPROVED submit already launched: the row is `running` with a live instance key.
+    await runs.insert({ ...claimRow("running"), process_key: "PI-1" });
+    // A racing UNAPPROVED submit that read the pre-launch row now tries to (re-)park it. The guarded
+    // write must refuse to overwrite the launched claim — otherwise a later re-submit double-launches.
+    await parkRunFencedAgainstLaunch(data, true, claimRow("awaiting-approval"));
+    const row = await runs.get("rk");
+    assertEquals(row?.status, "running"); // NOT clobbered back to awaiting-approval
+    assertEquals(row?.process_key, "PI-1"); // instance key preserved
+  });
+});
+
+test("parkRunFencedAgainstLaunch: a first park INSERTs the row; a park onto a still-parked row idempotently re-parks it (metadata refreshed, status stays awaiting-approval)", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    // First unapproved submit: no row yet → INSERT.
+    await parkRunFencedAgainstLaunch(data, false, claimRow("awaiting-approval"));
+    assertEquals((await runs.get("rk"))?.status, "awaiting-approval");
+    // A second unapproved submit onto the existing parked row: guarded UPDATE re-parks it (status is
+    // not `running`, so it applies) without duplicating the row.
+    await parkRunFencedAgainstLaunch(data, true, { ...claimRow("awaiting-approval"), digest: "d2" });
+    const row = await runs.get("rk");
+    assertEquals(row?.status, "awaiting-approval");
+    assertEquals(row?.digest, "d2");
+  });
+});
+
+// ── computeRunKey ─────────────────────────────────────────────────────────────
+test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back to the digest", () => {
+  assertEquals(computeRunKey("run-1", "digestX"), "run-1");
+  assertEquals(computeRunKey("  run-2  ", "digestX"), "run-2"); // trimmed
+  assertEquals(computeRunKey("", "digestX"), "digestX");
+  assertEquals(computeRunKey("   ", "digestX"), "digestX");
+  assertEquals(computeRunKey(null, "digestX"), "digestX");
+  assertEquals(computeRunKey(undefined, "digestX"), "digestX");
+});
+
+// ── isDeliveryGraphApproved ───────────────────────────────────────────────────
+test("isDeliveryGraphApproved: a non-side-effecting graph needs no approval", () => {
+  assertEquals(isDeliveryGraphApproved(false, null, "d"), true);
+  assertEquals(isDeliveryGraphApproved(false, "wrong", "d"), true);
+});
+
+test("isDeliveryGraphApproved: a side-effecting graph dispatches ONLY with the matching content token", () => {
+  assertEquals(isDeliveryGraphApproved(true, "d", "d"), true);
+  assertEquals(isDeliveryGraphApproved(true, "  d  ", "d"), true); // trimmed
+  assertEquals(isDeliveryGraphApproved(true, "wrong", "d"), false);
+  assertEquals(isDeliveryGraphApproved(true, null, "d"), false);
+  assertEquals(isDeliveryGraphApproved(true, "", "d"), false);
+});
+
+// ── buildHumanLabels / parseHumanLabels ───────────────────────────────────────
+test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", () => {
+  const graph = {
+    nodes: [
+      { id: "open-b", kind: "agent", agent: { jobType: "j" } },
+      { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish\nsecond line" } },
+      { id: "ack", kind: "human" }, // no prompt → falls back to the node id
+    ],
+    edges: [{ from: "open-b", to: "publish" }, { from: "publish", to: "ack" }],
+  };
+  const compiled = compileDeliveryGraph(graph);
+  assertEquals(compiled.ok, true);
+  if (!compiled.ok) return;
+  const labels = buildHumanLabels(compiled);
+  const publishEl = compiled.resolved.nodes.find((n) => n.id === "publish")?.element ?? "";
+  const ackEl = compiled.resolved.nodes.find((n) => n.id === "ack")?.element ?? "";
+  assertEquals(labels[humanTaskElementId(publishEl)], "run the manual OTP publish"); // first line only
+  assertEquals(labels[humanTaskElementId(ackEl)], "ack"); // fallback to node id
+});
+
+test("parseHumanLabels: round-trips a stored map and tolerates null/blank/corrupt", () => {
+  assertEquals(parseHumanLabels(JSON.stringify({ a: "x" })), { a: "x" });
+  assertEquals(parseHumanLabels(null), {});
+  assertEquals(parseHumanLabels(""), {});
+  assertEquals(parseHumanLabels("  "), {});
+  assertEquals(parseHumanLabels("{not json"), {});
+  assertEquals(parseHumanLabels(JSON.stringify(["a"])), {}); // non-object
+  assertEquals(parseHumanLabels(JSON.stringify({ a: 1, b: "y" })), { b: "y" }); // drops non-string values
+});
+
+// ── deriveDeliveryPhase ───────────────────────────────────────────────────────
+test("deriveDeliveryPhase: COMPLETED → done, TERMINATED → failed", () => {
+  assertEquals(deriveDeliveryPhase("COMPLETED", [], {}), { status: "done", phase: DELIVERY_PHASE.COMPLETED, phase_node_id: null });
+  assertEquals(deriveDeliveryPhase("TERMINATED", [], {}), { status: "failed", phase: DELIVERY_PHASE.FAILED, phase_node_id: null });
+});
+
+test("deriveDeliveryPhase: ACTIVE with an open human task → parked on that node with its label", () => {
+  const el = humanTaskElementId("n2");
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: el }], { [el]: "manual OTP publish" });
+  assertEquals(p.status, "running");
+  assertEquals(p.phase, "Parked on human node: manual OTP publish");
+  assertEquals(p.phase_node_id, el);
+});
+
+test("deriveDeliveryPhase: a parked node with no stored label falls back to the element id", () => {
+  const el = humanTaskElementId("n5");
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: el }], {});
+  assertEquals(p.phase, `Parked on human node: ${el}`);
+  assertEquals(p.phase_node_id, el);
+});
+
+test("deriveDeliveryPhase: ACTIVE with only a non-human open task (or none) → a bare Running", () => {
+  assertEquals(deriveDeliveryPhase("ACTIVE", [], {}), { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null });
+  assertEquals(deriveDeliveryPhase("ACTIVE", [{ elementId: "some-service-task" }], {}), {
+    status: "running",
+    phase: DELIVERY_PHASE.RUNNING,
+    phase_node_id: null,
+  });
+  // A null state (instance not found this pass) is treated as still-running, never a false terminal.
+  assertEquals(deriveDeliveryPhase(null, [], {}), { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null });
+});
+
+test("deriveDeliveryPhase: multiple open human tasks pick the lowest element id deterministically", () => {
+  const a = humanTaskElementId("n1");
+  const b = humanTaskElementId("n3");
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: b }, { elementId: a }], { [a]: "first", [b]: "second" });
+  assertEquals(p.phase, "Parked on human node: first");
+  assertEquals(p.phase_node_id, a);
+});