@nanobpm/nano-workforce 0.162.2 → 0.163.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.163.0](https://github.com/nanobpm/nano-workforce/compare/v0.162.2...v0.163.0) (2026-08-30)
+
+### Features
+
+* **reconcile:** engine-reset reconciliation surface for inflight work ([#622](https://github.com/nanobpm/nano-workforce/issues/622)) ([#627](https://github.com/nanobpm/nano-workforce/issues/627)) ([a10ba65](https://github.com/nanobpm/nano-workforce/commit/a10ba650829b15228e35eb45f08ecef98eff69d8)), closes [Magikcraft/nano-bpm#1065](https://github.com/Magikcraft/nano-bpm/issues/1065)
+
 ## [0.162.2](https://github.com/nanobpm/nano-workforce/compare/v0.162.1...v0.162.2) (2026-08-30)
 
 ### Bug Fixes

package/app/enginePreflight.ts

@@ -56,7 +56,21 @@ export function resolveEngineAddress(
  * stock Camunda 8 gateway, which returns the same shape without it.
  */
 export interface TopologyProbe {
-  nano?: { engine?: string; version?: string; falconPath?: string } | null;
+  nano?:
+    | {
+        engine?: string;
+        version?: string;
+        falconPath?: string;
+        /** Monotonic incarnation / epoch id the engine stamps at boot and re-mints on a
+         *  reset/restore/rewind (companion to the versioned snapshot envelope,
+         *  Magikcraft/nano-bpm#1068). The app persists the last-seen value; a REGRESSION is the
+         *  robust "engine was reset → reconcile" signal (issue #622, app/reconcile.ts). */
+        incarnation?: number | string;
+        /** Alias for {@link incarnation} — accepted so the app tolerates either spelling the engine
+         *  status endpoint settles on without a code change. */
+        epoch?: number | string;
+      }
+    | null;
   gatewayVersion?: string;
 }
 

package/app/instanceTracking.ts

@@ -63,6 +63,23 @@ export function activeStatusesFor(table: string): readonly string[] {
   return binding.activeStatuses;
 }
 
+/** A tracked table's engine-instance key column (the `keyField` in nano.app.json — e.g.
+ *  `process_key`), the single source of truth the app-side reconcile probes/orphans by so it can
+ *  never drift from the reconciler's notion of "which column holds the engine instance key". */
+export function keyFieldFor(table: string): string {
+  return trackingBindingFor(table).keyField;
+}
+
+/** Every `instanceTracking` binding — the full registry of ENGINE-BACKED base tables (each row is
+ *  projected off a live engine process instance keyed by `keyField`). The app-side engine-reset
+ *  reconcile (app/reconcile.ts) scans exactly this set: a row whose `statusField` is still in the
+ *  binding's `activeStatuses` and whose `keyField` is populated is non-terminal engine-backed work,
+ *  the only surface reconcile may drive to `orphaned`. Terminal rows and non-engine-backed surfaces
+ *  (presence, append-only audit) are, by construction, not in this set and are never touched. */
+export function engineBackedBindings(): readonly InstanceTracking[] {
+  return INSTANCE_TRACKING_BINDINGS;
+}
+
 /** The managed derived read-model VIEW name + effective-status column for a base table, resolved by
  *  urban's OWN target resolver so the app never drifts from the framework's `<table>__tracking` /
  *  `derived_status` naming (ADR 0065). */

package/app/reconcile.test.ts

@@ -0,0 +1,212 @@
+// Red/green coverage for the app-side engine-reset reconciliation surface (issue #622).
+//
+// The core scenario the incident (Magikcraft/nano-bpm#1065) demanded a supported remedy for: the
+// engine is reset and its incarnation epoch REGRESSES, while `app.db` still projects engine-backed
+// inflight work (an active `feature_runs`/`delivery_graph_runs`/… row keyed on a now-dead
+// `process_key`). Reconcile must drive exactly those rows to the defined `orphaned` terminal WITH
+// PROVENANCE, leave terminal history + non-engine-backed rows untouched, and be idempotent.
+//
+// These run against the REAL migration set (092 applied to an in-memory SQLite via urban's own
+// `makeGateway`), so the tables/columns/indexes reconcile reads and writes are the shipping schema.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { freshData } from "../test/reconcileDb.ts";
+import {
+  ORPHANED_STATUS,
+  parseEngineEpoch,
+  RECONCILE_ORPHAN_REASON,
+  reconcileEngineBackedWork,
+} from "./reconcile.ts";
+
+const AT = () => new Date("2026-02-02T00:00:00.000Z");
+
+function seedFeatureRun(raw: DatabaseSync, key: string, status: string, processKey: string | null): void {
+  raw
+    .prepare(
+      `INSERT INTO feature_runs (feature_key, repo, issue_number, issue_url, base_branch, status, process_key, created_at, updated_at)
+       VALUES (?, 'o/r', 1, 'https://x', 'main', ?, ?, '2026-01-01', '2026-01-01')`,
+    )
+    .run(key, status, processKey);
+}
+
+function seedDeliveryGraphRun(raw: DatabaseSync, runKey: string, status: string, processKey: string | null): void {
+  raw
+    .prepare(
+      `INSERT INTO delivery_graph_runs (run_key, process_key, digest, status, created_at, updated_at)
+       VALUES (?, ?, 'deadbeef', ?, '2026-01-01', '2026-01-01')`,
+    )
+    .run(runKey, processKey, status);
+}
+
+test("parseEngineEpoch reads nano.incarnation (or its epoch alias), else null", () => {
+  assertEquals(parseEngineEpoch({ nano: { incarnation: 7 } }), 7);
+  assertEquals(parseEngineEpoch({ nano: { epoch: "9" } }), 9);
+  assertEquals(parseEngineEpoch({ nano: { engine: "nano" } }), null);
+  assertEquals(parseEngineEpoch({ gatewayVersion: "8.6" }), null);
+  assertEquals(parseEngineEpoch(null), null);
+});
+
+test("first observation SEEDS the epoch without orphaning anything", async () => {
+  const { data, raw } = freshData();
+  seedFeatureRun(raw, "o/r#1", "running", "pk-1");
+
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 5 }, { now: AT, runId: "run-seed" });
+
+  assertEquals(res.reason, "seed-epoch");
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(row.status, "running");
+  const rec = raw.prepare("SELECT epoch FROM engine_incarnation WHERE id=1").get() as { epoch: number };
+  assertEquals(rec.epoch, 5);
+});
+
+test("RED→GREEN: an epoch regression orphans dangling inflight rows with provenance", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+  seedDeliveryGraphRun(raw, "graph-1", "running", "77");
+
+  // The engine was reset/rewound: its incarnation epoch regressed 10 → 2.
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(res.reason, "epoch-regression");
+  assertEquals(res.orphanedCount, 2);
+
+  const fr = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(fr.status, ORPHANED_STATUS);
+  const dg = raw.prepare("SELECT status FROM delivery_graph_runs WHERE run_key='graph-1'").get() as { status: string };
+  assertEquals(dg.status, ORPHANED_STATUS);
+
+  const prov = raw
+    .prepare("SELECT * FROM reconcile_provenance WHERE source_table='feature_runs'")
+    .get() as Record<string, unknown>;
+  assertEquals(prov.to_status, ORPHANED_STATUS);
+  assertEquals(prov.from_status, "running");
+  assertEquals(prov.reason, RECONCILE_ORPHAN_REASON);
+  assertEquals(prov.observed_epoch, 2);
+  assertEquals(prov.run_id, "run-1");
+  assertEquals(prov.key_value, "41");
+
+  const run = raw.prepare("SELECT reason, orphaned_count FROM reconcile_runs WHERE run_id='run-1'").get() as {
+    reason: string;
+    orphaned_count: number;
+  };
+  assertEquals(run.reason, "epoch-regression");
+  assertEquals(run.orphaned_count, 2);
+  const rec = raw.prepare("SELECT epoch FROM engine_incarnation WHERE id=1").get() as { epoch: number };
+  assertEquals(rec.epoch, 2);
+});
+
+test("terminal history and rows without a process_key are NEVER touched", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "term#1", "merged", "88"); // terminal — not in activeStatuses
+  seedFeatureRun(raw, "await#1", "opened", "89"); // terminal-for-tracking
+  seedFeatureRun(raw, "nokeed#1", "running", null); // active but no engine key
+
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(res.orphanedCount, 0);
+  const statuses = raw.prepare("SELECT feature_key, status FROM feature_runs ORDER BY feature_key").all() as {
+    feature_key: string;
+    status: string;
+  }[];
+  assertEquals(statuses.find((r) => r.feature_key === "term#1")?.status, "merged");
+  assertEquals(statuses.find((r) => r.feature_key === "await#1")?.status, "opened");
+  assertEquals(statuses.find((r) => r.feature_key === "nokeed#1")?.status, "running");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+test("idempotent: a second pass with a matching epoch is a no-op", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+
+  const first = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+  assertEquals(first.orphanedCount, 1);
+
+  const second = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-2" });
+  assertEquals(second.reason, "no-op");
+  assertEquals(second.orphanedCount, 0);
+
+  const provCount = raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number };
+  assertEquals(provCount.c, 1);
+});
+
+test("an unreachable engine is a hard no-op — live work is never orphaned", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+
+  const res = await reconcileEngineBackedWork(data, { reachable: false, epoch: null }, { now: AT, runId: "run-1" });
+  assertEquals(res.reason, "engine-unreachable");
+  assertEquals(res.orphanedCount, 0);
+
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(row.status, "running");
+  const run = raw.prepare("SELECT reason FROM reconcile_runs WHERE run_id='run-1'").get() as { reason: string };
+  assertEquals(run.reason, "engine-unreachable");
+});
+
+test("RED→GREEN: a concurrent terminal transition wins — the guarded UPDATE never clobbers it", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+
+  // Interpose a writer that flips the row to a newer terminal status AFTER reconcile has SELECTed it
+  // as "running" but BEFORE its UPDATE lands — the exact TOCTOU window. With a blind UPDATE-by-pk the
+  // reset would clobber `merged` back to `orphaned` (and write provenance); the guarded UPDATE (status
+  // re-asserted) sees `res.changed === 0` and leaves the terminal history untouched.
+  const gw = data.open();
+  let raced = false;
+  const wrapTx = (t: { query: (...a: unknown[]) => unknown; exec: (sql: string, params?: unknown[]) => unknown }) => ({
+    query: (...a: unknown[]) => t.query(...a),
+    exec: (sql: string, params?: unknown[]) => {
+      if (!raced && /^UPDATE/.test(sql.trim())) {
+        raced = true;
+        raw.prepare("UPDATE feature_runs SET status='merged' WHERE feature_key='o/r#1'").run();
+      }
+      return t.exec(sql, params);
+    },
+  });
+  const wrappedSrc = {
+    query: (...a: unknown[]) => (gw as { query: (...a: unknown[]) => unknown }).query(...a),
+    exec: (sql: string, params?: unknown[]) => (gw as { exec: (sql: string, params?: unknown[]) => unknown }).exec(sql, params),
+    tx: (fn: (t: unknown) => unknown) => (gw as { tx: (f: (t: unknown) => unknown) => unknown }).tx((t) => fn(wrapTx(t as never))),
+  };
+  const wrapped = { open: () => wrappedSrc } as unknown as DataLayer;
+
+  const res = await reconcileEngineBackedWork(wrapped, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(raced, true);
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(row.status, "merged");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+test("RED→GREEN: orphaning stamps updated_at so the transition timestamp isn't left stale", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+  seedDeliveryGraphRun(raw, "graph-1", "running", "77");
+
+  // The seeded rows carry updated_at='2026-01-01'; AT() (the reconcile clock) is 2026-02-02. A blind
+  // `SET status='orphaned'` would leave updated_at at the stale seed value, misrepresenting when the
+  // row was orphaned to the UI/audits. The transition must refresh updated_at like every other one.
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(res.orphanedCount, 2);
+  const at = AT().toISOString();
+  const fr = raw
+    .prepare("SELECT status, updated_at FROM feature_runs WHERE feature_key='o/r#1'")
+    .get() as { status: string; updated_at: string };
+  assertEquals(fr.status, ORPHANED_STATUS);
+  assertEquals(fr.updated_at, at);
+  const dg = raw
+    .prepare("SELECT status, updated_at FROM delivery_graph_runs WHERE run_key='graph-1'")
+    .get() as { status: string; updated_at: string };
+  assertEquals(dg.status, ORPHANED_STATUS);
+  assertEquals(dg.updated_at, at);
+});

package/app/reconcile.ts

@@ -0,0 +1,326 @@
+// nano-workforce — the app-side engine-reset reconciliation surface (issue #622).
+//
+// When the Nano engine is reset, restored, or rolled to an incarnation whose key generator has
+// rewound (Magikcraft/nano-bpm#1065), `app.db` keeps projecting ENGINE-BACKED inflight work that no
+// longer exists on the engine: open user tasks pointing at dead instances, active runs keyed on a
+// `process_key` the fresh engine has re-minted for something unrelated (the release-train run
+// recorded `process_key=41`; the fresh engine re-minted 41 for an unrelated probe). Without a
+// supported way to converge, the app silently trusts stale projections — orphaned human gates and
+// key-collision identity confusion.
+//
+// `reconcile` is the first-class remedy. It runs ON STARTUP (main.ts) and ON DEMAND (the
+// `reconcileEngineState` operator command), scoped NARROWLY to claimed inflight work:
+//
+//   • Detection — engine INCARNATION EPOCH (preferred over fragile per-key 404 probing). The engine
+//     stamps a monotonic incarnation id at boot and exposes it on `/v2/topology`; the app persists
+//     the last-seen value (`engine_incarnation`). An epoch REGRESSION (observed < recorded) — the
+//     #1065 rewind signature — or its absence where one was recorded means "engine was reset/rewound
+//     → reconcile", ONE cheap check instead of N per-instance probes.
+//   • Convergence — for every NON-terminal, engine-backed app row (a nano.app.json instanceTracking
+//     binding whose `statusField` is still in its `activeStatuses` set and whose `keyField` is
+//     populated), drive the row to the defined `orphaned` terminal WITH PROVENANCE
+//     (`reconcile_provenance`: the reason, the observed engine epoch, and the reconcile run id) —
+//     instead of trusting a stale projection or silently dropping data.
+//   • Guardrails — TERMINAL rows (done/failed/merged/abandoned/…) and append-only / non-engine-backed
+//     surfaces (presence, audit, provenance) are NEVER mutated: reconcile only touches rows whose
+//     status is in a binding's `activeStatuses`. Every pass is recorded in `reconcile_runs`.
+//   • Idempotent — a second pass with a matching epoch is a no-op (nothing regressed, and every
+//     already-orphaned row has left its `activeStatuses`, so it is not re-scanned). An UNREACHABLE
+//     engine is a no-op too: reconcile NEVER orphans when it could not confirm a reset (a 401/5xx or
+//     a network error yields `reachable:false`, not a false "engine missing").
+//
+// The provenance is app-owned (not urban's `_urban_write_provenance`, which is a domain-free
+// insert-join sidecar written only inside a job): reconcile runs at boot / over HTTP, outside any
+// job, and needs to record the REASON + epoch + run id — which the app-owned `reconcile_provenance`
+// table carries, and the existing `app.db` backup convention makes the whole mutation reversible.
+
+import type { DataLayer, GatewayDataSource as DataSource } from "@nanobpm/urban";
+import type { TopologyProbe } from "./enginePreflight.ts";
+import { activeStatusesFor, baseStatusFieldFor, engineBackedBindings, keyFieldFor } from "./instanceTracking.ts";
+
+/** The defined terminal state a reset-orphaned engine-backed row is driven to. Deliberately DISTINCT
+ *  from a binding's natural terminal (`abandoned`/`failed`/…) so an operator can tell a row that was
+ *  orphaned by an engine reset apart from one that drained normally. Not in any binding's
+ *  `activeStatuses`, so an orphaned row is never re-scanned (idempotency) nor re-polled by the urban
+ *  instance-tracking reconciler. */
+export const ORPHANED_STATUS = "orphaned";
+
+/** The provenance reason stamped on every orphaned transition: the engine was reset/rewound and the
+ *  recorded incarnation epoch regressed (the #1065 signature). */
+export const RECONCILE_ORPHAN_REASON = "engine-reset/epoch-regression";
+
+/** The single-row epoch ledger + its append-only run/provenance sidecars (migration 092). */
+const INCARNATION_TABLE = "engine_incarnation";
+const RUNS_TABLE = "reconcile_runs";
+const PROVENANCE_TABLE = "reconcile_provenance";
+/** The conventional last-touched timestamp column stamped on every status transition; orphaning
+ *  refreshes it too, but only on the tables that actually declare it (introspected per binding). */
+const UPDATED_AT_COLUMN = "updated_at";
+
+/** What a `/v2/topology` epoch probe observed. `reachable:false` means the engine could not be
+ *  confirmed (network error, or a non-2xx like 401/5xx) — reconcile then does NOTHING, so a
+ *  transient outage can never be mistaken for a reset and orphan live work. `reachable:true` with a
+ *  null `epoch` means the engine answered but exposes no incarnation id (e.g. a stock Camunda 8
+ *  gateway, or before Magikcraft/nano-bpm#1068 ships). That null is a no-op ONLY when no epoch was
+ *  ever recorded; if a concrete epoch WAS recorded, a now-null observation reads as a regression
+ *  ("the epoch disappeared" — the reset signature), so reconcile orphans inflight work. See the
+ *  decision table on {@link reconcileEngineBackedWork}. */
+export interface EngineEpochObservation {
+  reachable: boolean;
+  epoch: number | null;
+}
+
+/** Why a reconcile pass acted (or did not). */
+export type ReconcileReason = "epoch-regression" | "seed-epoch" | "no-op" | "engine-unreachable";
+
+/** One orphaned engine-backed row. */
+export interface OrphanedRow {
+  table: string;
+  pk: string;
+  key: string | null;
+  fromStatus: string;
+}
+
+/** The outcome of one reconcile pass — the same shape the run row records and the operator command
+ *  returns. */
+export interface ReconcileResult {
+  runId: string;
+  reason: ReconcileReason;
+  observedEpoch: number | null;
+  recordedEpoch: number | null;
+  orphanedCount: number;
+  orphaned: OrphanedRow[];
+}
+
+export interface ReconcileLog {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+export interface ReconcileOptions {
+  /** Injectable clock (defaults to `Date`), so tests are deterministic. */
+  now?: () => Date;
+  /** Injectable run id (defaults to a random UUID). */
+  runId?: string;
+  /** The data source name to reconcile (defaults to the DataLayer's default source). */
+  sourceName?: string;
+  log?: ReconcileLog;
+}
+
+/** Read the incarnation epoch out of a `/v2/topology` body — `nano.incarnation` (or its `epoch`
+ *  alias), coerced from a number or a numeric string. Any other shape (absent, non-numeric) yields
+ *  null: "the engine exposes no epoch". A null is a no-op ONLY when no epoch was previously recorded;
+ *  when one WAS recorded, reconcile reads a now-null observation as a regression ("epoch disappeared"),
+ *  not a no-op — see the decision table on {@link reconcileEngineBackedWork}. */
+export function parseEngineEpoch(body: TopologyProbe | null | undefined): number | null {
+  const raw = body?.nano?.incarnation ?? body?.nano?.epoch;
+  if (raw == null) return null;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Probe `/v2/topology` for the engine incarnation epoch. Never throws: a network error or a non-2xx
+ *  yields `reachable:false` (reconcile then does nothing), so an outage can never orphan live work. */
+export async function probeEngineEpoch(
+  restAddress: string,
+  opts: { token?: string; fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<EngineEpochObservation> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${restAddress.replace(/\/+$/, "")}/topology`;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+  try {
+    const res = await fetchImpl(url, {
+      headers,
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 3000),
+    });
+    if (!res.ok) return { reachable: false, epoch: null };
+    const body: TopologyProbe = await res.json();
+    return { reachable: true, epoch: parseEngineEpoch(body) };
+  } catch {
+    return { reachable: false, epoch: null };
+  }
+}
+
+/** Double-quote a SQL identifier (table/column) so a manifest-declared name is safe to interpolate. */
+function q(id: string): string {
+  return `"${id.replace(/"/g, '""')}"`;
+}
+
+/** The schema of `table` we need to orphan a row: its primary-key column (the first `pk`-flagged
+ *  column from `PRAGMA table_info`, or `rowid` when the table declares none — so provenance always
+ *  records a stable row identity) and whether it carries an `updated_at` column to stamp. */
+async function tableShape(src: DataSource, table: string): Promise<{ pkCol: string; hasUpdatedAt: boolean }> {
+  const cols = await src.query<{ name: string; pk: number }>(`PRAGMA table_info(${q(table)})`);
+  const pk = cols.find((c) => Number(c.pk) > 0);
+  return { pkCol: pk?.name ?? "rowid", hasUpdatedAt: cols.some((c) => c.name === UPDATED_AT_COLUMN) };
+}
+
+/** The recorded last-seen epoch, or null when none was ever recorded (no row, or a null epoch). */
+async function readRecordedEpoch(src: DataSource): Promise<number | null> {
+  const rows = await src.query<{ epoch: number | null }>(
+    `SELECT epoch FROM ${INCARNATION_TABLE} WHERE id = 1`,
+  );
+  const epoch = rows.length ? rows[0].epoch : null;
+  return epoch == null ? null : Number(epoch);
+}
+
+/** Persist (seed or advance) the last-seen epoch. Only ever called with a concrete number, so a
+ *  recorded epoch always means "an epoch was actually observed". */
+async function persistEpoch(src: DataSource, epoch: number, at: string): Promise<void> {
+  await src.exec(
+    `INSERT INTO ${INCARNATION_TABLE} (id, epoch, observed_at) VALUES (1, ?, ?) ` +
+      `ON CONFLICT(id) DO UPDATE SET epoch = excluded.epoch, observed_at = excluded.observed_at`,
+    [epoch, at],
+  );
+}
+
+/** Orphan every NON-terminal, engine-backed row across all instanceTracking bindings, recording one
+ *  `reconcile_provenance` row per transition. Runs inside the caller's transaction. */
+async function orphanEngineBackedRows(
+  src: DataSource,
+  runId: string,
+  observedEpoch: number | null,
+  at: string,
+): Promise<OrphanedRow[]> {
+  const orphaned: OrphanedRow[] = [];
+  for (const binding of engineBackedBindings()) {
+    const table = binding.table;
+    // A binding with no active-status selector cannot classify "in-flight" — skip it rather than
+    // guess (activeStatusesFor would throw; we tolerate a selector-less binding).
+    if (!binding.activeStatuses?.length) continue;
+    const active = activeStatusesFor(table);
+    const statusField = baseStatusFieldFor(table);
+    const keyField = keyFieldFor(table);
+    const { pkCol, hasUpdatedAt } = await tableShape(src, table);
+    const placeholders = active.map(() => "?").join(", ");
+    const rows = await src.query<{ __pk: unknown; __key: unknown; __status: unknown }>(
+      `SELECT ${q(pkCol)} AS __pk, ${q(keyField)} AS __key, ${q(statusField)} AS __status ` +
+        `FROM ${q(table)} WHERE ${q(statusField)} IN (${placeholders}) AND ${q(keyField)} IS NOT NULL`,
+      [...active],
+    );
+    for (const row of rows) {
+      const pk = String(row.__pk);
+      const key = row.__key == null ? null : String(row.__key);
+      const fromStatus = String(row.__status);
+      // GUARDED update: re-assert the exact status we read AND a populated key, so a writer that
+      // flipped the row to a newer terminal status (or cleared its key) between the SELECT above and
+      // this UPDATE wins the race — we never clobber that terminal history back to `orphaned`. Only a
+      // row we actually transitioned (`res.changed > 0`) gets provenance and is counted. We also stamp
+      // `updated_at` (when the table has one) so the transition to `orphaned` refreshes the row's
+      // timestamp the same way every other status transition in the codebase does — leaving it stale
+      // would misrepresent the orphaning moment to the UI/audits.
+      const res = await src.exec(
+        `UPDATE ${q(table)} SET ${q(statusField)} = ?` +
+          (hasUpdatedAt ? `, ${q(UPDATED_AT_COLUMN)} = ?` : "") +
+          ` WHERE ${q(pkCol)} = ? AND ${q(statusField)} = ? AND ${q(keyField)} IS NOT NULL`,
+        hasUpdatedAt
+          ? [ORPHANED_STATUS, at, row.__pk, fromStatus]
+          : [ORPHANED_STATUS, row.__pk, fromStatus],
+      );
+      if (res.changed <= 0) continue;
+      await src.exec(
+        `INSERT INTO ${PROVENANCE_TABLE} ` +
+          `(run_id, source_table, pk_value, key_value, from_status, to_status, reason, observed_epoch, at) ` +
+          `VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [runId, table, pk, key, fromStatus, ORPHANED_STATUS, RECONCILE_ORPHAN_REASON, observedEpoch, at],
+      );
+      orphaned.push({ table, pk, key, fromStatus });
+    }
+  }
+  return orphaned;
+}
+
+/**
+ * Reconcile the app's engine-backed projections against one epoch observation. Pure of I/O beyond the
+ * data layer (the topology probe is {@link probeEngineEpoch}, injected as `observation`), so the
+ * red/green test drives it with a seeded row + a regressed epoch directly.
+ *
+ * Decision table (engine reachable):
+ *   • recorded != null AND (observed == null OR observed < recorded)  → REGRESSION: orphan inflight.
+ *   • recorded == null AND observed != null                          → SEED: first epoch learned.
+ *   • otherwise                                                       → NO-OP (incl. a matching epoch).
+ * The epoch is persisted whenever a concrete one was observed (seed, advance, or the fresh
+ * post-rewind incarnation), so the very next pass with that same epoch is a pure no-op.
+ *
+ * This surface is deliberately EPOCH-SCOPED: it only ever acts on the epoch signal. An engine that
+ * is reachable but exposes NO epoch and for which none was ever recorded (observed == null AND
+ * recorded == null) is, by contract, an intentional no-op — we have no reset signal to act on, and
+ * we never orphan live work speculatively. Converging engine-backed rows against an engine with no
+ * epoch support (e.g. via a per-instance existence probe) is out of contract for this surface.
+ */
+export async function reconcileEngineBackedWork(
+  data: DataLayer,
+  observation: EngineEpochObservation,
+  opts: ReconcileOptions = {},
+): Promise<ReconcileResult> {
+  const src = data.open(opts.sourceName);
+  const at = (opts.now?.() ?? new Date()).toISOString();
+  const runId = opts.runId ?? crypto.randomUUID();
+
+  // An unreachable engine is a hard no-op: we could not confirm a reset, so we NEVER orphan.
+  if (!observation.reachable) {
+    const recorded = await readRecordedEpoch(src);
+    await recordRun(src, { runId, at, observedEpoch: null, recordedEpoch: recorded, reason: "engine-unreachable", orphanedCount: 0 });
+    opts.log?.warn("reconcile: engine unreachable — skipped (no rows orphaned; live work left intact).");
+    return { runId, reason: "engine-unreachable", observedEpoch: null, recordedEpoch: recorded, orphanedCount: 0, orphaned: [] };
+  }
+
+  const observedEpoch = observation.epoch;
+  const recordedEpoch = await readRecordedEpoch(src);
+  const regression = recordedEpoch != null && (observedEpoch == null || observedEpoch < recordedEpoch);
+
+  const result = await src.tx(async (t) => {
+    let orphaned: OrphanedRow[] = [];
+    let reason: ReconcileReason;
+    if (regression) {
+      orphaned = await orphanEngineBackedRows(t, runId, observedEpoch, at);
+      reason = "epoch-regression";
+    } else if (recordedEpoch == null && observedEpoch != null) {
+      reason = "seed-epoch";
+    } else {
+      reason = "no-op";
+    }
+    if (observedEpoch != null) await persistEpoch(t, observedEpoch, at);
+    await recordRun(t, { runId, at, observedEpoch, recordedEpoch, reason, orphanedCount: orphaned.length });
+    return { reason, orphaned };
+  });
+
+  if (result.reason === "epoch-regression") {
+    opts.log?.warn(
+      `reconcile: engine epoch regressed ${recordedEpoch} → ${observedEpoch} (reset/rewind) — ` +
+        `orphaned ${result.orphaned.length} inflight row(s) [run ${runId}].`,
+    );
+  } else if (result.reason === "seed-epoch") {
+    opts.log?.info(`reconcile: recorded engine epoch ${observedEpoch} (first observation) [run ${runId}].`);
+  } else {
+    opts.log?.info(`reconcile: engine epoch ${observedEpoch ?? "n/a"} unchanged — no-op [run ${runId}].`);
+  }
+
+  return { runId, reason: result.reason, observedEpoch, recordedEpoch, orphanedCount: result.orphaned.length, orphaned: result.orphaned };
+}
+
+async function recordRun(
+  src: DataSource,
+  run: { runId: string; at: string; observedEpoch: number | null; recordedEpoch: number | null; reason: ReconcileReason; orphanedCount: number },
+): Promise<void> {
+  await src.exec(
+    `INSERT INTO ${RUNS_TABLE} (run_id, started_at, observed_epoch, recorded_epoch, reason, orphaned_count) ` +
+      `VALUES (?, ?, ?, ?, ?, ?)`,
+    [run.runId, run.at, run.observedEpoch, run.recordedEpoch, run.reason, run.orphanedCount],
+  );
+}
+
+/** Probe the engine's incarnation epoch, then reconcile — the wiring both startup (main.ts) and the
+ *  `reconcileEngineState` operator command share, so the two paths can never diverge. */
+export async function runEngineReconcile(
+  data: DataLayer,
+  engineRest: { restAddress: string; token?: string },
+  opts: ReconcileOptions & { fetchImpl?: typeof fetch } = {},
+): Promise<ReconcileResult> {
+  const observation = await probeEngineEpoch(engineRest.restAddress, {
+    token: engineRest.token,
+    fetchImpl: opts.fetchImpl,
+  });
+  return reconcileEngineBackedWork(data, observation, opts);
+}

package/db/migrations/092_engine_reconcile.sql

@@ -0,0 +1,53 @@
+-- Engine-reset reconciliation surface (issue #622).
+--
+-- When the Nano engine is reset, restored, or rolled to an incarnation whose key generator has
+-- rewound (Magikcraft/nano-bpm#1065), `app.db` keeps projecting engine-backed inflight work that no
+-- longer exists on the engine. These three sidecars give the app a first-class, idempotent,
+-- provenance-stamped `reconcile` surface (app/reconcile.ts) that runs on startup and on demand:
+--
+--   • engine_incarnation  — the single-row last-seen engine incarnation/epoch id. The engine stamps
+--     a monotonic incarnation id at boot (companion to the versioned snapshot envelope,
+--     Magikcraft/nano-bpm#1068) and exposes it on `/v2/topology`. An epoch REGRESSION (the observed
+--     epoch is lower than the recorded one) — or its absence where one was recorded — is the cheap,
+--     robust "engine was reset/rewound → reconcile" signal, one check instead of N per-instance probes.
+--   • reconcile_runs      — one row per reconcile pass: the observed vs recorded epoch, the outcome
+--     reason, and how many rows were orphaned. The append-only audit of every convergence.
+--   • reconcile_provenance— one row per orphaned transition: which engine-backed app row
+--     (source_table, pk_value, its engine instance key) moved from which status to `orphaned`, why
+--     (engine-reset/epoch-regression), the observed engine epoch, and the owning reconcile run id.
+--     This is the provenance that makes each mutation legible and reversible instead of a silent drop.
+--
+-- These are app-owned bookkeeping surfaces; reconcile itself never mutates append-only audit or
+-- already-terminal history — only NON-terminal, engine-backed rows (nano.app.json instanceTracking
+-- bindings) whose status is still in the binding's activeStatuses set.
+
+CREATE TABLE IF NOT EXISTS engine_incarnation (
+  id INTEGER PRIMARY KEY CHECK (id = 1), -- single-row table: the app only tracks one engine
+  epoch INTEGER,                          -- last-seen engine incarnation/epoch id (NULL until the engine exposes one)
+  observed_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS reconcile_runs (
+  run_id TEXT PRIMARY KEY,
+  started_at TEXT NOT NULL,
+  observed_epoch INTEGER,   -- the engine epoch observed on this run (NULL when the engine exposes none)
+  recorded_epoch INTEGER,   -- the previously-recorded epoch (NULL on the first ever run)
+  reason TEXT NOT NULL,     -- 'epoch-regression' | 'seed-epoch' | 'no-op' | 'engine-unreachable'
+  orphaned_count INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS reconcile_provenance (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  source_table TEXT NOT NULL,  -- the engine-backed base table the orphaned row lives in
+  pk_value TEXT NOT NULL,      -- the row's primary-key value
+  key_value TEXT,              -- the engine instance key (keyField, e.g. process_key) the row projected
+  from_status TEXT,            -- the non-terminal status the row carried before reconcile
+  to_status TEXT NOT NULL,     -- always the defined 'orphaned' terminal
+  reason TEXT NOT NULL,        -- 'engine-reset/epoch-regression'
+  observed_epoch INTEGER,      -- the engine epoch observed when the row was orphaned
+  at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS ix_reconcile_provenance_run ON reconcile_provenance (run_id);
+CREATE INDEX IF NOT EXISTS ix_reconcile_provenance_row ON reconcile_provenance (source_table, pk_value);

package/main.ts

@@ -22,6 +22,7 @@ import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urba
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
 import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
+import { runEngineReconcile } from "./app/reconcile.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
@@ -102,6 +103,30 @@ if (httpServer instanceof Server) {
   app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
 }
 
+// Engine-reset reconciliation (issue #622). On boot, compare the engine's incarnation epoch against
+// the last-seen value; on a REGRESSION (the engine was reset/restored/rewound and re-minted its keys,
+// Magikcraft/nano-bpm#1065) drive every dangling engine-backed inflight row to the defined `orphaned`
+// terminal WITH PROVENANCE — BEFORE the pollers below start projecting off stale, dead instances.
+// Guarded: an unreachable engine is a no-op (it never orphans live work), and any failure degrades to
+// a warn so reconcile can never block boot.
+if (app.data) {
+  try {
+    const reconciled = await runEngineReconcile(
+      app.data,
+      { restAddress: engineAddress.restAddress, token: process.env.CAMUNDA_TOKEN },
+      { log: { info: (m) => app.log.info(m), warn: (m) => app.log.warn(m) } },
+    );
+    if (reconciled.orphanedCount > 0) {
+      app.log.warn(
+        `startup reconcile: engine reset detected — orphaned ${reconciled.orphanedCount} engine-backed ` +
+          `inflight row(s) [run ${reconciled.runId}].`,
+      );
+    }
+  } catch (err) {
+    app.log.warn(`startup reconcile skipped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
 // overlap two passes (which could double-signal `readiness-ready`); the next pass is scheduled
 // only after the previous one settles.

package/openapi.yaml

@@ -844,6 +844,64 @@ components:
           type: string
         uptimeSeconds:
           type: integer
+    ReconcileReport:
+      type: object
+      description: The result of one engine-reset reconciliation pass (issue #622).
+      additionalProperties: false
+      required:
+        - runId
+        - reason
+        - observedEpoch
+        - recordedEpoch
+        - orphanedCount
+        - orphaned
+      properties:
+        runId:
+          type: string
+          description: The reconcile run id every orphaned transition's provenance is stamped with.
+        reason:
+          type: string
+          description: Why this pass acted (or did not).
+          enum:
+            - epoch-regression
+            - seed-epoch
+            - no-op
+            - engine-unreachable
+        observedEpoch:
+          type: integer
+          nullable: true
+          description: The engine incarnation epoch observed on this pass (null when the engine exposes
+            none, or was unreachable).
+        recordedEpoch:
+          type: integer
+          nullable: true
+          description: The previously-recorded epoch this pass compared against (null on the first run).
+        orphanedCount:
+          type: integer
+          description: How many engine-backed inflight rows were driven to `orphaned`.
+        orphaned:
+          type: array
+          description: The rows orphaned by this pass.
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - table
+              - pk
+              - key
+              - fromStatus
+            properties:
+              table:
+                type: string
+              pk:
+                type: string
+              key:
+                type: string
+                nullable: true
+                description: The engine instance key (e.g. process_key) the row projected.
+              fromStatus:
+                type: string
+                description: The non-terminal status the row carried before it was orphaned.
     AgentInstructions:
       type: object
       description: The agent operator guide — how to drive (submit PRs/epics, answer escalations)
@@ -3189,6 +3247,40 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /reconcile:
+    post:
+      operationId: reconcileEngineState
+      summary: Reconcile engine-backed inflight projections after an engine reset/rewind (issue #622).
+      description: >-
+        The explicit operator command for the app-side reconciliation surface. Probes the engine's
+        incarnation epoch (`/v2/topology`) and compares it to the last-seen value: on a REGRESSION (the
+        #1065 reset/rewind signature) every NON-terminal engine-backed app row (an instanceTracking
+        binding whose status is still active and whose engine key is populated) is driven to the
+        defined `orphaned` terminal WITH PROVENANCE. Terminal history and non-engine-backed surfaces
+        (presence, audit) are never touched. Idempotent — a second call with a matching epoch is a
+        no-op — and safe: an unreachable engine orphans nothing. Runs automatically on startup too.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The reconcile pass result (what it observed and orphaned).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReconcileReport"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "503":
+          description: The app has no data source configured, so there is nothing to reconcile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /version:
     get:
       operationId: getVersion

package/operations/reconcileEngineState.test.ts

@@ -0,0 +1,81 @@
+// Delegate-level tests for POST /app/api/reconcile → operation `reconcileEngineState` (issue #622).
+// Covers the shared-secret guard (401), the no-data-source guard (503), and a happy-path 200 that
+// exercises the wiring to `runEngineReconcile` against the REAL shipping schema (the whole migration
+// set on an in-memory SQLite) with the engine `/topology` probe stubbed — so the operator command's
+// auth guard, status codes, and reconcile wiring are regression-covered by the Node test suite.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import { freshData } from "../test/reconcileDb.ts";
+import handler from "./reconcileEngineState.ts";
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "POST",
+      path: "/app/api/reconcile",
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+/** Stub the global `/topology` probe so the delegate never touches the network; restore after. */
+async function withEngineEpoch<T>(epoch: number | null, fn: () => Promise<T>): Promise<T> {
+  const prev = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    ({
+      ok: true,
+      json: async () => (epoch == null ? {} : { nano: { incarnation: epoch } }),
+    }) as unknown as Response) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prev;
+  }
+}
+
+test("returns 503 when no data source is configured", async () => {
+  const app = { log: noopLog() } as any as AppApi;
+  const res = (await handler(input(), app)) as any;
+  assertEquals(res.status, 503);
+  assert("error" in res.body);
+});
+
+test("first observation seeds the epoch and returns 200 with a reconcile result", async () => {
+  const { data } = freshData();
+  const app = { data, log: noopLog() } as any as AppApi;
+  const res = await withEngineEpoch(7, async () => (await handler(input(), app)) as any);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.reason, "seed-epoch");
+  assertEquals(res.body.orphanedCount, 0);
+  assert(typeof res.body.runId === "string" && res.body.runId.length > 0);
+});
+
+test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    // SECRET is bound at import time, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./reconcileEngineState.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const { data } = freshData();
+    const app = { data, log: noopLog() } as any as AppApi;
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const wrong = (await guarded(input({ "x-hook-secret": "nope" }), app)) as any;
+    assertEquals(wrong.status, 401);
+    const ok = await withEngineEpoch(7, async () =>
+      (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any,
+    );
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/reconcileEngineState.ts

@@ -0,0 +1,44 @@
+// POST /app/api/reconcile → operationId `reconcileEngineState` (ADR 0058/0059, base /app/api).
+//
+// The explicit OPERATOR COMMAND for the app-side engine-reset reconciliation surface (issue #622) —
+// the on-demand twin of the startup pass in main.ts, sharing the one `runEngineReconcile` seam so the
+// two paths can never diverge. An operator (or a restore runbook) POSTs here after resetting /
+// restoring / rewinding the engine to converge `app.db`: it probes the engine incarnation epoch and,
+// on a regression, drives every dangling engine-backed inflight row to the defined `orphaned` terminal
+// with provenance. Idempotent (a matching epoch is a no-op) and safe (an unreachable engine orphans
+// nothing), so it is harmless to run at any time — a green "nothing to do" is the common case.
+//
+// The engine address is the canonical `resolveEngineAddress` (the same precedence the engine client
+// and startup preflight use), so the operator command talks to exactly the engine the app runs
+// against. The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI
+// `security`): when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header.
+
+import { resolveEngineAddress } from "../app/enginePreflight.ts";
+import { runEngineReconcile } from "../app/reconcile.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("reconcileEngineState", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("reconcileEngineState rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.data) {
+    app.log.warn("reconcileEngineState: no data source configured — nothing to reconcile");
+    return { status: 503, body: { error: "no data source configured" } };
+  }
+  const engineAddress = resolveEngineAddress();
+  const result = await runEngineReconcile(
+    app.data,
+    { restAddress: engineAddress.restAddress, token: envVar("CAMUNDA_TOKEN") ?? undefined },
+    { log: { info: (m) => app.log.info(m), warn: (m) => app.log.warn(m) } },
+  );
+  app.log.info("reconcileEngineState complete", {
+    reason: result.reason,
+    orphanedCount: result.orphanedCount,
+    runId: result.runId,
+  });
+  return { status: 200, body: result };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.162.2",
+  "version": "0.163.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/test/reconcileDb.ts

@@ -0,0 +1,61 @@
+// A test-only DataLayer over a real in-memory `node:sqlite` db with the WHOLE migration set applied,
+// for exercising the engine-reset reconciliation surface (`app/reconcile.ts`, issue #622) and its
+// operator-command delegate (`operations/reconcileEngineState.ts`) against the REAL shipping schema —
+// so the tables/columns/indexes reconcile reads and writes are exactly what deploys, not a fake.
+//
+// Canonical harness shared by `app/reconcile.test.ts` and `operations/reconcileEngineState.test.ts`
+// (derivation over duplication: one in-memory DataLayer builder, not two divergent copies).
+import { readdirSync, readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach } from "node:test";
+import { fileURLToPath } from "node:url";
+import { type DataLayer, makeGateway, type SqliteDb } from "@nanobpm/urban";
+import { applyMigrationSet } from "#test-migrations";
+
+const MIGRATIONS_DIR = fileURLToPath(new URL("../db/migrations", import.meta.url));
+
+// Every raw handle `freshData()` opens is tracked here and released after each test, so call sites
+// (all of them) don't leak native SQLite handles across the run. Mirrors `test/worldDb.ts` and
+// `test/blackboardDb.ts` (derivation over duplication: the same auto-close idiom, not a new one).
+const openDbs = new Set<DatabaseSync>();
+afterEach(() => {
+  for (const raw of openDbs) {
+    if (openDbs.delete(raw)) raw.close();
+  }
+});
+
+/** Adapt a raw `node:sqlite` handle to urban's tiny `SqliteDb` seam so `makeGateway` yields the real
+ *  record-oriented `DataSource` reconcile binds to (no fakes — the shipping gateway). */
+export function sqliteDb(raw: DatabaseSync): SqliteDb {
+  return {
+    exec: (sql) => raw.exec(sql),
+    run: (sql, params = []) => {
+      const r = raw.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      raw.prepare(sql).all(...(params as never[])) as T[],
+    close: () => raw.close(),
+  };
+}
+
+export function readMigrationFiles(): { name: string; sql: string }[] {
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((n) => n.endsWith(".sql"))
+    .map((name) => ({ name, sql: readFileSync(`${MIGRATIONS_DIR}/${name}`, "utf8") }));
+}
+
+/** A DataLayer over a fresh in-memory DB with the whole migration set applied. The raw handle is
+ *  tracked and auto-closed after each test (see `openDbs`), and FK enforcement is enabled so the
+ *  migrations are exercised under the real constraints they ship with. */
+export function freshData(): { data: DataLayer; raw: DatabaseSync } {
+  const raw = new DatabaseSync(":memory:");
+  openDbs.add(raw);
+  // SQLite disables FK enforcement by default; enable it so migrations with foreign keys are
+  // exercised (and any FK violations surface) exactly as they would on the shipping schema.
+  raw.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(raw, readMigrationFiles());
+  const gw = makeGateway(sqliteDb(raw));
+  const data = { open: () => gw } as unknown as DataLayer;
+  return { data, raw };
+}