@nanobpm/nano-workforce 0.70.2 → 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,17 @@
+# [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)
+
+
+### Features
+
+* add a Tasks page to resolve native user-task escalations in the UI ([#238](https://github.com/nanobpm/nano-workforce/issues/238)) ([4dcd1a1](https://github.com/nanobpm/nano-workforce/commit/4dcd1a1ca1756bec45997ce619ed92bff31d03d6)), closes [210/#220](https://github.com/nanobpm/nano-workforce/issues/220)
+
 ## [0.70.2](https://github.com/nanobpm/nano-workforce/compare/v0.70.1...v0.70.2) (2026-08-15)
 
 

package/SPEC.md

@@ -264,8 +264,12 @@ generic Urban **page runtime** (`@nanobpm/app`, ADR 0042) — no hand-written SP
 The page defines status-filtered tabs (active vs. history), a submit form, a
 per-row **Cancel** action, and an expandable detail with the round/escalation
 child grids and a lazily-loaded transcript. The round/escalation grids are
-read-only audit; escalations are answered through the **task inbox** surface at
-`/tasks` (native `userTask`s), not an inline form on this page.
+read-only audit. Open native user-task escalations are additionally resolved
+app-side from the **Tasks** page (`pages/tasks.page.json`, issue #236) — a nav
+tab whose per-kind `dataGrid`s list every open escalation (feature / plan-review
+/ trial-merge / PR review / blocked-run) off the `user_tasks` read-model and
+submit the typed decision to the canonical human completer — so an operator no
+longer depends on Urban's read-only `taskInbox` stub at `/tasks`.
 
 The app-specific business-logic endpoints are **OpenAPI operations** mounted
 under `api.base` (`/app/api`), each implemented by a delegate module in
@@ -282,6 +286,7 @@ The full, authoritative contract is `openapi.yaml` (Swagger UI at
 | `POST` | `/app/api/actions/start/convergence-loop` | parse the PR ref → create the aggregate + start the process (the ONE submit door — page + external callers) |
 | `POST` | `/app/api/actions/start/plan-fanout` | parse the issue ref → start a plan fan-out run (the ONE plan door) |
 | `POST` | `/app/api/actions/message` (`escalation-answered`) | answer an open merge-loop escalation → publish `escalation-answered` (the four #156 escalation kinds are native user tasks answered via the task inbox) |
+| `POST` | `/app/api/actions/complete-user-task` | complete an open native user-task escalation from the Tasks page (plan-review / trial-merge / PR `wait-answer`) → `completeEscalationAsHuman` (the same resume path the task inbox uses) |
 | `GET`/`POST` | `/app/api/hooks/blackboard` | per-plan coordination blackboard (capability-token side-channel) |
 | `GET` | `/app/api/hooks/abandon` | cooperative abandon check (per-PR capability token) |
 

package/app/agentCompletion.test.ts

@@ -21,6 +21,7 @@ import {
   latestCompletion,
   revertAgentCompletion,
   type TaskCompletion,
+  validateEscalationVariables,
 } from "./agentCompletion.ts";
 
 /** A minimal in-memory `Table<T>`: AUTOINCREMENT ids on insert, structural `find`, `get`, `update`. */
@@ -386,3 +387,71 @@ test("latestCompletion returns the newest row by id regardless of insertion orde
   assertEquals(newest.id, 3, "the highest-id row for the key wins, not the first found");
   assertEquals(stores.task_completions.rows[0].id, 3, "the backing array is not reordered");
 });
+
+// --- Form-contract enforcement (issue #236 review advisory): a completion must satisfy the linked
+// `.form`'s required-field + select allowed-value contract BEFORE the engine resumes, so a missing or
+// invalid decision can never park the process in an invalid state. Derived from the canonical `.form`,
+// exercised through BOTH completers so agent and human paths reject invalid input identically.
+
+test("completer rejects a completion missing a required form field (no engine resume, no ledger row)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-1", elementId: "wait-answer" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-1",
+    operatorId: "alice",
+    variables: { answer: "   " }, // required, but blank
+  });
+
+  assertEquals(r.ok, false);
+  assert(String(r.reason).includes("answer"), "the reason names the missing required field");
+  assertEquals(completed.length, 0, "an invalid completion never resumes the process");
+  assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
+});
+
+test("completer rejects a select value outside the form's allowed set", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-2", elementId: "trial-merge-decision" }]);
+
+  const r = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-2",
+    agentId: "bot",
+    variables: { action: "explode" }, // not one of proceed/rebase/abandon
+  });
+
+  assertEquals(r.ok, false);
+  assert(String(r.reason).includes("action"), "the reason names the invalid select field");
+  assertEquals(completed.length, 0, "an out-of-range decision never resumes the process");
+});
+
+test("completer accepts variables that satisfy the form contract (required present + allowed value)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-3", elementId: "plan-review-decision" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-3",
+    operatorId: "alice",
+    variables: { directive: "revise", notes: "narrow scope" },
+  });
+
+  assertEquals(r.ok, true);
+  assertEquals(completed.length, 1, "a contract-valid completion resumes the process");
+  assertEquals(completed[0].variables, { directive: "revise", notes: "narrow scope" });
+});
+
+test("validateEscalationVariables derives its contract from the canonical .form files", async () => {
+  // wait-answer -> pr-escalation.form (answer required)
+  assertEquals(validateEscalationVariables("wait-answer", { answer: "ok" }), null);
+  assert(validateEscalationVariables("wait-answer", {}) !== null);
+  // trial-merge-decision -> action required, allowed proceed/rebase/abandon
+  assertEquals(validateEscalationVariables("trial-merge-decision", { action: "abandon" }), null);
+  assert(validateEscalationVariables("trial-merge-decision", { action: "nope" }) !== null);
+  // plan-review-decision -> directive required, allowed proceed/revise
+  assertEquals(validateEscalationVariables("plan-review-decision", { directive: "proceed" }), null);
+  assert(validateEscalationVariables("plan-review-decision", { directive: "" }) !== null);
+  // an element with no linked form contract is not enforced
+  assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
+});

