@nanobpm/nano-workforce 0.70.2 → 0.72.0

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")}`;
+}

package/app/contracts.test.ts

@@ -0,0 +1,111 @@
+// Unit tests for the durable contract registry + typed env schema (issue #227, ADR 0004).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  allContracts,
+  detectDeclarationConflicts,
+  ENV_CONTRACTS,
+  envContract,
+  readEnv,
+  readEnvOr,
+  rejectedEnvSynonyms,
+} from "./contracts.ts";
+
+test("readEnv: trims, treats blank/whitespace as unset, reads the injected env", () => {
+  assertEquals(readEnv("NANO_WORKFORCE_BASE_URL", { NANO_WORKFORCE_BASE_URL: "  https://x  " }), "https://x");
+  assertEquals(readEnv("NANO_WORKFORCE_BASE_URL", { NANO_WORKFORCE_BASE_URL: "   " }), undefined);
+  assertEquals(readEnv("NANO_WORKFORCE_BASE_URL", {}), undefined);
+});
+
+test("readEnvOr: falls back to the registry default, then to the given fallback", () => {
+  assertEquals(readEnvOr("NANO_WORKFORCE_BASE_URL", "x", {}), "http://localhost:3000");
+  assertEquals(readEnvOr("NANO_WORKFORCE_BASE_URL", "x", { NANO_WORKFORCE_BASE_URL: "https://y" }), "https://y");
+  // A key with no registered default falls through to the caller's fallback.
+  assertEquals(readEnvOr("NANO_ESCALATION_SLA_TIMEOUT", "PT24H", {}), "PT24H");
+});
+
+test("rejectedEnvSynonyms: maps retired base-URL names to the canonical key (#226/#223)", () => {
+  const rejected = rejectedEnvSynonyms();
+  assertEquals(rejected.get("NANO_PR_PUBLIC_BASE_URL"), "NANO_WORKFORCE_BASE_URL");
+  assertEquals(rejected.get("NANO_PR_BASE_URL"), "NANO_WORKFORCE_BASE_URL");
+});
+
+test("envContract: exposes owner + semantics + default for a declared key", () => {
+  const c = envContract("NANO_WORKFORCE_BASE_URL");
+  assertEquals(c.name, "NANO_WORKFORCE_BASE_URL");
+  assertEquals(c.default, "http://localhost:3000");
+  assert(c.semantics.length > 0, "an env contract must carry semantics");
+});
+
+test("allContracts: includes env, wire, type, and capability-url entries", () => {
+  const cats = new Set(allContracts().map((c) => c.category));
+  for (const cat of ["env", "wire", "type", "capability-url"] as const) {
+    assert(cats.has(cat), `registry must carry a ${cat} contract`);
+  }
+});
+
+test("detectDeclarationConflicts: a differently-named env key with equivalent semantics is a synonym", () => {
+  const conflicts = detectDeclarationConflicts({
+    category: "env",
+    name: "NANO_PR_EXTERNAL_BASE_URL",
+    semantics:
+      "Externally-reachable base URL agents use to reach this app; drives every plan's blackboard capability URL.",
+  });
+  assert(
+    conflicts.some((c) => c.kind === "synonym" && c.existingName === "NANO_WORKFORCE_BASE_URL"),
+    "a semantically-equivalent env key must be flagged as a synonym of the existing one",
+  );
+});
+
+test("detectDeclarationConflicts: the same name with different semantics is a contradiction", () => {
+  const conflicts = detectDeclarationConflicts({
+    category: "env",
+    name: "NANO_PR_POLL_MS",
+    semantics: "completely unrelated meaning about widget colours and fonts",
+  });
+  assert(
+    conflicts.some((c) => c.kind === "contradiction"),
+    "a redeclaration of an existing name with different semantics must contradict",
+  );
+});
+
+test("detectDeclarationConflicts: a retired synonym is flagged as rejected-synonym", () => {
+  const conflicts = detectDeclarationConflicts({
+    category: "env",
+    name: "NANO_PR_BASE_URL",
+    semantics: "the base url",
+  });
+  assertEquals(conflicts[0].kind, "rejected-synonym");
+  assertEquals(conflicts[0].existingName, "NANO_WORKFORCE_BASE_URL");
+});
+
+test("detectDeclarationConflicts: a genuinely new, distinct contract is clean", () => {
+  const conflicts = detectDeclarationConflicts({
+    category: "env",
+    name: "NANO_WIDGET_TIMEOUT",
+    semantics: "milliseconds a widget waits before giving up on a render",
+  });
+  assertEquals(conflicts, []);
+});
+
+test("every declared env key's registry name matches its key (no internal drift)", () => {
+  for (const [key, value] of Object.entries(ENV_CONTRACTS)) {
+    assertEquals(value.name, key, `ENV_CONTRACTS['${key}'].name must equal its key`);
+  }
+});
+
+test("config-family keys read via envVar() are declared (the check:contracts blind spot, PR #229)", () => {
+  // These are read in production through the `envVar("KEY")` helper (app/version.ts, operations/*,
+  // main.ts), which bypasses the typed `readEnv` path. They MUST still be declared, or they are an
+  // unregistered second source of truth — exactly the drift the registry exists to kill (#227).
+  for (const key of [
+    "NANO_PR_WEBHOOK_SECRET",
+    "NANO_AGENTIC_SECRET",
+    "NANO_AGENTIC",
+    "NANO_WORKFORCE_GIT_SHA",
+  ] as const) {
+    assert(key in ENV_CONTRACTS, `${key} must be declared in ENV_CONTRACTS`);
+  }
+  assertEquals(envContract("NANO_PR_WEBHOOK_SECRET").secret, true);
+  assertEquals(envContract("NANO_AGENTIC_SECRET").secret, true);
+});