@nanobpm/nano-workforce 0.117.0 → 0.118.1

package/.github/workflows/invariants.yml

@@ -56,11 +56,14 @@ jobs:
       - name: Check BPMN diagram freshness (layout)
         run: npm run layout:check
 
-      # Generated-artifact freshness (`urban gen --check`): landscape.gen.html, JSON Schemas / OpenAPI,
-      # the processos grammar (ir.gbnf) and friends are `derived == f(sources)` — re-derive over the
-      # merged sources and fail if a committed artifact drifted.
-      - name: Check generated artifacts (urban gen --check)
-        run: npm run gen:check
+      # NOTE: there is deliberately NO `urban gen --check` (`gen:check`) step here. In THIS repo the
+      # only `urban gen` output is `nano-generated/`, which is GIT-IGNORED (since the initial commit)
+      # and regenerated at build time via `pretypecheck`/`pretest` (`=> urban gen`). It is never a
+      # committed artifact, so there is nothing to freshness-check — on a clean checkout `urban gen
+      # --check` only reports it "missing" and fails every run (#423). Because it is regenerated from
+      # the MERGED sources on every typecheck/test, it cannot merge-skew; merged-tree correctness of
+      # the generated code is already covered by the `typecheck + test (Node)` job, which runs
+      # `urban gen` then compiles on the `merge_group`/`push` commit. Do not re-add `gen:check` here.
 
       # Navigation index is another checked-in derived artifact; re-assert it on the merged tree too.
       - name: Check navigation index freshness

package/.github/workflows/release.yml

@@ -1,24 +1,72 @@
 name: Release
 
 on:
-  push:
-    branches: [main]
+  # Gate releases on green CI: run only AFTER the required workflows finish, and
+  # only release when EVERY required check is `success` for that commit (#423).
+  # A release must never ship from a red `main`.
+  workflow_run:
+    workflows: ["CI", "Whole-repo invariants (merge-skew guard)"]
+    types: [completed]
 
 # Prevent overlapping releases from racing on the same branch.
 concurrency:
-  group: release-${{ github.ref }}
+  group: release-main
   cancel-in-progress: false
 
 permissions:
   contents: read
 
 jobs:
