@nanobpm/nano-workforce 0.71.0 → 0.72.0

package/openapi.yaml

@@ -864,6 +864,30 @@ components:
                 type: string
               created_at:
                 type: string
+        contractConflicts:
+          type: array
+          description: >-
+            Near-duplicate contract-DECLARATION conflicts on a `contract` POST (issue #227): a
+            synonym, contradiction, or rejected synonym vs. the durable contract registry. Advisory —
+            surfaced so the writer reconciles a divergent contract at authoring time; never a lock.
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - kind
+              - proposedName
+              - existingName
+              - detail
+            properties:
+              kind:
+                type: string
+                enum: [synonym, contradiction, rejected-synonym]
+              proposedName:
+                type: string
+              existingName:
+                type: string
+              detail:
+                type: string
     AbandonStatus:
       type: object
       required:

package/operations/appendBlackboard.ts

@@ -7,11 +7,15 @@
 //   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
 //          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
 //          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
+//          A `contract` POST additionally returns `contractConflicts` (near-duplicate declaration
+//          conflicts vs. the durable registry, #227); the field is absent for other kinds, per the
+//          OpenAPI schema's optional property.
 
 import {
   appendEntry,
+  detectContractDeclarationConflicts,
   detectFileClaimConflicts,
-  normalizeKind,
+  normalizeAppKind,
   planKeyForToken,
 } from "../app/blackboard.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -28,40 +32,56 @@ export default defineOperation("appendBlackboard", async ({ req, body }, app) =>
   const b = body ?? {};
   const text = typeof b.body === "string" ? b.body.trim() : "";
   if (!text) return { status: 400, body: { error: "'body' (the note text) is required" } };
-  const kind = normalizeKind(b.kind);
+  const kind = normalizeAppKind(b.kind);
   const files = Array.isArray(b.files) ? b.files.map(String) : [];
   // Normalize once (trim + default to "system") so the value we send to appendEntry matches the
   // value we send to detectFileClaimConflicts. Otherwise an omitted/blank author_task is stored as
   // "system" but conflict detection sees "", and the caller's own prior "system" claims are wrongly
   // reported as sibling conflicts.
   const author_task = (typeof b.author_task === "string" ? b.author_task.trim() : "") || "system";
+  // Trim before it becomes the idempotency key: `dedupe_key` backs a unique index (and is now also
+  // parsed for the `<category>:<name>` contract ref), so accidental leading/trailing whitespace would
+  // otherwise slip past dedupe and create near-identical entries. A blank-after-trim key is no key.
+  const dedupe_key = typeof b.dedupe_key === "string" ? b.dedupe_key.trim() || undefined : undefined;
   const res = await appendEntry(app.data, planKey, {
     author_task,
     kind,
     files,
     body: text,
     wave: typeof b.wave === "number" ? b.wave : null,
-    dedupe_key: typeof b.dedupe_key === "string" ? b.dedupe_key : undefined,
+    dedupe_key,
   });
-  // Advisory conflict-of-intent: surface prior sibling claims on the same file(s). Computed AFTER
-  // the append and filtered to claims strictly before ours (id < res.id), so first-writer-wins is
-  // decided by insertion order — a sibling that raced a claim in between is still caught, and our
-  // own just-written row is never reported. Never blocks the append — the agent decides how to react.
+  // Advisory conflict-of-intent. For a `file-claim`, surface prior sibling claims on the same
+  // file(s) — computed AFTER the append and filtered to claims strictly before ours (id < res.id),
+  // so first-writer-wins is decided by insertion order (a sibling that raced a claim in between is
+  // still caught, and our own just-written row is never reported). Never blocks the append.
   const conflicts = kind === "file-claim"
     ? await detectFileClaimConflicts(app.data, planKey, {
       author_task,
       files,
-      beforeId: Number(res.id),
+      beforeId: res.id,
     })
     : [];
+  // For a `contract`, surface near-duplicate DECLARATION conflicts (a synonym/contradiction/rejected
+  // synonym vs. the durable registry) so a writer reconciles a divergent contract at authoring time
+  // (#227). Advisory — the agent decides how to react.
+  const contractConflicts = kind === "contract"
+    ? detectContractDeclarationConflicts({ dedupe_key, body: text })
+    : [];
   app.log.info("blackboard entry appended", {
     planKey,
     kind,
     inserted: res.inserted,
     conflicts: conflicts.length,
+    contractConflicts: contractConflicts.length,
   });
   return {
     status: res.inserted ? 201 : 200,
-    body: { id: Number(res.id), inserted: res.inserted, conflicts },
+    // `contractConflicts` is only meaningful on a `contract` POST and is optional in the schema, so
+    // omit it entirely for other kinds rather than emitting an always-empty array (keeps the response
+    // shape aligned with the OpenAPI contract, which does not require the field).
+    body: kind === "contract"
+      ? { id: res.id, inserted: res.inserted, conflicts, contractConflicts }
+      : { id: res.id, inserted: res.inserted, conflicts },
   };
 });

