@nanobpm/nano-workforce 0.103.0 → 0.105.0

package/openapi.yaml

@@ -386,6 +386,15 @@ components:
         instance:
           type: string
           description: The worker instance id, echoed back for provenance (optional).
+        durableResume:
+          type: boolean
+          description: >-
+            Whether this worker's harness advertises durable-resume (issue #325, ADR 0062 Slice 5/5)
+            — an ENROLMENT attribute, never a routing token. Recorded per instance so the app emits
+            the world-restore marker only to a fleet with a participant; a harness that omits it (or
+            sets false) redrives a re-leased round from scratch. Recorded only when `instance` is
+            a non-blank string — a missing, empty, or whitespace-only `instance` is echoed back for
+            provenance but the flag is not persisted.
     EnrolledRole:
       type: object
       description: One matched role in an enrolment resolution — provenance for the resolved SERVE set.
@@ -411,6 +420,14 @@ components:
         instance:
           type: string
           description: The worker instance id, echoed from the request when supplied.
+        durableResume:
+          type: boolean
+          description: >-
+            Echo of the request's durable-resume declaration (issue #325, ADR 0062 Slice 5/5).
+            Present only when the request supplied it. This reflects the value the worker sent, not a
+            guarantee of durable persistence — recording into the durable-resume registry is
+            best-effort (skipped when `instance` is absent/blank, and a registry write hiccup is
+            logged without failing enrolment).
         serve:
           type: array
           description: The SERVE token set — sorted, de-duplicated leaf tokens the worker may serve.

package/operations/enrolAgenticWorker.test.ts

@@ -2,6 +2,8 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry } from "../app/durableResume.ts";
 import { noopLog } from "../test/log.ts";
 import handler from "./enrolAgenticWorker.ts";
 
@@ -69,6 +71,68 @@ test("rejects non-finite capability.weight (NaN/Infinity) as 400", async () => {
   assertEquals(infWeight.status, 400);
 });
 
+// Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5).
+test("echoes durableResume back in the result when the worker declares it", async () => {
+  const on = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), app)) as any;
+  assertEquals(on.status, 200);
+  assertEquals(on.body.durableResume, true);
+  const off = (await handler(input({ capability: { cognition: "decide" }, instance: "w2", durableResume: false }), app)) as any;
+  assertEquals(off.body.durableResume, false);
+});
+
+test("omits durableResume from the result when the worker does not declare it", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), app)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("durableResume" in res.body, false);
+});
+
+test("rejects a non-boolean durableResume as 400", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: "yes" }), app)) as any;
+  assertEquals(res.status, 400);
+});
+
+test("records durable-resume participation in the registry when a data layer + instance are present", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), true);
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), true);
+});
+
+test("a re-enrol omitting durableResume persists an explicit false, clearing a stale true (degrade to scratch)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  // First enrol advertises durable-resume.
+  await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), withData);
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), true);
+  // Re-enrol WITHOUT the field (downgrade/rollback/client bug) must clear the stale flag.
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("durableResume" in res.body, false, "still omitted from the echo");
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), false, "stale true cleared");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false);
+});
+
+test("a declaration without an instance is echoed but not persisted (enrolment is per-instance)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.durableResume, true, "still echoed");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false, "nothing recorded without an instance key");
+});
+
+test("a blank/whitespace instance is echoed but not persisted (avoids a shared registry-row collision)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "   ", durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.instance, "   ", "still echoed verbatim");
+  assertEquals(res.body.durableResume, true, "still echoed");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false, "nothing recorded for a blank instance key");
+});
+
 test("enforces the shared secret when NANO_PR_WEBHOOK_SECRET is set", async () => {
   // The module captures the secret at load, so re-import a cache-busted copy with the env var set to
   // exercise the guarded 401 path and the authorized 200 path.

package/operations/enrolAgenticWorker.ts

@@ -12,13 +12,14 @@
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 import type { Capability } from "@nanobpm/agentic/protocol";
 import { resolveEnrolment } from "../app/agentic/vocab/enrol.ts";
+import { DurableResumeRegistry } from "../app/durableResume.ts";
 import { envVar } from "../app/version.ts";
 import type { EnrolResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
+export default defineOperation("enrolAgenticWorker", async ({ req, body }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     app.log.warn("enrolAgenticWorker rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
@@ -65,6 +66,13 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
       body: { error: "`capability.weight` must be a finite number when provided" },
     };
   }
+  // The durable-resume enrolment attribute (issue #325, ADR 0062 Slice 5/5) — a boolean the harness
+  // advertises. A directly-invoked delegate bypasses the OpenAPI runtime validation, so guard the type
+  // here (a non-boolean would corrupt the {0,1} enrolment flag the world-restore gate reads).
+  if (body.durableResume !== undefined && typeof body.durableResume !== "boolean") {
+    app.log.warn("enrolAgenticWorker rejected: non-boolean durableResume");
+    return { status: 400, body: { error: "`durableResume` must be a boolean when provided" } };
+  }
 
   // Fold a top-level `host` into the capability when the capability didn't carry its own — a worker
   // may declare its host either on the capability or beside it (ADR 0059 `{ capability, host }`).
@@ -74,6 +82,26 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
       : body.capability;
 
   const resolved = resolveEnrolment(capability);
+
+  // Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): record whether this worker's
+  // harness advertises durable-resume so the world-restore marker is emitted only to a fleet with a
+  // participant. Recorded per instance (ADR 0056 §7 — an enrolment attribute, never a routing token),
+  // so it needs a non-blank `instance`; a declaration without one — or with a blank/whitespace
+  // string — is echoed but not persisted (a blank key would let unrelated workers collide on the
+  // same registry row and wrongly open/close the fleet-wide durable-resume gate). Omission of the
+  // field on a re-enrol persists an explicit `false` (degrade to scratch), so a harness that previously
+  // advertised durable-resume and later re-enrols without the field clears its stale `true` rather than
+  // leaving `fleetSupportsDurableResume()` true indefinitely. Best-effort — the enrolment resolution
+  // must not fail on a registry write hiccup.
+  const instanceKey = body.instance?.trim();
+  if (app.data && instanceKey) {
+    try {
+      await new DurableResumeRegistry(app.data).recordEnrolment(instanceKey, body.durableResume ?? false);
+    } catch (err) {
+      app.log.warn("enrolAgenticWorker: durable-resume record failed", { instance: instanceKey, err: String(err) });
+    }
+  }
+
   const result: EnrolResult = {
     serve: [...resolved.serve],
     roles: resolved.roles.map((role) => {
@@ -85,6 +113,7 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
     leaseTtl: resolved.leaseTtl,
   };
   if (body.instance !== undefined) result.instance = body.instance;
+  if (body.durableResume !== undefined) result.durableResume = body.durableResume;
 
   app.log.info("agentic enrol resolved", { instance: body.instance, serve: result.serve, family: capability.family });
   return { status: 200, body: result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.103.0",
+  "version": "0.105.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",

package/resources/processes/retro.bpmn

@@ -13,6 +13,18 @@
           <nano:extend name="pr" type="string" optional="true" />
           <nano:extend name="summary" type="string" optional="true" />
         </nano:shape>
+        <nano:shape id="ConformanceRecordIn" name="Record conformance — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="status" type="string" optional="true" />
+          <nano:extend name="commentUrl" type="string" optional="true" />
+          <nano:extend name="slicesMet" type="integer" optional="true" />
+          <nano:extend name="slicesReduced" type="integer" optional="true" />
+          <nano:extend name="slicesNotVerified" type="integer" optional="true" />
+          <nano:extend name="deviationsRaised" type="integer" optional="true" />
+          <nano:extend name="deviationsUnraised" type="integer" optional="true" />
+          <nano:extend name="hasDeviations" type="boolean" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+        </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="Epic complete">
@@ -26,6 +38,29 @@
         </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_start</bpmn:incoming>
+      <bpmn:outgoing>f_toConformance</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="conformance" name="Verify implementation vs spec (agent)">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:conformance" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="conformance.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+        </zeebe:linkedResources>
+        <zeebe:ioMapping>
+          <zeebe:input source="=conformanceDigest" target="appendPrompt" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toConformance</bpmn:incoming>
+      <bpmn:outgoing>f_toRecordConformance</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="record-conformance" name="Record conformance">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.conformance-record" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ConformanceRecordIn" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toRecordConformance</bpmn:incoming>
       <bpmn:outgoing>f_toSynthesize</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="synthesize" name="Synthesize &#38; promote (agent)">
@@ -55,7 +90,9 @@
       <bpmn:incoming>f_toEnd</bpmn:incoming>
     </bpmn:endEvent>
     <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="gather" />
-    <bpmn:sequenceFlow id="f_toSynthesize" sourceRef="gather" targetRef="synthesize" />
+    <bpmn:sequenceFlow id="f_toConformance" sourceRef="gather" targetRef="conformance" />
+    <bpmn:sequenceFlow id="f_toRecordConformance" sourceRef="conformance" targetRef="record-conformance" />
+    <bpmn:sequenceFlow id="f_toSynthesize" sourceRef="record-conformance" targetRef="synthesize" />
     <bpmn:sequenceFlow id="f_toRecord" sourceRef="synthesize" targetRef="record" />
     <bpmn:sequenceFlow id="f_toEnd" sourceRef="record" targetRef="End" />
   </bpmn:process>
@@ -70,34 +107,48 @@
       <bpmndi:BPMNShape id="BPMNShape_gather" bpmnElement="gather">
         <dc:Bounds x="216" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
+      <bpmndi:BPMNShape id="BPMNShape_conformance" bpmnElement="conformance">
         <dc:Bounds x="416" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
+      <bpmndi:BPMNShape id="BPMNShape_record-conformance" bpmnElement="record-conformance">
         <dc:Bounds x="616" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
+        <dc:Bounds x="816" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
+        <dc:Bounds x="1016" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="816" y="102" width="36" height="36" />
+        <dc:Bounds x="1216" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="794" y="143" width="80" height="14" />
+          <dc:Bounds x="1194" y="143" width="80" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
         <di:waypoint x="116" y="120" />
         <di:waypoint x="216" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toSynthesize" bpmnElement="f_toSynthesize">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toConformance" bpmnElement="f_toConformance">
         <di:waypoint x="316" y="120" />
         <di:waypoint x="416" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecordConformance" bpmnElement="f_toRecordConformance">
         <di:waypoint x="516" y="120" />
         <di:waypoint x="616" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toSynthesize" bpmnElement="f_toSynthesize">
         <di:waypoint x="716" y="120" />
         <di:waypoint x="816" y="120" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
+        <di:waypoint x="916" y="120" />
+        <di:waypoint x="1016" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
+        <di:waypoint x="1116" y="120" />
+        <di:waypoint x="1216" y="120" />
+      </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>
   </bpmndi:BPMNDiagram>
 </bpmn:definitions>

package/resources/prompts/conformance.md

@@ -0,0 +1,105 @@
+# Conformance agent — verify the implementation against the spec, by reading the code
+
+You are the **spec-conformance agent**. An epic (a fan-out `plan`) has finished — every one of its
+slices has reached a terminal state and the landed PRs are now in the tree. Your job is to answer a
+single, evidence-based question for a human:
+
+> **Did we actually build what the spec asked for — no more, no less?**
+
+You are NOT the retro agent (that one distils lessons). You are the auditor. Crucially, **you verify
+against the real implementation, not against what the agents claimed.** Transcripts, `learning`
+notes, and even a slice's own status can be optimistic or wrong. The diff cannot. Read the code.
+
+## Input
+
+The job payload (stdin JSON) carries:
+
+- `variables.planKey` — the epic's key, e.g. `owner/repo#123`.
+- `variables.repo` — the **target repo** `owner/repo` the work landed in.
+- `variables.issueUrl` — the epic's source issue. **This issue body is the SPEC.**
+- **`variables.conformanceDigest`** — appended below the `---` separator: the spec broken into
+  slices (each slice's planner-supplied `prompt` is its acceptance brief), the list of **delivered
+  PRs** you must examine, and the deviations that were **raised** during implementation
+  (`scope-change` entries). This tells you *what to check* and *where to look* — it does NOT tell
+  you the answer.
+
+You have `gh` / git authenticated for the target repository.
+
+## What to do
+
+1. **Read the spec.** `gh issue view <n> --repo <repo>` for the epic issue body, plus every slice's
+   `prompt` in the digest. Together these are the acceptance criteria you are auditing against.
+2. **Examine the ACTUAL implementation.** For every delivered PR in the digest:
+   `gh pr diff <n> --repo <repo>`, and read the touched source and tests (clone/checkout if you
+   need to navigate). Do not trust the PR description — read what the code does.
+3. **Distinguish real delivery from the appearance of it.** This is the whole point of examining
+   code. For each spec item, decide whether it is *load-bearing* in the shipped system:
+   - Is the new code actually **wired in / reachable**, or is it a dead entrypoint behind a flag,
+     a stub, or a synthetic path nothing calls?
+   - Do the **tests exercise the real behaviour**, or are they asserting on mocks/gated paths so
+     they pass without proving the feature works?
+   - Was the item delivered **in full**, or narrowed to a subset while looking complete?
+4. **Assign each spec item an acceptance verdict**, with a one-line evidence pointer (file / PR /
+   test) for each:
+   - **met** — delivered as specified, wired in, and genuinely tested.
+   - **met-in-unit-only** — implemented and unit-tested, but not proven wired into the live system.
+   - **reduced** — delivered in a narrower form than the spec asked for.
+   - **not-verified** — you could not confirm it from the implementation (missing, stubbed, dead
+     code, or tests that don't actually exercise it).
+5. **Reconcile the raised deviations.** For each `scope-change` entry in the digest, confirm the
+   code matches what was said, and note it as a **raised** deviation.
+6. **Hunt for UNRAISED deviations** — things the code does that the spec did *not* ask for, or spec
+   items silently dropped, that were **never** flagged on the blackboard. These are the most
+   valuable finding: scope drift nobody surfaced.
+7. **Post the conformance report as a comment on the epic issue**
+   (`gh issue comment <n> --repo <repo> --body-file <file>`). Structure it: a one-line verdict, a
+   per-item table (item → verdict → evidence), the raised deviations, and the unraised deviations.
+   Be specific and cite files/PRs — this comment is the deliverable a human reads.
+
+## Do not
+
+- Do **not** open, modify, or merge any PR. You audit; you do not remediate. (A later stage decides
+  whether a finding warrants a follow-up task.)
+- Do **not** soften a `not-verified` into a `met` because the transcript sounded confident. Absence
+  of evidence in the code is `not-verified`.
+- Do **not** manufacture deviations to look thorough. A clean epic that fully met its spec is a
+  perfectly good — and common — result.
+
+## Output contract
+
+Write a JSON object of **result variables** to the file named by the `AGENT_RESULT_FILE`
+environment variable:
+
+```json
+{
+  "status": "filed",
+  "commentUrl": "https://github.com/owner/repo/issues/123#issuecomment-456",
+  "slicesMet": 4,
+  "slicesReduced": 1,
+  "slicesNotVerified": 1,
+  "deviationsRaised": 2,
+  "deviationsUnraised": 1,
+  "hasDeviations": true,
+  "summary": "6 items: 4 met, 1 reduced (auth rate-limit narrowed to per-IP), 1 not-verified (webhook retry path is dead code). 2 raised + 1 unraised deviation (added a /debug route not in spec)."
+}
+```
+
+Rules:
+
+- `status` — one of:
+  - `filed` — you examined the implementation and posted the report comment. Set `commentUrl`.
+  - `skipped` — there was no landed implementation to examine (nothing shipped). Explain in
+    `summary`; omit the counts.
+  - `blocked` — you could not proceed (e.g. no read access, could not fetch a PR). Explain in
+    `summary`.
+- `commentUrl` — the URL of the report comment you posted on the epic issue, for `filed`.
+- `slicesMet` / `slicesReduced` / `slicesNotVerified` — integer counts of your per-item verdicts
+  (count `met-in-unit-only` under `slicesReduced`, since it is not full live delivery).
+- `deviationsRaised` — count of `scope-change` deviations you reconciled.
+- `deviationsUnraised` — count of deviations you found that were never flagged.
+- `hasDeviations` — `true` when anything is reduced / not-verified / an unraised deviation exists;
+  i.e. the epic did not cleanly meet its spec. A later stage uses this to decide escalation.
+- `summary` — a short human-readable verdict.
+
+You are advisory and post-merge: you gate no delivery. Your value is an honest, code-grounded
+account of what shipped versus what was asked — surface it plainly, and let the humans act on it.

package/resources/prompts/retro.md

@@ -10,6 +10,11 @@ so the *next* fleet — and human contributors — never re-learn it the hard wa
 You are the mechanism that lifts a lesson from "a thing one agent happened to hit" to "a thing the
 repo now tells everyone up front."
 
+> **Scope:** a separate **conformance** agent runs before you and audits whether the epic met its
+> spec (posting its own report on the epic issue). That is *not* your job — do **not** re-verify
+> acceptance or re-litigate scope here. Focus purely on distilling reusable **lessons** and
+> promoting them into the repo.
+
 ## Input
 
 The job payload (stdin JSON) carries:

package/test/worldDb.ts

@@ -89,15 +89,27 @@ function openDataSource(db: DatabaseSync): MemDataSource {
   return ds;
 }
 
-/** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
-export function memWorldData(): { data: DataLayer; db: DatabaseSync } {
+/** A `DataLayer` stub over a fresh in-memory db with the given migration files applied (in order).
+ * The generic factory behind {@link memWorldData} — reused by tests that need a different durable
+ * table (e.g. `worker_durable_resume`, migration 052) without re-authoring the gateway/tx shim. */
+export function memDataFor(migrationFiles: readonly string[]): { data: DataLayer; db: DatabaseSync } {
   const db = new DatabaseSync(":memory:");
   openDbs.add(db);
-  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/049_world_checkpoint.sql", import.meta.url)), "utf8");
-  db.exec(sql);
+  // SQLite disables FK enforcement by default; enable it so migrations with foreign keys are
+  // exercised (and FK violations surface) exactly as the migration-specific tests do.
+  db.exec("PRAGMA foreign_keys = ON;");
+  for (const file of migrationFiles) {
+    const sql = readFileSync(fileURLToPath(new URL(`../db/migrations/${file}`, import.meta.url)), "utf8");
+    db.exec(sql);
+  }
   const data = {
     table: (name: string, pk = "id") => gateway(db, name, pk),
     open: () => openDataSource(db),
   } as unknown as DataLayer;
   return { data, db };
 }
+
+/** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
+export function memWorldData(): { data: DataLayer; db: DatabaseSync } {
+  return memDataFor(["049_world_checkpoint.sql"]);
+}

package/workers/conformance-record/worker.test.ts

@@ -0,0 +1,199 @@
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+function fakeApp() {
+  const stores: Record<string, any[]> = { plan_conformance: [] };
+  const seq: Record<string, number> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async insert(row: any) {
+        const id = (seq[name] = (seq[name] ?? 0) + 1);
+        rows.push(pk === "id" ? { id, ...row } : { ...row });
+        return pk === "id" ? id : row[pk];
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async findOne(where: any = {}) {
+        return rows.find((r) => match(r, where));
+      },
+      async get(id: any) {
+        return rows.find((row) => row[pk] === id);
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: noopLog() };
+  return { app, stores };
+}
+
+test("conformance-record: persists a filed conformance from hoisted result vars", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    {
+      variables: {
+        planKey: "o/r#5",
+        status: "filed",
+        commentUrl: "https://github.com/o/r/issues/5#issuecomment-1",
+        slicesMet: 4,
+        slicesReduced: 1,
+        slicesNotVerified: 1,
+        deviationsRaised: 2,
+        deviationsUnraised: 1,
+        hasDeviations: true,
+        summary: "6 items, 4 met",
+        "io.nanobpm.agentResult": { output: "the full conformance report" },
+      },
+    } as any,
+    app as any,
+  );
+
+  assertEquals(stores.plan_conformance.length, 1);
+  const row = stores.plan_conformance[0];
+  assertEquals(row.status, "filed");
+  assertEquals(row.comment_url, "https://github.com/o/r/issues/5#issuecomment-1");
+  assertEquals(row.slices_met, 4);
+  assertEquals(row.slices_reduced, 1);
+  assertEquals(row.slices_not_verified, 1);
+  assertEquals(row.deviations_raised, 2);
+  assertEquals(row.deviations_unraised, 1);
+  assertEquals(row.has_deviations, 1);
+  assertEquals(row.report, "the full conformance report");
+});
+
+test("conformance-record: derives has_deviations from ground truth even when the agent flag is absent", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { variables: { planKey: "o/r#6", status: "filed", commentUrl: "https://x/6#c", slicesNotVerified: 1 } } as any,
+    app as any,
+  );
+  // The agent didn't set hasDeviations, but a not-verified item means the epic didn't cleanly meet spec.
+  assertEquals(stores.plan_conformance[0].has_deviations, 1);
+});
+
+test("conformance-record: a clean epic records has_deviations = 0", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { variables: { planKey: "o/r#7", status: "filed", commentUrl: "https://x/7#c", slicesMet: 3, hasDeviations: false } } as any,
+    app as any,
+  );
+  assertEquals(stores.plan_conformance[0].has_deviations, 0);
+  assertEquals(stores.plan_conformance[0].slices_met, 3);
+});
+
+test("conformance-record: coerces filed without a comment URL to skipped", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { variables: { planKey: "o/r#8", status: "filed", summary: "forgot to post" } } as any,
+    app as any,
+  );
+  assertEquals(stores.plan_conformance[0].status, "skipped");
+  assertEquals(stores.plan_conformance[0].comment_url, null);
+});
+
+test("conformance-record: a non-filed status carries no verdict counts or deviations", async () => {
+  const { app, stores } = fakeApp();
+  // A "filed" that downgrades to skipped (no comment) must not persist the agent's counts /
+  // has_deviations — a skipped/blocked audit produced no verified verdict, so the row would be
+  // internally inconsistent (status=skipped yet has_deviations=1 with non-zero counts).
+  await handler(
+    {
+      variables: {
+        planKey: "o/r#11",
+        status: "filed",
+        slicesMet: 4,
+        slicesReduced: 1,
+        slicesNotVerified: 1,
+        deviationsRaised: 2,
+        deviationsUnraised: 1,
+        hasDeviations: true,
+        summary: "audit ran but never posted",
+        "io.nanobpm.agentResult": { output: "transcript explaining why" },
+      },
+    } as any,
+    app as any,
+  );
+  const row = stores.plan_conformance[0];
+  assertEquals(row.status, "skipped");
+  assertEquals(row.slices_met, 0);
+  assertEquals(row.slices_reduced, 0);
+  assertEquals(row.slices_not_verified, 0);
+  assertEquals(row.deviations_raised, 0);
+  assertEquals(row.deviations_unraised, 0);
+  assertEquals(row.has_deviations, 0);
+  // summary + report are human-readable context — retained so a skipped/blocked row still explains itself.
+  assertEquals(row.summary, "audit ran but never posted");
+  assertEquals(row.report, "transcript explaining why");
+});
+
+test("conformance-record: coerces string-encoded numeric counts hoisted by the agent", async () => {
+  const { app, stores } = fakeApp();
+  // The agentTask runner hoists result-JSON keys as-is; an agent may emit counts as strings ("1").
+  // These must be parsed, not silently coerced to 0 (which would wrongly clear the verdict).
+  await handler(
+    {
+      variables: {
+        planKey: "o/r#12",
+        status: "filed",
+        commentUrl: "https://x/12#c",
+        slicesMet: "4",
+        slicesReduced: "1",
+        slicesNotVerified: "0",
+        deviationsRaised: "2",
+        deviationsUnraised: "0",
+        hasDeviations: false,
+      },
+    } as any,
+    app as any,
+  );
+  const row = stores.plan_conformance[0];
+  assertEquals(row.slices_met, 4);
+  assertEquals(row.slices_reduced, 1);
+  assertEquals(row.deviations_raised, 2);
+  // A reduced item is ground truth for a deviation even though the agent's flag was false.
+  assertEquals(row.has_deviations, 1);
+});
+
+test("conformance-record: honours a string-encoded hasDeviations flag", async () => {
+  const { app, stores } = fakeApp();
+  // A clean epic (no reduced / not-verified / unraised) where the agent emits hasDeviations as the
+  // string "true" must still record a deviation — a stringified boolean can't silently be dropped.
+  await handler(
+    {
+      variables: {
+        planKey: "o/r#13",
+        status: "filed",
+        commentUrl: "https://x/13#c",
+        slicesMet: 3,
+        hasDeviations: "true",
+      },
+    } as any,
+    app as any,
+  );
+  assertEquals(stores.plan_conformance[0].has_deviations, 1);
+});
+
+test("conformance-record: honours an explicit blocked status", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { variables: { planKey: "o/r#9", status: "blocked", summary: "no read access" } } as any,
+    app as any,
+  );
+  assertEquals(stores.plan_conformance[0].status, "blocked");
+});
+
+test("conformance-record: defaults to skipped when the agent reported nothing", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { variables: { planKey: "o/r#10", summary: "nothing shipped" } } as any,
+    app as any,
+  );
+  assertEquals(stores.plan_conformance[0].status, "skipped");
+});