@nanobpm/nano-workforce 0.71.0 → 0.72.0

package/.github/workflows/ci.yml

@@ -54,6 +54,13 @@ jobs:
       - name: Check migration prefixes (no collisions)
         run: npm run check:migrations
 
+      # Contract-registry gate (issue #227): every config-family env key must be declared in the ONE
+      # typed schema (app/contracts.ts), no retired synonym (e.g. NANO_PR_BASE_URL, #223) may reappear
+      # in code, and the registry must reconcile against itself (no synonyms/contradictions). This is
+      # what makes a duplicate/synonymous contract a build failure instead of a silent runtime fallback.
+      - name: Check contract registry (no synonyms / undeclared keys)
+        run: npm run check:contracts
+
       # Runs the full *.test.ts suite under Node's built-in test runner (node:test), which strips
       # TypeScript types on the fly (Node >= 22.6) — no build step.
       - name: Test (Node)

package/AGENTS.md

@@ -59,6 +59,29 @@ Before starting planned work, check for an existing issue or PR. If one is
 already in progress, stop and flag it with a link. Otherwise create and claim an
 issue before writing code.
 
+## Shared contracts: one registry, one typed env schema (issue #227, ADR 0004)
+
+Parallel/sliced work keeps producing **two divergent representations of one contract** — an env-key
+synonym (the canonical `NANO_WORKFORCE_BASE_URL` vs. retired names like `NANO_PR_PUBLIC_BASE_URL`/its
+phantom `NANO_PR_BASE_URL` fallback, #226/#223), a wire-shape drift (nano-ide #234), two type names
+for one shape — each authored against a mock, discovered only at runtime. Prevent it at authoring
+time:
+
+- **Consult the durable registry FIRST — `app/contracts.ts`.** Before introducing a new **env/config
+  key**, **wire-frame shape**, **shared exported type**, or **capability-URL scheme**, check the
+  registry. If a semantically-equivalent contract exists, **reuse it**; otherwise declare it there
+  (owner + semantics per entry).
+- **Env keys go through the ONE typed schema** (`ENV_CONTRACTS` + `readEnv`/`readEnvOr`). Every
+  config-family key (`NANO_*`, `NANOBPMN_*`, `CAMUNDA_*`, `PR_REVIEW_*`) MUST be declared; a synonym or
+  an undeclared key is a **CI failure** (`npm run check:contracts`). A **retired synonym** (e.g.
+  `NANO_PR_BASE_URL`) reappearing in code is a hard failure — never reintroduce a phantom fallback.
+- **Signal in-flight on the blackboard.** When introducing/consuming a cross-cutting contract, POST a
+  `kind:"contract"` entry (`dedupe_key` as `<category>:<name>`, e.g. `env:NANO_X`) so siblings see it
+  before they reinvent it. The write-time guard reports near-duplicate-declaration `contractConflicts`.
+- **Reconcile.** `npm run reconcile:contracts` reads the whole blackboard + registry and reports
+  synonyms / contradictions / mock-vs-real skew (advisory). `npm run check:contracts` is the hard,
+  registry-only gate (also in CI).
+
 ## BPMN: author the semantic model, generate the diagram
 
 **The `.bpmn` files under `resources/processes/` are hand-authored semantic
@@ -226,11 +249,12 @@ npm run check                                         # urban check (manifest va
 npm run layout:check                                  # BPMN diagram freshness (no drift)
 npm run check:prompts                                 # agent-prompt template resolution
 npm run check:migrations                              # migration prefixes (no collisions)
+npm run check:contracts                               # contract registry (no synonyms / undeclared env keys)
 npm test                                              # unit tests (node --test)
 ```
 
 CI (`.github/workflows/ci.yml`) gates lint, typecheck, `urban check`, `layout:check`,
-the prompt check, the migration-prefix check, and the Node test suite. Run `npm run layout <file.bpmn>` after
+the prompt check, the migration-prefix check, the contract-registry check, and the Node test suite. Run `npm run layout <file.bpmn>` after
 any BPMN flow change and commit the regenerated diagram — the `layout:check`
 gate fails the build otherwise.
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.72.0](https://github.com/nanobpm/nano-workforce/compare/v0.71.0...v0.72.0) (2026-08-15)
+
+
+### Features
+
+* coordinate shared contracts via a durable registry + blackboard signal + reconciliation pass ([#229](https://github.com/nanobpm/nano-workforce/issues/229)) ([2c250b5](https://github.com/nanobpm/nano-workforce/commit/2c250b51596e1a062c4e09c6aef638010abea793)), closes [#223](https://github.com/nanobpm/nano-workforce/issues/223) [#234](https://github.com/nanobpm/nano-workforce/issues/234) [214/#217](https://github.com/nanobpm/nano-workforce/issues/217) [#223](https://github.com/nanobpm/nano-workforce/issues/223) [#227](https://github.com/nanobpm/nano-workforce/issues/227) [#227](https://github.com/nanobpm/nano-workforce/issues/227)
+
 # [0.71.0](https://github.com/nanobpm/nano-workforce/compare/v0.70.2...v0.71.0) (2026-08-15)
 
 

package/app/blackboard.test.ts

@@ -8,20 +8,49 @@ import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import { memBlackboardData } from "../test/blackboardDb.ts";
 import {
+  APP_BLACKBOARD_KINDS,
   appendEntry,
   blackboardUrl,
+  detectContractDeclarationConflicts,
   detectFileClaimConflicts,
   isUniqueViolation,
   mintBlackboardToken,
+  normalizeAppKind,
   normalizeKind,
+  parseContractRef,
   planKeyForToken,
   planKeyForTokenSync,
   publicBaseUrl,
   readBlackboard,
   readBlackboardPage,
   renderCoordinationBrief,
+  toSafeRowId,
 } from "./blackboard.ts";
 
+test("toSafeRowId: passes through safe numbers/bigints, throws above MAX_SAFE_INTEGER (PR #229)", () => {
+  assertEquals(toSafeRowId(42), 42);
+  assertEquals(toSafeRowId(0), 0);
+  // A bigint within the safe range narrows to an identical number.
+  assertEquals(toSafeRowId(9007199254740991n), Number.MAX_SAFE_INTEGER);
+  // Beyond 2^53 a Number(...) coercion would silently lose precision as a `since` cursor — fail loud.
+  let threw = false;
+  try {
+    toSafeRowId(9007199254740993n);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "a bigint id above MAX_SAFE_INTEGER must throw, not silently lose precision");
+  // The number branch guards the same boundary: a driver-returned non-safe-integer must also fail
+  // loud rather than pass through as a lossy cursor (#229).
+  let threwNum = false;
+  try {
+    toSafeRowId(Number.MAX_SAFE_INTEGER + 2);
+  } catch {
+    threwNum = true;
+  }
+  assert(threwNum, "a number id that is not a safe integer must throw, not silently pass through");
+});
+
 test("mintBlackboardToken: URL-safe, unguessable, unique", () => {
   const a = mintBlackboardToken();
   const b = mintBlackboardToken();
@@ -36,7 +65,7 @@ test("publicBaseUrl: honours the env override and trims a trailing slash", () =>
 });
 
 test("publicBaseUrl: a blank/whitespace override falls back instead of yielding a bad URL", () => {
-  // Explicit override args bypass the `process.env.NANO_WORKFORCE_BASE_URL` default, so this test
+  // Explicit override args bypass the `NANO_WORKFORCE_BASE_URL` default, so this test
   // needs no env manipulation — the env-read path is covered by the dedicated test below.
   assertEquals(publicBaseUrl(""), "http://localhost:3000");
   assertEquals(publicBaseUrl("   "), "http://localhost:3000");
@@ -71,6 +100,30 @@ test("normalizeKind: valid passes through, anything else becomes note", () => {
   assertEquals(normalizeKind(undefined), "note");
 });
 
+test("normalizeAppKind: passes contract through (the store's own normaliser would coerce it to note)", () => {
+  assertEquals(normalizeAppKind("contract"), "contract");
+  assertEquals(normalizeAppKind("file-claim"), "file-claim");
+  assertEquals(normalizeAppKind("bogus"), "note");
+  assert(APP_BLACKBOARD_KINDS.includes("contract"), "contract is an app-recognised kind");
+  assert(APP_BLACKBOARD_KINDS.includes("note"), "app kinds are a superset of the store's kinds");
+});
+
+test("parseContractRef: parses the <category>:<name> dedupe_key convention", () => {
+  assertEquals(parseContractRef("env:NANO_X"), { category: "env", name: "NANO_X" });
+  assertEquals(parseContractRef("type:BlackboardEntry"), { category: "type", name: "BlackboardEntry" });
+  assertEquals(parseContractRef("bogus:X"), undefined);
+  assertEquals(parseContractRef("nocolon"), undefined);
+  assertEquals(parseContractRef(undefined), undefined);
+});
+
+test("detectContractDeclarationConflicts: flags a retired synonym; clean for a genuinely new key", () => {
+  const rejected = detectContractDeclarationConflicts({ dedupe_key: "env:NANO_PR_BASE_URL", body: "base url" });
+  assertEquals(rejected[0]?.kind, "rejected-synonym");
+  assertEquals(detectContractDeclarationConflicts({ dedupe_key: "env:NANO_TOTALLY_NEW", body: "an unrelated brand new thing about caching" }), []);
+  // No convention → nothing to reconcile against.
+  assertEquals(detectContractDeclarationConflicts({ body: "freeform" }), []);
+});
+
 test("renderCoordinationBrief: leads with a separator and teaches the protocol + URL", () => {
   const url = "https://h/app/api/hooks/blackboard?token=abc";
   const brief = renderCoordinationBrief(url);
@@ -89,6 +142,13 @@ test("renderCoordinationBrief: leads with a separator and teaches the protocol +
   // Learnings: teaches reading prior gotchas and posting a reusable `learning`.
   assertStringIncludes(brief, "learning");
   assertStringIncludes(brief, "Share what you learn");
+  // Contracts (#227): teaches consulting the registry + blackboard and posting a `contract` entry.
+  assertStringIncludes(brief, "contract");
+  assertStringIncludes(brief, "app/contracts.ts");
+  assertStringIncludes(brief, "kind\":\"contract\"");
+  // The contract-POST write-time guard surfaces overlaps via `contractConflicts` (a `file-claim`
+  // POST uses the separate `conflicts` array); the brief must name the right field.
+  assertStringIncludes(brief, "contractConflicts");
 });
 
 test("planKeyForToken: resolves a token to its plan, undefined otherwise (async + sync agree)", async () => {
@@ -166,6 +226,20 @@ test("appendEntry: a blank body is rejected", async () => {
   assert(threw, "blank body must throw");
 });
 
+test("appendEntry: a contract append patches the kind even when it collapses onto an existing row (deterministic round-trip)", async () => {
+  const { data } = memBlackboardData();
+  // A prior append under this dedupe_key stored kind `note` (the store's default for an unknown kind).
+  const first = await appendEntry(data, "p", { author_task: "t", body: "seed", kind: "note", dedupe_key: "env:NANO_X" });
+  assertEquals(first.inserted, true);
+  // A later `contract` append with the SAME dedupe_key is a no-op insert (`inserted: false`) — but it
+  // must still leave the row readable as `contract`, not lingering as `note`.
+  const again = await appendEntry(data, "p", { author_task: "t", body: "seed", kind: "contract", dedupe_key: "env:NANO_X" });
+  assertEquals(again.inserted, false, "same dedupe_key is a no-op insert");
+  const entries = await readBlackboard(data, "p");
+  assertEquals(entries.length, 1);
+  assertEquals(entries[0].kind, "contract", "the contract kind is patched deterministically regardless of res.inserted");
+});
+
 test("readBlackboard: since returns only newer entries (incremental poll)", async () => {
   const { data } = memBlackboardData();
   await appendEntry(data, "p", { body: "one" });

package/app/blackboard.ts

@@ -28,8 +28,20 @@
 // handle (`data.source().db`) — the same physical database the record gateway (`data.table`) uses,
 // so the HTTP hook and the agentic channel share one connection and one table.
 
-import { BlackboardStore, type SqliteDb } from "@nanobpm/agentic/blackboard";
+import {
+  BLACKBOARD_TABLE,
+  BlackboardStore,
+  normalizeKind as normalizeStoreKind,
+  type SqliteDb,
+  BLACKBOARD_KINDS as STORE_KINDS,
+} from "@nanobpm/agentic/blackboard";
 import type { DataLayer } from "@nanobpm/urban";
+import {
+  type ContractCategory,
+  type DeclarationConflict,
+  detectDeclarationConflicts,
+  readEnvOr,
+} from "./contracts.ts";
 
 // Re-export the storage vocabulary from the shared package so there is ONE canonical definition of
 // the kinds, the kind-normaliser, and the unique-violation predicate — the app never keeps a
@@ -37,6 +49,23 @@ import type { DataLayer } from "@nanobpm/urban";
 export type { BlackboardKind } from "@nanobpm/agentic/blackboard";
 export { BLACKBOARD_KINDS, isUniqueViolation, normalizeKind } from "@nanobpm/agentic/blackboard";
 
+
+/** The app-recognised blackboard kinds: the shared store's kinds PLUS `contract` — the live,
+ * in-flight coordination signal introduced by issue #227 ("I am introducing / consuming contract
+ * X"). It is DERIVED from the store's set (spread, never re-typed), so the two never drift; `contract`
+ * is the only app-local addition, until the shared package promotes it. The durable source of truth
+ * for a contract is the registry (`app/contracts.ts`); this kind is the real-time heads-up that lets
+ * siblings in a wave see a new contract before they independently invent a synonym. */
+export const APP_BLACKBOARD_KINDS = [...STORE_KINDS, "contract"] as const;
+export type AppBlackboardKind = (typeof APP_BLACKBOARD_KINDS)[number];
+
+/** The app-side kind normaliser: passes `contract` through (the store's own normaliser would coerce
+ * it to `note`), and defers to the shared normaliser for every other value so unknown kinds still
+ * default to `note`. ONE place decides the app's kind vocabulary. */
+export function normalizeAppKind(kind: unknown): AppBlackboardKind {
+  return kind === "contract" ? "contract" : normalizeStoreKind(kind);
+}
+
 /** The parsed, agent-facing view of an entry (files decoded to an array). Snake_case is the
  * app/HTTP-hook boundary contract every existing caller and agent already consumes. */
 export interface BlackboardEntry {
@@ -69,15 +98,17 @@ export function mintBlackboardToken(): string {
 }
 
 /** The externally-reachable base URL agents use to reach this app. Must resolve from WHEREVER the
- * agent runs (co-located or remote/containerised), so it is configured, never hardcoded. */
-export function publicBaseUrl(env: string | undefined = process.env.NANO_WORKFORCE_BASE_URL): string {
-  // Skip the override if it is unset OR blank/whitespace, so an explicitly-set-but-empty
-  // NANO_WORKFORCE_BASE_URL can't yield a malformed capability URL.
-  const base =
-    [env, "http://localhost:3000"]
-      .map((v) => v?.trim())
-      .find((v): v is string => Boolean(v)) ?? "http://localhost:3000";
-  return base.replace(/\/+$/, "");
+ * agent runs (co-located or remote/containerised), so it is configured, never hardcoded. Read
+ * through the ONE typed env schema ({@link readEnvOr} over `NANO_WORKFORCE_BASE_URL`) — there is no
+ * second name for this value. The retired synonyms `NANO_PR_PUBLIC_BASE_URL` (coalesced into the
+ * canonical name in #226) and the phantom `NANO_PR_BASE_URL` fallback (introduced in #53, cleaned
+ * up per #223) are recorded as rejected synonyms in `app/contracts.ts`, so neither can be
+ * reintroduced as a silent runtime fallback. */
+export function publicBaseUrl(base: string = readEnvOr("NANO_WORKFORCE_BASE_URL")): string {
+  // Skip a blank/whitespace value so an explicitly-set-but-empty NANO_WORKFORCE_BASE_URL can't yield
+  // a malformed capability URL; fall back to the schema-declared default.
+  const resolved = base.trim() || readEnvOr("NANO_WORKFORCE_BASE_URL");
+  return resolved.replace(/\/+$/, "");
 }
 
 /** The capability URL for a plan's blackboard: the token rides the query string, so the agent can
@@ -122,7 +153,9 @@ from re-discovering it the hard way.
 
 \`kind\` is one of: \`file-claim\` (you now edit a file outside your original slice),
 \`constraint-change\` (you discovered a constraint that changes another task's direction),
-\`scope-change\` (your contract/scope shifted), \`learning\` (see below), or \`note\`. Set
+\`scope-change\` (your contract/scope shifted), \`contract\` (you are introducing/consuming a shared
+env key / wire shape / type / capability-URL scheme — see below), \`learning\` (see below), or
+\`note\`. Set
 \`author_task\` to your task id. If a retry might make you re-POST the same fact, include a stable
 \`"dedupe_key"\` so it collapses to one entry.
 
@@ -139,6 +172,29 @@ one entry across retries and siblings:
 
 A \`learning\` is advisory and never blocks anyone; it is knowledge for the fleet, not a claim on a file.
 
+**Coordinate SHARED CONTRACTS before you invent one (issue #227).** A *contract* is anything two
+slices must agree on but that each of you could author independently against a mock: an **env/config
+key**, a **wire-frame shape** (a message/relay payload), a **shared exported type/interface name**, or
+a **capability-URL scheme**. Divergent copies of one contract (an env-key synonym, a producer/hub
+wire-shape drift) are only discovered at runtime, after both sides are green against their own mock.
+Prevent it:
+
+- **Consult the durable contract registry FIRST** (\`app/contracts.ts\` — env keys go through the ONE
+  typed \`ENV_CONTRACTS\` schema; wire/type/capability-URL contracts are declared alongside). If a
+  semantically-equivalent contract already exists, **reuse it** (import the shared type, read the
+  existing env key) — never author a synonym. A retired synonym (e.g. \`NANO_PR_BASE_URL\`) is a hard
+  CI failure, not a fallback.
+- **Consult the blackboard \`contract\` entries** below for what siblings are introducing *right now*.
+- **When you introduce OR consume a cross-cutting contract, POST a \`contract\` entry** so siblings see
+  it before they reinvent it, and add the durable declaration to \`app/contracts.ts\`:
+
+      curl -s -X POST "${url}" -H 'content-type: application/json' \\
+        -d '{"author_task":"<your-task-id>","kind":"contract","dedupe_key":"env:NANO_X","body":"introducing env key NANO_X — <owner> — <semantics + default>"}'
+
+The write-time guard reports a \`contractConflicts\` array on a \`contract\` POST when your declaration looks
+like a synonym of, or contradicts, an existing contract — reconcile before proceeding. (A \`file-claim\`
+POST reports its own overlaps in a separate \`conflicts\` array — see below.)
+
 **Stay in sync while you work (this matters most while siblings run in parallel).** The GET
 response includes a \`"cursor"\`. Re-read incrementally — before you start each new file, and at
 least every few minutes on long tasks — passing the last cursor back as \`since\` so you fetch only
@@ -280,15 +336,46 @@ export async function detectFileClaimConflicts(
     }));
 }
 
+/** Narrow a SQLite row id (`number | bigint`) to a JS number, failing loudly if it exceeds the
+ * safe-integer range. Blackboard rowids are monotonic and stay far below 2^53 in practice, but the
+ * driver types the id as `number | bigint`; coercing a huge bigint via `Number(...)` would silently
+ * lose precision and corrupt the id where it is used as a `since` cursor. We narrow ONCE here so the
+ * union never escapes `appendEntry` and no caller re-coerces. Both branches guard the safe-integer
+ * boundary: a `bigint` above `MAX_SAFE_INTEGER`, or a driver-returned `number` that is somehow not a
+ * safe integer, both throw rather than silently yield a lossy cursor. */
+export function toSafeRowId(id: number | bigint): number {
+  if (typeof id === "bigint") {
+    if (id > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error(
+        `blackboard row id ${id} exceeds Number.MAX_SAFE_INTEGER; unsafe to narrow to a JS number cursor`,
+      );
+    }
+    return Number(id);
+  }
+  if (!Number.isSafeInteger(id)) {
+    throw new Error(
+      `blackboard row id ${id} is not a safe integer; unsafe to use as a JS number cursor`,
+    );
+  }
+  return id;
+}
+
 /** Append an entry, idempotently. A blank `body` is rejected. When a `dedupe_key` is supplied and
  * an entry already exists for it on this plan, the write is a no-op and the existing id is
- * returned (`inserted: false`) — so an engine job retry re-POSTing the same fact never duplicates. */
+ * returned (`inserted: false`) — so an engine job retry re-POSTing the same fact never duplicates.
+ *
+ * The `contract` kind (issue #227) is the app-local addition: the shared store's normaliser would
+ * coerce it to `note`, so after the store's insert (which owns all the idempotency/dedupe semantics)
+ * we patch the ONE row's kind column back to `contract`. We reuse the store's insert rather than
+ * hand-writing a parallel one, so there is no drift in the append logic — only the kind vocabulary is
+ * app-extended. */
 export async function appendEntry(
   data: DataLayer,
   planKey: string,
   input: BlackboardInput,
-): Promise<{ inserted: boolean; id: number | bigint }> {
-  return storeFor(data).append(planKey, {
+): Promise<{ inserted: boolean; id: number }> {
+  const appKind = normalizeAppKind(input.kind);
+  const res = storeFor(data).append(planKey, {
     authorTask: input.author_task,
     kind: input.kind,
     files: input.files,
@@ -296,4 +383,47 @@ export async function appendEntry(
     wave: input.wave,
     dedupeKey: input.dedupe_key,
   });
+  if (appKind === "contract") {
+    // The store defaulted `kind` to `note` (its normaliser doesn't know `contract`); restore it on
+    // the resolved row. Patch on EVERY `contract` append — not only when `res.inserted` — so an
+    // idempotent retry (or a race) that resolves to an existing id (`inserted: false`), or a row
+    // first inserted under a different kind for the same `dedupe_key`, still reads back as `contract`
+    // rather than lingering as `note`. The UPDATE is idempotent on an already-`contract` row.
+    // Bind `res.id` as-is (it is `number | bigint`) — coercing a bigint id via `Number(...)` could
+    // lose precision above `Number.MAX_SAFE_INTEGER` and patch the wrong row; SQLite binds bigint natively.
+    data.source().db.run(`UPDATE ${BLACKBOARD_TABLE} SET kind = 'contract' WHERE id = ?`, [res.id]);
+  }
+  return { inserted: res.inserted, id: toSafeRowId(res.id) };
+}
+
+/** Parse a `contract` entry's `dedupe_key` convention `<category>:<name>` (e.g. `env:NANO_X`,
+ * `type:BlackboardEntry`). Returns the category+name when it parses, else undefined. */
+export function parseContractRef(
+  dedupeKey: string | undefined,
+): { category: ContractCategory; name: string } | undefined {
+  if (!dedupeKey) return undefined;
+  const idx = dedupeKey.indexOf(":");
+  if (idx <= 0) return undefined;
+  const category = dedupeKey.slice(0, idx).trim();
+  const name = dedupeKey.slice(idx + 1).trim();
+  if (!name) return undefined;
+  if (category === "env" || category === "wire" || category === "type" || category === "capability-url") {
+    return { category, name };
+  }
+  return undefined;
+}
+
+/** Write-time near-duplicate DECLARATION detection for a `contract` POST (issue #227, AC4). Extends
+ * the store's conflict reporting (`file-claim`) to the declaration surface: given a proposed contract
+ * (its `<category>:<name>` from `dedupe_key`, its semantics from `body`), report any registry entry
+ * that is a synonym (same thing, different name), a contradiction (same name, different meaning), or a
+ * rejected synonym (a retired name). Advisory — surfaced to the writer, never a lock. Returns `[]`
+ * when the entry doesn't carry the `<category>:<name>` convention (nothing to reconcile against). */
+export function detectContractDeclarationConflicts(opts: {
+  dedupe_key?: string;
+  body: string;
+}): DeclarationConflict[] {
+  const ref = parseContractRef(opts.dedupe_key);
+  if (!ref) return [];
+  return detectDeclarationConflicts({ category: ref.category, name: ref.name, semantics: opts.body });
 }

package/app/contractReconcile.test.ts

@@ -0,0 +1,94 @@
+// Unit tests for the contract reconciliation pass (issue #227, ADR 0004).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { Contract } from "./contracts.ts";
+import {
+  formatReconciliationReport,
+  reconcileContracts,
+  reconcileRegistry,
+} from "./contractReconcile.ts";
+
+test("reconcileRegistry: the committed registry reconciles clean (no synonyms/contradictions)", () => {
+  assertEquals(reconcileRegistry(), []);
+});
+
+test("reconcileRegistry: two same-category entries with equivalent semantics are flagged as synonyms", () => {
+  const contracts: Contract[] = [
+    { category: "env", name: "NANO_A_URL", owner: "a", semantics: "externally reachable base url agents use to reach this app" },
+    { category: "env", name: "NANO_B_URL", owner: "b", semantics: "externally reachable base url agents use to reach this app" },
+  ];
+  const findings = reconcileRegistry(contracts);
+  assertEquals(findings.length, 1, "one symmetric synonym pair, reported once");
+  assertEquals(findings[0].kind, "synonym");
+  assertEquals(findings[0].names.sort(), ["NANO_A_URL", "NANO_B_URL"]);
+});
+
+test("reconcileContracts: an in-flight signal for a contract not in the registry is mock-vs-real skew", () => {
+  const report = reconcileContracts([
+    { authorTask: "task-x", category: "env", name: "NANO_GHOST", body: "some new key nobody landed" },
+  ]);
+  assert(
+    report.findings.some((f) => f.kind === "mock-vs-real-skew" && f.names.includes("NANO_GHOST")),
+    "a signalled contract absent from the durable registry must be flagged as skew",
+  );
+});
+
+test("reconcileContracts: a signal reintroducing a rejected synonym is flagged", () => {
+  const report = reconcileContracts([
+    { authorTask: "task-y", category: "env", name: "NANO_PR_BASE_URL", body: "the base url" },
+  ]);
+  assert(
+    report.findings.some((f) => f.kind === "rejected-synonym"),
+    "a rejected synonym signalled on the blackboard must be reconciled",
+  );
+  // A rejected synonym must NOT also be reported as mock-vs-real skew: the right action is to reuse
+  // the canonical name, not to "land" the retired name in the registry — a skew finding there is
+  // noise that contradicts the rejected-synonym advice.
+  assertEquals(
+    report.findings.filter((f) => f.kind === "mock-vs-real-skew"),
+    [],
+    "a rejected synonym must not double-report as skew",
+  );
+});
+
+test("reconcileContracts: a synonym signal (different name, same thing) is flagged synonym, not skew", () => {
+  const report = reconcileContracts([
+    {
+      authorTask: "task-w",
+      category: "env",
+      name: "NANO_APP_PUBLIC_URL",
+      body: "Externally-reachable base URL agents use to reach this app; drives every plan's blackboard capability URL.",
+    },
+  ]);
+  assert(
+    report.findings.some((f) => f.kind === "synonym"),
+    "a differently-named duplicate of an existing contract must be flagged as a synonym",
+  );
+  assertEquals(
+    report.findings.filter((f) => f.kind === "mock-vs-real-skew"),
+    [],
+    "a synonym must not double-report as skew — reuse the canonical, don't land the new name",
+  );
+});
+
+test("reconcileContracts: a signal for an existing registry contract, reused correctly, is clean of skew", () => {
+  const report = reconcileContracts([
+    {
+      authorTask: "task-z",
+      category: "env",
+      name: "NANO_WORKFORCE_BASE_URL",
+      body: "Externally-reachable base URL agents use to reach this app; drives every plan's blackboard capability URL.",
+    },
+  ]);
+  assertEquals(report.findings.filter((f) => f.kind === "mock-vs-real-skew"), []);
+});
+
+test("formatReconciliationReport: clean report reads clean, dirty report lists findings", () => {
+  assert(formatReconciliationReport({ findings: [], clean: true }).includes("no synonyms"));
+  const dirty = formatReconciliationReport({
+    findings: [{ kind: "synonym", detail: "x looks like y", names: ["x", "y"], source: "registry" }],
+    clean: false,
+  });
+  assert(dirty.includes("1 issue"));
+  assert(dirty.includes("[synonym]"));
+});

package/app/contractReconcile.ts

@@ -0,0 +1,134 @@
+// nano-workforce — the contract reconciliation pass (issue #227, ADR 0004).
+//
+// A sibling to the L2 epic retro / cross-epic pass. Where the retro distils *learnings*, this pass
+// reconciles *contracts*: it reads the whole blackboard (every `contract` signal siblings posted)
+// alongside the durable contract registry (`app/contracts.ts`) and flags —
+//
+//   - SYNONYMS: two declarations of one thing under different names (the #223 env-key failure mode),
+//   - CONTRADICTIONS: one name declared with two different meanings/owners,
+//   - MOCK-vs-REAL SKEW: a contract signalled in-flight on the blackboard that never landed in the
+//     durable registry (a live signal with no durable truth — the pair the issue says must both hold).
+//
+// The pass is PURE and advisory: it returns a report. The caller (a reconciliation agent, or the CI
+// check `scripts/check-contracts.ts` for the registry-only static half) decides whether to surface an
+// escalation / merge candidate. Nothing here mutates the blackboard or the registry.
+
+import {
+  allContracts,
+  type Contract,
+  type ContractCategory,
+  detectDeclarationConflicts,
+  rejectedEnvSynonyms,
+} from "./contracts.ts";
+
+/** An in-flight contract signal, as posted to the blackboard `contract` kind. `category`/`name` come
+ * from the `<category>:<name>` `dedupe_key` convention; `body` carries the human semantics. */
+export interface ContractSignal {
+  readonly authorTask: string;
+  readonly category?: ContractCategory;
+  readonly name?: string;
+  readonly body: string;
+}
+
+/** One reconciliation finding. */
+export interface ReconciliationFinding {
+  readonly kind: "synonym" | "contradiction" | "rejected-synonym" | "mock-vs-real-skew";
+  readonly detail: string;
+  /** The contract name(s) the finding concerns. */
+  readonly names: string[];
+  /** Whoever raised the divergence, when known (a blackboard author, or "registry" for a static one). */
+  readonly source: string;
+}
+
+export interface ReconciliationReport {
+  readonly findings: ReconciliationFinding[];
+  /** Convenience: true when there is nothing to reconcile (findings is empty). */
+  readonly clean: boolean;
+}
+
+/** Reconcile the durable registry against itself (the static half): synonyms among registry entries
+ * of one category, and any rejected synonym that somehow re-entered the registry. Used both by the
+ * full pass and by the CI check (which runs with no blackboard). */
+export function reconcileRegistry(contracts: Contract[] = allContracts()): ReconciliationFinding[] {
+  const findings: ReconciliationFinding[] = [];
+  const rejected = rejectedEnvSynonyms();
+  for (const c of contracts) {
+    if (c.category === "env" && rejected.has(c.name)) {
+      findings.push({
+        kind: "rejected-synonym",
+        detail: `Registry entry '${c.name}' is a retired synonym of '${rejected.get(c.name)}' — remove it.`,
+        names: [c.name, rejected.get(c.name) ?? ""],
+        source: "registry",
+      });
+    }
+  }
+  // Pairwise synonym detection within the registry: reuse the declaration detector so the definition
+  // of "synonym" lives in ONE place (app/contracts.ts). Compare each entry against the others; dedupe
+  // symmetric pairs by only reporting name < otherName.
+  for (const c of contracts) {
+    const others = contracts.filter((o) => o.name !== c.name);
+    for (const conflict of detectDeclarationConflicts({ category: c.category, name: c.name, semantics: c.semantics }, others)) {
+      if (conflict.kind !== "synonym") continue;
+      if (c.name >= conflict.existingName) continue; // report each pair once
+      findings.push({
+        kind: "synonym",
+        detail: conflict.detail,
+        names: [c.name, conflict.existingName],
+        source: "registry",
+      });
+    }
+  }
+  return findings;
+}
+
+/** The full pass: reconcile the accumulated blackboard `contract` signals against the durable
+ * registry, plus the registry against itself. */
+export function reconcileContracts(
+  signals: ContractSignal[],
+  contracts: Contract[] = allContracts(),
+): ReconciliationReport {
+  const findings: ReconciliationFinding[] = [...reconcileRegistry(contracts)];
+  const byName = new Map(contracts.map((c) => [c.name, c]));
+
+  for (const sig of signals) {
+    // A structured signal (has category+name) can be checked against the registry precisely.
+    if (sig.category && sig.name) {
+      const conflicts = detectDeclarationConflicts(
+        { category: sig.category, name: sig.name, semantics: sig.body },
+        contracts,
+      );
+      for (const conflict of conflicts) {
+        findings.push({
+          kind: conflict.kind === "synonym" ? "synonym" : conflict.kind === "contradiction" ? "contradiction" : "rejected-synonym",
+          detail: `${sig.authorTask}: ${conflict.detail}`,
+          names: [conflict.proposedName, conflict.existingName].filter(Boolean),
+          source: sig.authorTask,
+        });
+      }
+      // Mock-vs-real skew: an in-flight signal for a contract that never landed in the durable
+      // registry. The blackboard is the live signal; the registry is the durable truth. A signal
+      // with no registry entry is exactly the divergence-only-at-runtime risk the issue names.
+      // BUT a signal already flagged as a synonym or rejected synonym must NOT also be reported as
+      // skew: the correct action is to reuse the existing canonical contract, not to "land" the
+      // proposed (synonymous/retired) name in the registry — so a skew finding there is noise that
+      // contradicts the synonym advice.
+      const isSynonymish = conflicts.some((c) => c.kind === "synonym" || c.kind === "rejected-synonym");
+      if (!byName.has(sig.name) && !isSynonymish) {
+        findings.push({
+          kind: "mock-vs-real-skew",
+          detail: `${sig.authorTask}: signalled contract '${sig.category}:${sig.name}' on the blackboard but it is not in the durable registry — land it in app/contracts.ts or it stays a mock-only agreement.`,
+          names: [sig.name],
+          source: sig.authorTask,
+        });
+      }
+    }
+  }
+  return { findings, clean: findings.length === 0 };
+}
+
+/** Render a report as a short, human/agent-readable text block (for an escalation body or a log). */
+export function formatReconciliationReport(report: ReconciliationReport): string {
+  if (report.clean) return "Contract reconciliation: no synonyms, contradictions, or mock-vs-real skew found.";
+  const lines = report.findings.map((f) => `- [${f.kind}] ${f.detail}`);
+  return `Contract reconciliation found ${report.findings.length} issue(s):\n${lines.join("\n")}`;
+}