@nanobpm/nano-workforce 0.71.0 → 0.72.1

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.1",
   "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",