package/operations/blackboard.test.ts

@@ -100,6 +100,18 @@ test("POST is idempotent on dedupe_key (retry → 200, not a duplicate)", async
   assertEquals(n, 1);
 });
 
+test("POST dedupe_key is trimmed → a whitespace-padded retry still dedupes to one row (#227)", async () => {
+  const { app, db } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  assertEquals((await call(app, "POST", { token: "tok" }, { author_task: "t", body: "claim", dedupe_key: "t:claim:1" })).status, 201);
+  // A retry whose key only differs by leading/trailing whitespace must NOT slip past dedupe.
+  const padded = await call(app, "POST", { token: "tok" }, { author_task: "t", body: "claim", dedupe_key: "  t:claim:1  " });
+  assertEquals(padded.status, 200);
+  assertEquals(padded.body.inserted, false);
+  const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard WHERE scope = ?", ["o/r#1"]);
+  assertEquals(n, 1);
+});
+
 test("GET ?since returns only newer entries", async () => {
   const { app } = memApp();
   await seedPlan(app, "o/r#1", "tok");
@@ -175,4 +187,41 @@ test("POST a non-file-claim carries no conflicts", async () => {
   await seedPlan(app, "o/r#1", "tok");
   const res = await call(app, "POST", { token: "tok" }, { author_task: "t", kind: "note", body: "fyi" });
   assertEquals(res.body.conflicts, []);
+  // `contractConflicts` is optional in the schema and only meaningful on a `contract` POST — a
+  // non-`contract` response omits it entirely rather than emitting an always-empty array (#229).
+  assertEquals("contractConflicts" in res.body, false);
+});
+
+test("POST kind='contract' persists the contract kind and round-trips through GET (#227)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const post = await call(app, "POST", { token: "tok" }, {
+    author_task: "task-a",
+    kind: "contract",
+    dedupe_key: "env:NANO_WIDGET_TIMEOUT",
+    body: "introducing env key NANO_WIDGET_TIMEOUT — app/widget.ts — widget request timeout in ms",
+  });
+  assertEquals(post.status, 201);
+  // No existing contract matches, so no declaration conflicts.
+  assertEquals(post.body.contractConflicts, []);
+
+  const get = await call(app, "GET", { token: "tok" });
+  assertEquals(get.body.entries.length, 1);
+  // The store's normaliser would coerce an unknown kind to 'note'; the adapter restores 'contract'.
+  assertEquals(get.body.entries[0].kind, "contract");
+});
+
+test("POST kind='contract' reintroducing a rejected synonym surfaces a declaration conflict (#223/#227)", async () => {
+  const { app } = memApp();
+  await seedPlan(app, "o/r#1", "tok");
+  const post = await call(app, "POST", { token: "tok" }, {
+    author_task: "task-b",
+    kind: "contract",
+    dedupe_key: "env:NANO_PR_BASE_URL",
+    body: "base url for the app",
+  });
+  assertEquals(post.status, 201);
+  assertEquals(post.body.contractConflicts.length >= 1, true);
+  assertEquals(post.body.contractConflicts[0].kind, "rejected-synonym");
+  assertEquals(post.body.contractConflicts[0].existingName, "NANO_WORKFORCE_BASE_URL");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -37,6 +37,8 @@
     "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
     "check:migrations": "node --experimental-strip-types scripts/check-migrations.ts",
+    "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",
+    "reconcile:contracts": "node --experimental-strip-types scripts/reconcile-contracts.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",

package/scripts/check-contracts.test.ts

@@ -0,0 +1,58 @@
+// Coverage for the config-key SCAN in the contract gate (scripts/check-contracts.ts, PR #229).
+//
+// The gate is only as strong as the read patterns it recognises. Before this fix it matched only
+// dot-access (`process.env.KEY`), so a config-family key smuggled in through the `envVar("KEY")`
+// helper or string-literal bracket-access silently bypassed the "must be declared" invariant — which
+// is how NANO_PR_WEBHOOK_SECRET / NANO_AGENTIC* stayed undeclared while `check:contracts` passed
+// green. These assert `envKeyReads` sees all three patterns so the gate can hold them to the registry.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { envKeyReads, EXPLICIT_CONFIG_KEYS, toPosixRel } from "./check-contracts.ts";
+import { ENV_CONTRACTS } from "../app/contracts.ts";
+
+test("envKeyReads: dot-access is recognised", () => {
+  assertEquals(envKeyReads("const x = process.env.NANO_PR_POLL_MS;"), ["NANO_PR_POLL_MS"]);
+});
+
+test("envKeyReads: string-literal bracket-access is recognised (double and single quote)", () => {
+  assert(envKeyReads('process.env["NANO_PR_WEBHOOK_SECRET"]').includes("NANO_PR_WEBHOOK_SECRET"));
+  assert(envKeyReads("process.env['NANO_AGENTIC']").includes("NANO_AGENTIC"));
+});
+
+test("envKeyReads: the envVar(\"KEY\") helper is recognised", () => {
+  assert(envKeyReads('const s = envVar("NANO_AGENTIC_SECRET") ?? "";').includes("NANO_AGENTIC_SECRET"));
+  assert(envKeyReads('envVar( "NANO_WORKFORCE_GIT_SHA" )').includes("NANO_WORKFORCE_GIT_SHA"));
+});
+
+test("envKeyReads: catches keys across all patterns in one source", () => {
+  const src = [
+    "const a = process.env.CAMUNDA_TRANSPORT;",
+    'const b = process.env["NANOBPMN_BASE_URL"];',
+    'const c = envVar("NANO_WORKFORCE_GIT_SHA");',
+  ].join("\n");
+  const keys = new Set(envKeyReads(src));
+  assert(keys.has("CAMUNDA_TRANSPORT"));
+  assert(keys.has("NANOBPMN_BASE_URL"));
+  assert(keys.has("NANO_WORKFORCE_GIT_SHA"));
+});
+
+test("envKeyReads: a dynamic (non-literal) read is NOT matched", () => {
+  // `process.env[name]` (a variable) can't be resolved statically, so it isn't reported.
+  assertEquals(envKeyReads("const v = process.env[name];"), []);
+});
+
+test("GITHUB_TOKEN is enforced by the gate and declared in the registry (PR #229 suppressed advisory)", () => {
+  // GITHUB_TOKEN is read in production outside the config families (app/service.ts,
+  // operations/startPlanFanout.ts). Pin it into the enforced set so the gate holds it to its
+  // registry declaration — a future removal from ENV_CONTRACTS while code still reads it must fail.
+  assert(EXPLICIT_CONFIG_KEYS.has("GITHUB_TOKEN"), "GITHUB_TOKEN must be an enforced config key");
+  assert("GITHUB_TOKEN" in ENV_CONTRACTS, "GITHUB_TOKEN must be declared in ENV_CONTRACTS");
+});
+
+test("toPosixRel: normalises Windows backslashes so EXEMPT_FILES matches cross-platform (PR #229 suppressed advisory)", () => {
+  // On Windows `join` yields backslashes, so `scripts\check-contracts.ts` would never match the
+  // POSIX-style EXEMPT_FILES entry and the checker would self-scan and explode. Normalise them.
+  assertEquals(toPosixRel("C:\\repo\\scripts\\check-contracts.ts", "C:\\repo"), "scripts/check-contracts.ts");
+  // POSIX paths are already correct and pass through unchanged.
+  assertEquals(toPosixRel("/repo/scripts/check-contracts.ts", "/repo"), "scripts/check-contracts.ts");
+});

package/scripts/check-contracts.ts

@@ -0,0 +1,151 @@
+// check-contracts — CI gate for the shared contract registry (issue #227, ADR 0004).
+//
+// The registry (`app/contracts.ts`) is the single source of truth for cross-cutting contracts. This
+// gate enforces the invariants that make a duplicate/synonymous contract a BUILD failure rather than
+// a silent runtime fallback (the #223 / nano-ide #234 failure mode):
+//
+//   1. EVERY config-family env key read anywhere in the app (`process.env.NANO_*`, `CAMUNDA_*`,
+//      `NANOBPMN_BASE_URL`, `PR_REVIEW_PORT`) MUST be declared in the ONE typed schema
+//      `ENV_CONTRACTS`. An undeclared config key is a second, unregistered source of truth — fail.
+//      The scan recognises all three read patterns the app uses: dot-access (`process.env.KEY`),
+//      string-literal bracket-access (`process.env["KEY"]`), and the `envVar("KEY")` helper
+//      (`app/version.ts`) — a config key smuggled in through any of them must still be declared.
+//   2. NO rejected synonym (a name we deliberately retired, e.g. `NANO_PR_BASE_URL`) may appear in
+//      code. Its reappearance is the #223 phantom-fallback cascade — fail.
+//   3. The registry must reconcile against itself: no two entries are synonyms, no rejected synonym
+//      leaked back into the registry (`reconcileRegistry`).
+//
+// Scope note: the env-key scan targets the config family (below), NOT every env var — infra reads
+// like `NODE_ENV` are not app contracts. `GITHUB_TOKEN`/`CAMUNDA_TOKEN` ARE declared (as secrets) so
+// the schema documents them, but they need no fallback default.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { reconcileRegistry } from "../app/contractReconcile.ts";
+import { ENV_CONTRACTS, rejectedEnvSynonyms } from "../app/contracts.ts";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// The directories that hold app code (mirrors the `lint` glob in package.json).
+const CODE_DIRS = ["app", "operations", "workers", "pages", "components", "scripts", "e2e"];
+const CODE_FILES = ["main.ts"];
+
+// The config-family env-key prefixes/names that MUST be declared in ENV_CONTRACTS. Anything matching
+// this and not declared is an unregistered config source of truth.
+//
+// A config key is read one of three ways in this app, and all three must be held to the registry
+// invariant — otherwise a key smuggled in via `envVar("…")` or bracket-access silently bypasses the
+// gate (the exact blind spot that let NANO_PR_WEBHOOK_SECRET / NANO_AGENTIC* go undeclared):
+//   - dot-access:                 process.env.KEY
+//   - string-literal bracket:     process.env["KEY"] / process.env['KEY']
+//   - the envVar() helper:        envVar("KEY")  (app/version.ts)
+const CONFIG_KEY_MATCHERS: readonly RegExp[] = [
+  /\bprocess\.env\.([A-Z][A-Z0-9_]*)\b/g,
+  /\bprocess\.env\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\]/g,
+  /\benvVar\(\s*["']([A-Z][A-Z0-9_]*)["']\s*\)/g,
+];
+const CONFIG_FAMILY = /^(NANO_|NANOBPMN_|CAMUNDA_|PR_REVIEW_)/;
+// `GITHUB_TOKEN` is the one production credential read outside the config families (app/service.ts,
+// operations/startPlanFanout.ts). It is declared in ENV_CONTRACTS; enforce that declaration here so a
+// future removal from the registry while code still reads it trips the gate (issue #227).
+export const EXPLICIT_CONFIG_KEYS = new Set(["PR_REVIEW_PORT", "GITHUB_TOKEN"]);
+
+/** Every env-key name read in `src` via any supported pattern (dot-access, string-literal
+ * bracket-access, or the `envVar("KEY")` helper). Order-preserving, with duplicates, so a caller can
+ * report each read site's key against the registry. */
+export function envKeyReads(src: string): string[] {
+  const keys: string[] = [];
+  for (const matcher of CONFIG_KEY_MATCHERS) {
+    for (const m of src.matchAll(matcher)) keys.push(m[1]);
+  }
+  return keys;
+}
+
+// The registry module declares the keys and (in comments/strings) names the rejected synonyms, this
+// checker's own doc comment shows the read patterns it scans for, and this checker's test embeds
+// literal `process.env[…]` / `envVar(…)` fixtures — all would self-trip the scan, so they are exempt.
+const EXEMPT_FILES = new Set([
+  "app/contracts.ts",
+  "scripts/check-contracts.ts",
+  "scripts/check-contracts.test.ts",
+]);
+
+function walk(dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (entry === "node_modules" || entry === "nano-generated" || entry.startsWith(".")) continue;
+      walk(full, out);
+    } else if ([".ts", ".mts", ".cts"].includes(extname(full))) {
+      out.push(full);
+    }
+  }
+}
+
+/** Path of `file` relative to ROOT, normalised to POSIX separators so it matches the POSIX-style
+ * `EXEMPT_FILES` entries on every platform (Windows `join` yields backslashes — issue #229 review). */
+export function toPosixRel(file: string, root: string = ROOT): string {
+  return file.slice(root.length + 1).replaceAll("\\", "/");
+}
+
+function collectFiles(): string[] {
+  const files: string[] = [];
+  for (const d of CODE_DIRS) {
+    const full = join(ROOT, d);
+    try {
+      if (statSync(full).isDirectory()) walk(full, files);
+    } catch {
+      /* dir may not exist in every checkout */
+    }
+  }
+  for (const f of CODE_FILES) {
+    const full = join(ROOT, f);
+    try {
+      if (statSync(full).isFile()) files.push(full);
+    } catch {
+      /* optional */
+    }
+  }
+  return files;
+}
+
+function main(): void {
+  const declared = new Set(Object.keys(ENV_CONTRACTS));
+  const rejected = rejectedEnvSynonyms();
+  const errors: string[] = [];
+
+  for (const file of collectFiles()) {
+    const rel = toPosixRel(file);
+    if (EXEMPT_FILES.has(rel)) continue;
+    const src = readFileSync(file, "utf8");
+    for (const key of envKeyReads(src)) {
+      if (rejected.has(key)) {
+        errors.push(
+          `  ${rel}: reads retired synonym '${key}' — reuse the canonical key '${rejected.get(key)}'. ` +
+            `A retired synonym must never come back as a silent fallback (issue #223).`,
+        );
+        continue;
+      }
+      if (!CONFIG_FAMILY.test(key) && !EXPLICIT_CONFIG_KEYS.has(key)) continue;
+      if (!declared.has(key)) {
+        errors.push(
+          `  ${rel}: reads config env key '${key}' that is NOT declared in ENV_CONTRACTS ` +
+            `(app/contracts.ts). Declare it in the ONE typed schema so it can't become a synonym.`,
+        );
+      }
+    }
+  }
+
+  for (const finding of reconcileRegistry()) {
+    errors.push(`  registry: [${finding.kind}] ${finding.detail}`);
+  }
+
+  if (errors.length > 0) {
+    console.error(`check-contracts: contract-registry violations:\n${errors.join("\n")}`);
+    process.exit(1);
+  }
+
+  console.log(`check-contracts: OK (${declared.size} declared env keys, registry reconciles clean).`);
+}
+
+if (import.meta.main) main();

package/scripts/reconcile-contracts.test.ts

@@ -0,0 +1,38 @@
+// Coverage for the advisory-only reconcile pass's URL decoding (scripts/reconcile-contracts.ts, PR
+// #229). The pass is designed to NEVER fail the build. `fileUrlToPath` decodes NANO_APP_DB_URL, and a
+// literal `%` (or any malformed %-escape) makes `decodeURIComponent` throw — which would crash an
+// "advisory, never gate CI" script. Decoding is now best-effort, so a malformed URL degrades to the
+// raw path instead of throwing.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { fileUrlToPath } from "./reconcile-contracts.ts";
+
+test("fileUrlToPath: decodes a well-formed percent-escape", () => {
+  assertEquals(fileUrlToPath("file:./my%20app.db"), "./my app.db");
+});
+
+test("fileUrlToPath: a malformed percent-escape does not throw (best-effort)", () => {
+  // A bare `%` is not a valid escape; decodeURIComponent would throw. The pass must not crash — a
+  // successful call that returns the raw path proves the decode is best-effort.
+  assertEquals(fileUrlToPath("file:./100%done.db"), "./100%done.db");
+});
+
+test("fileUrlToPath: a non-file URL yields undefined", () => {
+  assertEquals(fileUrlToPath("postgres://localhost/db"), undefined);
+});
+
+test("fileUrlToPath: a malformed file:// URL yields undefined, never throws (PR #229)", () => {
+  // `new URL("file://…")` throws on a malformed authority/host. The advisory pass must degrade to
+  // undefined (best-effort: file simply not found) rather than crash a "never gate CI" script.
+  assertEquals(fileUrlToPath("file://%zz/bad host/db.sqlite"), undefined);
+});
+
+test("fileUrlToPath: strips a query/hash suffix on an opaque file: URL (PR #229)", () => {
+  // A valid SQLite-style URL carries connection params (`?mode=ro`). The opaque `file:` branch must
+  // drop the `?…`/`#…` suffix so the path resolves to a real on-disk file, else reconciliation is
+  // silently disabled by a path that never exists.
+  assertEquals(fileUrlToPath("file:./app.db?mode=ro"), "./app.db");
+  assertEquals(fileUrlToPath("file:./app.db#frag"), "./app.db");
+  assertEquals(fileUrlToPath("file:./app.db?mode=ro&cache=shared#x"), "./app.db");
+});
+

package/scripts/reconcile-contracts.ts

@@ -0,0 +1,104 @@
+// npm run reconcile:contracts — the contract reconciliation pass runner (issue #227, ADR 0004).
+//
+// A sibling to the L2 retro: read the whole blackboard (`agentic_blackboard`) plus the durable
+// contract registry (`app/contracts.ts`) and report synonyms / contradictions / mock-vs-real skew.
+// Advisory by design — it PRINTS a report (an escalation / merge candidate) and exits 0, so it can
+// run periodically without gating CI. The registry-only, mechanically-enforceable half is the hard
+// gate `scripts/check-contracts.ts`; this pass adds the blackboard-vs-registry view.
+//
+// It reads the app sqlite datasource (NANO_APP_DB_URL, default `file:./app.db`) directly through
+// node:sqlite. If the datasource or the blackboard table is absent, it still runs the static
+// registry reconciliation.
+
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { BLACKBOARD_TABLE } from "@nanobpm/agentic/blackboard";
+import {
+  type ContractSignal,
+  formatReconciliationReport,
+  reconcileContracts,
+} from "../app/contractReconcile.ts";
+import type { ContractCategory } from "../app/contracts.ts";
+
+function safeDecodeURIComponent(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    // Advisory-only pass: a malformed %-escape in NANO_APP_DB_URL must never fail the build. Fall
+    // back to the raw segment so reconciliation still runs (worst case: the file simply isn't found).
+    return s;
+  }
+}
+
+export function fileUrlToPath(u: string): string | undefined {
+  if (!u.startsWith("file:")) return undefined;
+  if (u.startsWith("file://")) {
+    let pathname: string;
+    try {
+      pathname = new URL(u).pathname;
+    } catch {
+      // Advisory-only pass: a malformed file:// URL must never fail the build. Give up on this
+      // input (worst case the file simply isn't found) rather than throwing out of reconciliation.
+      return undefined;
+    }
+    const p = safeDecodeURIComponent(pathname);
+    return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+  }
+  // Opaque `file:` form (no authority) — the `new URL().pathname` branch above already drops any
+  // query/hash, but here we hold the raw remainder, so strip a `?…`/`#…` suffix ourselves. A valid
+  // SQLite-style URL like `file:./app.db?mode=ro` must resolve to `./app.db`, not `./app.db?mode=ro`
+  // (which never exists on disk and would silently disable blackboard reconciliation).
+  const raw = u.slice("file:".length).replace(/[?#].*$/, "");
+  const p = safeDecodeURIComponent(raw);
+  return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+}
+
+function parseRef(dedupeKey: string | null): { category?: ContractCategory; name?: string } {
+  if (!dedupeKey) return {};
+  const idx = dedupeKey.indexOf(":");
+  if (idx <= 0) return {};
+  const category = dedupeKey.slice(0, idx).trim();
+  const name = dedupeKey.slice(idx + 1).trim();
+  if (!name) return {};
+  if (category === "env" || category === "wire" || category === "type" || category === "capability-url") {
+    return { category, name };
+  }
+  return {};
+}
+
+function loadSignals(): ContractSignal[] {
+  const url = process.env.NANO_APP_DB_URL ?? "file:./app.db";
+  const path = fileUrlToPath(url);
+  if (!path || !existsSync(path)) return [];
+  let db: DatabaseSync;
+  try {
+    db = new DatabaseSync(path, { readOnly: true });
+  } catch {
+    // Advisory-only pass: opening the db can still fail (permission, invalid/corrupt file) even
+    // though the path exists. Degrade to no signals — reconcile the registry alone — rather than
+    // crash a script that must never gate CI.
+    return [];
+  }
+  try {
+    // biome-ignore lint/plugin: external node:sqlite row shape at the DB boundary — the column list is fixed by the SELECT above.
+    const rows = db
+      .prepare(
+        `SELECT author_task, body, dedupe_key FROM ${BLACKBOARD_TABLE} WHERE kind = 'contract' ORDER BY id ASC`,
+      )
+      .all() as { author_task: string; body: string; dedupe_key: string | null }[];
+    return rows.map((r) => ({ authorTask: r.author_task, body: r.body, ...parseRef(r.dedupe_key) }));
+  } catch {
+    // No blackboard table (bare/unmigrated db) — reconcile the registry alone.
+    return [];
+  } finally {
+    db.close();
+  }
+}
+
+function main(): void {
+  const report = reconcileContracts(loadSignals());
+  console.log(formatReconciliationReport(report));
+  // Advisory: never fail the build. The hard, registry-only gate is `npm run check:contracts`.
+}
+
+if (import.meta.main) main();