package/app/agentCompletion.ts

@@ -20,6 +20,7 @@
 // SAME `completeUserTaskAttributed` (as `human`), so there is exactly one implementation of "complete
 // an escalation user task" — the agent path is an extension of it, not a parallel copy.
 
+import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 
 const now = () => new Date().toISOString();
@@ -69,6 +70,77 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
 ]);
 
+/** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
+ *  BPMN `zeebe:formDefinition formId`). Kept beside `ESCALATION_TASK_ELEMENTS` so the completer
+ *  validates against the SAME `.form` the task inbox renders — one contract, no second field list. */
+const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
+  "feature-escalation": "feature-escalation",
+  "plan-review-decision": "plan-review-decision",
+  "trial-merge-decision": "trial-merge-decision",
+  "wait-answer": "pr-escalation",
+};
+
+interface FormContract {
+  /** Field keys marked `validate.required` in the `.form`. */
+  required: string[];
+  /** `select` field key → its allowed `values`. */
+  allowed: Record<string, string[]>;
+}
+
+const formContractCache = new Map<string, FormContract>();
+
+/** Derive a `.form`'s required-field + select allowed-value contract, cached per formId. The `.form`
+ *  files (`resources/forms/*.form`, deployed via nano.app.json) are the CANONICAL contract, so this
+ *  reads them rather than re-encoding the field lists — no drift surface. */
+function formContract(formId: string): FormContract {
+  const cached = formContractCache.get(formId);
+  if (cached) return cached;
+  const raw: {
+    components?: { key?: string; validate?: { required?: boolean }; values?: { value?: string }[] }[];
+  } = JSON.parse(readFileSync(new URL(`../resources/forms/${formId}.form`, import.meta.url), "utf8"));
+  const required: string[] = [];
+  const allowed: Record<string, string[]> = {};
+  for (const c of raw.components ?? []) {
+    if (!c.key) continue;
+    if (c.validate?.required) required.push(c.key);
+    if (c.values?.length) {
+      allowed[c.key] = c.values.map((v) => v.value ?? "").filter((v) => v !== "");
+    }
+  }
+  const contract: FormContract = { required, allowed };
+  formContractCache.set(formId, contract);
+  return contract;
+}
+
+/** Validate completion `variables` against the escalation's `.form` contract (required fields present
+ *  + `select` values within the allowed set), so a completion can never resume the process with a
+ *  missing/invalid decision (e.g. a `wait-answer` with no `answer`, or a `trial-merge-decision` with
+ *  an `action` outside proceed/rebase/abandon). Returns a human-readable reason on violation, or
+ *  `null` when the variables satisfy the contract. Derived from the canonical `.form` — the same
+ *  contract the task inbox renders — so both the agent and human completers reject invalid input the
+ *  exact same way, with one implementation. An element with no linked form contract is not enforced. */
+export function validateEscalationVariables(
+  elementId: string,
+  variables: Record<string, unknown>,
+): string | null {
+  const formId = ESCALATION_FORM_BY_ELEMENT[elementId];
+  if (!formId) return null;
+  const { required, allowed } = formContract(formId);
+  for (const key of required) {
+    const v = variables[key];
+    if (v === undefined || v === null || (typeof v === "string" && v.trim() === "")) {
+      return `${elementId}: "${key}" is required`;
+    }
+  }
+  for (const [key, values] of Object.entries(allowed)) {
+    const v = variables[key];
+    if (v !== undefined && v !== null && !values.includes(String(v))) {
+      return `${elementId}: "${key}" must be one of ${values.join(", ")}`;
+    }
+  }
+  return null;
+}
+
 /** The canonical attributed completer. Records an attribution row in `task_completions` (reversible
  *  iff the actor is an agent) and THEN completes the user task with the exact typed `variables` — so
  *  the ledger row can never be lost by a resume that fires before the write. If the engine
@@ -183,6 +255,9 @@ export async function completeEscalationAsAgent(
   const resolved = await resolveEscalationTask(engine, userTaskKey);
   if (!resolved.ok) return resolved;
 
+  const invalid = validateEscalationVariables(resolved.elementId, input.variables);
+  if (invalid) return { ok: false, reason: invalid };
+
   const { completionId } = await completeUserTaskAttributed(
     data,
     engine,
@@ -212,6 +287,9 @@ export async function completeEscalationAsHuman(
   const resolved = await resolveEscalationTask(engine, userTaskKey);
   if (!resolved.ok) return resolved;
 
+  const invalid = validateEscalationVariables(resolved.elementId, input.variables);
+  if (invalid) return { ok: false, reason: invalid };
+
   const { completionId } = await completeUserTaskAttributed(
     data,
     engine,

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 });
 }