+  # Whichever gating workflow finishes LAST (successfully) re-triggers this and
+  # finds every required check green → releases. An earlier trigger, while a
+  # sibling gate is still pending, resolves to `should_release=false` (neutral —
+  # no release, no failure). If any required check fails, no trigger ever sees an
+  # all-green commit, so nothing releases.
+  gate:
+    name: release gate
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.conclusion == 'success'
+    permissions:
+      checks: read
+      contents: read
+    outputs:
+      should_release: ${{ steps.gate.outputs.should_release }}
+    steps:
+      - name: Require every required check green for this commit
+        id: gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          # These must ALL be `success` on the release commit before we ship. Keep
+          # in lock-step with the `main` ruleset's required status checks.
+          required=("typecheck + test (Node)" "whole-repo invariants")
+          # Dedupe to ONE row per check name — the latest run (max .id) — so re-runs
+          # can't leave us reading a stale conclusion. Slurp every page into a
+          # single array with `jq -s` (NOT `gh --slurp`, which gh rejects when
+          # combined with `--jq`) so `group_by` sees every run for the SHA; jq's
+          # `group_by` sorts by the key first, so unsorted input can't split a name.
+          runs="$(gh api "repos/$REPO/commits/$SHA/check-runs?per_page=100" --paginate \
+                    | jq -r -s '[.[].check_runs[]] | group_by(.name) | map(max_by(.id))
+                          | .[] | [.name, (.conclusion // "pending")] | @tsv')"
+          should=true
+          for name in "${required[@]}"; do
+            concl="$(printf '%s\n' "$runs" | awk -F'\t' -v n="$name" '$1==n{print $2}')"
+            echo "gate: '$name' = ${concl:-missing}"
+            [ "${concl:-missing}" = "success" ] || should=false
+          done
+          echo "should_release=$should" >> "$GITHUB_OUTPUT"
+
   release:
     name: semantic-release
+    needs: gate
+    if: needs.gate.outputs.should_release == 'true'
     runs-on: ubuntu-latest
-    # `[skip ci]` on the release commit already prevents a re-trigger, but guard
-    # against loops from any automated release commit as well.
-    if: "!contains(github.event.head_commit.message, '[skip ci]')"
     permissions:
       contents: write # create tags, GitHub Releases, push CHANGELOG/version bump
       issues: write # comment on released issues
@@ -28,6 +76,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.event.workflow_run.head_sha }} # release the exact gated commit
           fetch-depth: 0 # semantic-release needs full history + tags
           persist-credentials: true # let @semantic-release/git push the release commit
 

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.118.1](https://github.com/nanobpm/nano-workforce/compare/v0.118.0...v0.118.1) (2026-08-21)
+
+
+### Bug Fixes
+
+* **ci:** gate releases on green CI and drop perma-red gen:check ([#424](https://github.com/nanobpm/nano-workforce/issues/424)) ([a57746b](https://github.com/nanobpm/nano-workforce/commit/a57746bafa264bf480eb8053cc2e133aa450f8b7))
+* **release:** use jq -s to slurp check-runs; gh --slurp rejects --jq ([#425](https://github.com/nanobpm/nano-workforce/issues/425)) ([d5c3fce](https://github.com/nanobpm/nano-workforce/commit/d5c3fce2652f0b275a5d71d6c8e45e47c403a289))
+
+# [0.118.0](https://github.com/nanobpm/nano-workforce/compare/v0.117.0...v0.118.0) (2026-08-21)
+
+
+### Features
+
+* **delivery-graphs:** human-facing Delivery Graphs UI surface ([#386](https://github.com/nanobpm/nano-workforce/issues/386)) ([#418](https://github.com/nanobpm/nano-workforce/issues/418)) ([3e5877d](https://github.com/nanobpm/nano-workforce/commit/3e5877d2e9f7dc4c7d7934b556e4eefd93685f0f)), closes [#405](https://github.com/nanobpm/nano-workforce/issues/405) [#397](https://github.com/nanobpm/nano-workforce/issues/397) [#374](https://github.com/nanobpm/nano-workforce/issues/374)
+
 # [0.117.0](https://github.com/nanobpm/nano-workforce/compare/v0.116.0...v0.117.0) (2026-08-21)
 
 

package/README.md

@@ -246,6 +246,27 @@ active epic already targets the same custom base. See
 
 ---
 
+## Delivery graphs
+
+Beyond a single PR (review convergence) and an epic (plan → fan-out), Nano Workforce can
+run an **arbitrary, heterogeneous, cross-repo, partly-human delivery graph** — e.g.
+*merge PR #A → un-draft+merge PR #B → a human runs a manual OTP publish → PR #C consumes
+the just-published version*. You author the graph as **JSON over a closed node vocabulary**
+(`agent` | `wait` | `human` | `connector`) — never BPMN or code — whose edges are
+**discovered facts** (`from: "<node>.<fact>"`). A deterministic compiler turns it into an
+engine-native process; a human approves the rendered preview before any side effect runs.
+
+Two doors: a **pure** `POST /app/api/actions/compile-delivery-graph` (validate + preview,
+side-effect-free — hammer it while drafting) and a **gated, idempotent**
+`POST /app/api/actions/start/delivery-graph` (approve → dispatch).
+
+The agent guide served at `GET /app/api/agent` documents the full vocabulary, both
+operation contracts, and a complete worked example — see §9 there, or point your coding
+agent at that URL to author, compile, and submit a graph unaided. See
+[ADR 0005](docs/adr/0005-agent-authored-delivery-graphs.md) for the design and rationale.
+
+---
+
 ## Configuration
 
 | env | default | purpose |

package/app/agentic/families/presence.family.test.ts

@@ -126,6 +126,18 @@ test("registeredWorkers: returns the canonical {instance, capability} supply row
   ]);
 });
 
+test("instanceForConnection: resolves the worker instance owning a connection (H6 write-side seam)", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  store.register({ instance: "w1", connectionId: "c1", identity: "leaf", capability: {} });
+  store.register({ instance: "w2", connectionId: "c2", identity: "leaf", capability: {} });
+  const registry = new PresenceRegistry(store, () => new Set(["c1", "c2"]));
+  assertEquals(registry.instanceForConnection("c1"), "w1");
+  assertEquals(registry.instanceForConnection("c2"), "w2");
+  assertEquals(registry.instanceForConnection("nope"), undefined, "unknown connection → undefined");
+  assertEquals(registry.instanceForConnection(""), undefined, "empty connection → undefined");
+});
+
 test("reconcile: removes rows whose connection the hub has closed, keeps live ones", () => {
   const store = createPresenceStore(memSqlite());
   store.ensureSchema();

package/app/agentic/families/presence.family.ts

@@ -133,6 +133,21 @@ export class PresenceRegistry {
     return this.#store.list().map((row) => ({ instance: row.instance, capability: { ...row.capability } }));
   }
 
+  /**
+   * The worker instance registered on a given connection, or undefined when none is. This is the
+   * connection → instance resolver the relay/correlation slice (H6, #149) uses to attribute a
+   * `produce` frame for a `job:<jobKey>` stream to the presence instance owning the producing
+   * connection — the one fact the relay holds (the connection id) turned into the join key the
+   * correlation registry needs. An empty connection id (or an unknown one) resolves to undefined.
+   */
+  instanceForConnection(connectionId: string): string | undefined {
+    if (connectionId === "") return undefined;
+    for (const row of this.#store.list()) {
+      if (row.connectionId === connectionId) return row.instance;
+    }
+    return undefined;
+  }
+
   /**
    * Eagerly drop presence rows whose connection the hub has already closed (a disconnect the hub's
    * single close listener removed from its in-memory registry). Rows also age out on the presence

package/app/agentic/families/relay.family.test.ts

@@ -19,7 +19,9 @@ import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
 import { type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../../test/log.ts";
+import { CorrelationRegistry, jobStream } from "../correlation.ts";
 import {
+  type CorrelationLink,
   createRelayFamily,
   currentRelayTranscriptService,
   family as relayFamily,
@@ -131,6 +133,25 @@ function mkService(registry: ConnectionRegistry, db: SqliteDb | undefined): {
   return { service, hub };
 }
 
+/** Build a service with the H6 correlation write-side wired (a real registry + a connection→instance map). */
+function mkCorrelatedService(
+  registry: ConnectionRegistry,
+  db: SqliteDb | undefined,
+  correlation: CorrelationRegistry,
+  byConnection: Map<string, string>,
+): { service: RelayTranscriptService; hub: CapturingHub } {
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({
+    hub,
+    registry,
+    db,
+    log: noopLog(),
+    correlation: () => correlation,
+    instanceForConnection: (id) => byConnection.get(id),
+  });
+  return { service, hub };
+}
+
 test("the family exports a valid AgenticFamily named 'relay'", () => {
   assertEquals(relayFamily.name, RELAY_FAMILY_NAME);
   assertEquals(relayFamily.name, "relay");
@@ -262,6 +283,212 @@ test("retention: a disconnected producer auto-completes its ephemeral stream on
   service.teardown();
 });
 
+test("H6 correlation write-side: a produce on job:<k> links instance→[k]; stream completion releases it", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  // The first `produce` for a job-scoped stream links the producing worker instance → jobKey, from
+  // data already crossing the wire (jobKey decoded from the stream id; instance from the connection).
+  hub.handler?.(produce(jobStream("k1"), 1, "chunk"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "instance → [jobKey] is now linked");
+  assertEquals(correlation.resolve("k1")?.stream, jobStream("k1"), "context carries the job-scoped stream");
+  assertEquals(correlation.count(), 1);
+
+  // Job end (stream completion) releases the correlation, so the worker's supply row clears it.
+  service.completeStream(jobStream("k1"));
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "completion releases the job");
+  assertEquals(correlation.resolve("k1"), undefined);
+  assertEquals(correlation.count(), 0);
+  service.teardown();
+});
+
+test("H6 correlation write-side: an unpersisted stream completion releases its job correlation and stops reconcile retrying", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-U"]]);
+  // No DataLayer → the relay runs unpersisted. A direct completeStream (job end, not a disconnect)
+  // must still transition in-memory state: unlink correlation, mark ephemeral completed, drop the
+  // producer — otherwise #reconcile keeps re-completing the stream on every subsequent frame.
+  const { service, hub } = mkCorrelatedService(registry, undefined, correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("kU"), 1, "x"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-U"), ["kU"]);
+
+  service.completeStream(jobStream("kU"));
+  assertEquals(correlation.jobKeysFor("worker-U"), [], "unpersisted completion releases the job");
+  assertEquals(correlation.count(), 0);
+
+  // The producer is still live, but the stream is now completed: a later frame's #reconcile must not
+  // re-link or otherwise resurrect the released correlation.
+  hub.handler?.(grant(0), p.conn);
+  assertEquals(correlation.count(), 0, "completed stream stays released; reconcile does not retry");
+  service.teardown();
+});
+
+test("H6 correlation write-side: a late produce after completion does not resurrect the released correlation", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-R"]]);
+  const { service, hub } = mkCorrelatedService(registry, undefined, correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("kR"), 1, "x"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-R"), ["kR"]);
+
+  // Job end completes the stream and releases the correlation.
+  service.completeStream(jobStream("kR"));
+  assertEquals(correlation.count(), 0, "completion releases the job");
+
+  // A late `produce` frame for the same, still-live producer must NOT re-link/re-own the completed
+  // stream — otherwise it resurrects a jobKey after it was released.
+  hub.handler?.(produce(jobStream("kR"), 1, "late"), p.conn);
+  assertEquals(correlation.count(), 0, "a late produce does not resurrect a completed stream");
+  assertEquals(correlation.jobKeysFor("worker-R"), [], "released jobKey stays released after a late produce");
+  service.teardown();
+});
+
+/**
+ * A {@link CorrelationLink} wrapper that delegates to a real registry but can be flipped to throw on
+ * `link()`/`releaseJob()`, exercising the advisory-resilience contract: `#link`/`#unlink` are
+ * documented "never throws into the frame handler", so a throwing injectable correlation must not
+ * take down the relay frame handler, and the stream must stay retryable.
+ */
+function throwingCorrelation(inner: CorrelationRegistry): {
+  correlation: CorrelationLink;
+  failLink: (on: boolean) => void;
+  failRelease: (on: boolean) => void;
+} {
+  let linkFails = false;
+  let releaseFails = false;
+  return {
+    correlation: {
+      link: (instance, jobKey, context) => {
+        if (linkFails) throw new Error("correlation.link boom");
+        inner.link(instance, jobKey, context);
+      },
+      releaseJob: (jobKey) => {
+        if (releaseFails) throw new Error("correlation.releaseJob boom");
+        inner.releaseJob(jobKey);
+      },
+    },
+    failLink: (on) => {
+      linkFails = on;
+    },
+    failRelease: (on) => {
+      releaseFails = on;
+    },
+  };
+}
+
+test("H6 correlation write-side: a throwing correlation.link() never escapes the frame handler and leaves the stream retryable", () => {
+  const registry = new ConnectionRegistry();
+  const inner = new CorrelationRegistry();
+  const { correlation, failLink } = throwingCorrelation(inner);
+  const byConnection = new Map([["prod", "worker-L"]]);
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({
+    hub,
+    registry,
+    db: undefined,
+    log: noopLog(),
+    correlation: () => correlation,
+    instanceForConnection: (id) => byConnection.get(id),
+  });
+  const p = connect("prod", registry);
+
+  // The first `produce` links — but the injected correlation throws. It must be swallowed (advisory),
+  // so the frame handler does not throw and the stream is left UNLINKED so a later produce retries.
+  failLink(true);
+  hub.handler?.(produce(jobStream("kL"), 1, "x"), p.conn);
+  assertEquals(inner.count(), 0, "a throwing link is swallowed and records no correlation");
+
+  // A later produce (link now succeeds) retries the link — proving the stream was left unlinked.
+  failLink(false);
+  hub.handler?.(produce(jobStream("kL"), 1, "y"), p.conn);
+  assertEquals(inner.jobKeysFor("worker-L"), ["kL"], "the link retries and succeeds on a later frame");
+  assertEquals(inner.count(), 1);
+  service.teardown();
+});
+
+test("H6 correlation write-side: a throwing correlation.releaseJob() never escapes the frame handler; completion still finalizes", () => {
+  const registry = new ConnectionRegistry();
+  const inner = new CorrelationRegistry();
+  const { correlation, failRelease } = throwingCorrelation(inner);
+  const byConnection = new Map([["prod", "worker-X"]]);
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({
+    hub,
+    registry,
+    db: undefined,
+    log: noopLog(),
+    correlation: () => correlation,
+    instanceForConnection: (id) => byConnection.get(id),
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("kX"), 1, "x"), p.conn);
+  assertEquals(inner.jobKeysFor("worker-X"), ["kX"]);
+
+  // A producer disconnect drives #reconcile → #unlink, but releaseJob throws. The advisory contract
+  // is "never throws into the frame handler": the throw must be swallowed so the reconcile pass (and
+  // the completion it drives) do not bubble out and take down unrelated streams' relay processing.
+  failRelease(true);
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn); // must NOT throw despite releaseJob throwing
+
+  // The stream still finalizes (terminal) so #reconcile does not thrash it every frame, and a later
+  // frame's reconcile is a clean no-op rather than a repeated crash.
+  hub.handler?.(produce(jobStream("kX"), 2, "late"), p.conn);
+  assertEquals(
+    inner.jobKeysFor("worker-X"),
+    ["kX"],
+    "a swallowed release leaves the correlation held (linked), never a crash",
+  );
+  service.teardown();
+});
+
+test("H6 correlation write-side: a producer disconnect releases its job correlation even unpersisted", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-B"]]);
+  // No DataLayer → the relay runs unpersisted; correlation release must still fire (store-independent).
+  const { service, hub } = mkCorrelatedService(registry, undefined, correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k2"), 1, "x"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-B"), ["k2"]);
+
+  // Producer drops; a subsequent frame from any live connection reconciles the dead producer.
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  assertEquals(correlation.jobKeysFor("worker-B"), [], "disconnect releases the job");
+  assertEquals(correlation.count(), 0);
+  service.teardown();
+});
+
+test("H6 correlation write-side: non-job streams are never linked; a link retries until the instance resolves", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map<string, string>();
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  // A plain (non-`job:`) stream carries no jobKey → never correlated.
+  hub.handler?.(produce("plain-stream", 1, "x"), p.conn);
+  assertEquals(correlation.count(), 0, "non-job streams are not linked");
+
+  // A job stream whose producer's presence instance is not yet known does not link — but a later
+  // frame (after the register lands) retries and links, closing the register/produce race.
+  hub.handler?.(produce(jobStream("k3"), 1, "a"), p.conn);
+  assertEquals(correlation.count(), 0, "no presence instance yet → not linked");
+  byConnection.set("prod", "worker-C");
+  hub.handler?.(produce(jobStream("k3"), 1, "b"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-C"), ["k3"], "retried link succeeds once the instance resolves");
+  service.teardown();
+});
+
 test("retention: a long-lived stream is checkpointed + reattachable and never auto-completed", () => {
   const registry = new ConnectionRegistry();
   const db = memoryDb();