@nanobpm/nano-workforce 0.100.0 → 0.101.0

package/app/world/store.ts

@@ -0,0 +1,320 @@
+// nano-workforce — the durable world-checkpoint + effect-ledger store (issue #324, ADR 0062 Slice
+// 4/5, the WORLD half). Backs the ./checkpoint.ts orchestration onto the app's SQLite DataLayer via
+// the RAD `Table<T>` surface (`data.table(...)`) — NOT hand-written SQL — over the two tables added
+// by `db/migrations/049_world_checkpoint.sql`.
+//
+// The store is the ONE canonical home of the world's durable resume state: the push-checkpoints
+// (`world_checkpoints`, a per-PR monotonic offset → commit SHA) and the effect ledger + fence
+// (`world_effects`). It exposes exactly what the forward path (record a checkpoint at a push) and the
+// restore path (read the last checkpoint, fence-replay its effect tail) need — nothing derivable is
+// duplicated (AGENTS.md "derivation over duplication": the tree is derived from `remote SHA +
+// effect-tail`, never snapshot into a log).
+import type { DataLayer, Table } from "@nanobpm/urban";
+import type { Effect, EffectKind, Fence } from "./effect-ledger.ts";
+
+/** A persisted push-checkpoint row (`world_checkpoints`). */
+interface WorldCheckpointRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  checkpoint_offset: number;
+  commit_sha: string;
+  created_at: string;
+}
+
+/** A persisted effect-ledger row (`world_effects`). */
+interface WorldEffectRow {
+  id: number;
+  pr_key: string;
+  checkpoint_offset: number;
+  seq: number;
+  kind: EffectKind;
+  idempotency_key: string;
+  description: string | null;
+  applied: number;
+  created_at: string;
+}
+
+/** The newest push-checkpoint for a PR — the durable resume boundary a replacement activation
+ * reconstructs the working tree to. `offset` is the shared mind/world turn boundary. */
+export interface LastCheckpoint {
+  readonly offset: number;
+  readonly commitSha: string;
+  readonly roundNo: number;
+}
+
+/** The inputs recording a world checkpoint at a push: the pushed SHA plus the irreversible effects
+ * that round performed (the push itself, any PR comment, any merge). */
+export interface RecordCheckpointInput {
+  readonly prKey: string;
+  readonly roundNo: number;
+  readonly commitSha: string;
+  /** Irreversible effects performed this round, in the order they occurred. Defaults to a single
+   * `push` effect keyed by the commit SHA when omitted. Each is recorded through the fence, so a
+   * re-record of an already-known idempotency key is a no-op (never a second real effect). */
+  readonly effects?: readonly Effect[];
+  /** Whether the recorded effects have already been realised on the forward path (default `true` —
+   * a checkpoint records what a round already DID). A pending tail effect (recorded before it is
+   * performed, for crash-precise replay) is recorded with `applied: false`. */
+  readonly applied?: boolean;
+}
+
+/** A durable store over the `world_checkpoints` + `world_effects` tables. */
+export class WorldStore {
+  readonly #data: DataLayer;
+
+  constructor(data: DataLayer) {
+    this.#data = data;
+  }
+
+  #checkpoints() {
+    return this.#data.table<WorldCheckpointRow>("world_checkpoints", "id");
+  }
+
+  #effects() {
+    return this.#data.table<WorldEffectRow>("world_effects", "id");
+  }
+
+  /** The next per-PR monotonic checkpoint offset (0 for the first, else `max + 1`). Derived from the
+   * durable rows so it survives a process restart — the offset is never held in memory. */
+  async nextOffset(prKey: string): Promise<number> {
+    return WorldStore.#nextOffsetOn(this.#checkpoints(), prKey);
+  }
+
+  /** The next offset computed against a specific checkpoints `Table` handle — so it can be read on the
+   * SAME transaction connection the checkpoint row is then inserted on (see {@link recordCheckpoint}),
+   * keeping the allocate-then-insert atomic. */
+  static async #nextOffsetOn(checkpoints: Table<WorldCheckpointRow>, prKey: string): Promise<number> {
+    const rows = await checkpoints.find({ pr_key: prKey });
+    if (rows.length === 0) return 0;
+    return Math.max(...rows.map((r) => r.checkpoint_offset)) + 1;
+  }
+
+  /** The next intra-checkpoint `seq` for `{prKey, offset}` — `0` for a fresh offset, else `max + 1`.
+   * When a re-record REUSES an existing offset (idempotent on the commit SHA), any newly-supplied
+   * effect must be appended AFTER the tail already recorded there, not restart at `seq 0` and collide
+   * with it. Read on the same transaction handle the effects are then appended on. */
+  static async #nextSeqOn(effects: Table<WorldEffectRow>, prKey: string, offset: number): Promise<number> {
+    const rows = await effects.find({ pr_key: prKey, checkpoint_offset: offset });
+    if (rows.length === 0) return 0;
+    return Math.max(...rows.map((r) => r.seq)) + 1;
+  }
+
+  /** True when `err` is the durable fence firing — a SQLite `UNIQUE constraint failed` raised because a
+   * concurrent/duplicate writer inserted the row BETWEEN our `findOne` and our `insert`. Every insert
+   * in this store guards a UNIQUE constraint (`UNIQUE(pr_key, commit_sha)` / `(pr_key, checkpoint_offset)`
+   * on checkpoints, `UNIQUE(pr_key, idempotency_key)` on effects), so a check-then-insert is inherently
+   * racy under the at-least-once persist-round delivery + a distributed fleet. This is the ONE place the
+   * store classifies a fence collision, so the three insert sites below turn it into the SAME intended
+   * idempotent outcome instead of each re-encoding the driver's error shape (a drift surface). Matched on
+   * the message substring the RAD `Table` surface propagates verbatim — the same one the schema tests
+   * assert on — because that surface hides the concrete driver error type. */
+  static #isFenceCollision(err: unknown): boolean {
+    return err instanceof Error && /UNIQUE constraint failed/i.test(err.message);
+  }
+
+  /** Reconcile an existing ledger row's `applied` flag toward a LATER record's knowledge: flip a
+   * still-pending row (`applied=0`) to realised (`applied=1`) once we know the effect has now landed
+   * (`applied=true`). This is monotone — it NEVER un-applies a row (`1` never goes back to `0`) and
+   * never marks a still-pending record applied — so a re-record can only ever advance the fence, not
+   * retreat it. It is the ONE place a pending→applied transition is written, so the record path
+   * (`#appendEffect`) and the replay path (`markApplied`) reconcile identically instead of each
+   * re-encoding the flip (a drift surface). Without it, `#appendEffect`'s duplicate-key short-circuit
+   * would leave a pending row pending forever even after the effect landed, so a later `restoreWorld`
+   * would re-apply an already-executed side effect. */
+  static async #reconcileApplied(
+    effects: Table<WorldEffectRow>,
+    row: WorldEffectRow,
+    applied: boolean,
+  ): Promise<void> {
+    if (applied && row.applied !== 1) await effects.update(row.id, { applied: 1 });
+  }
+
+  /** Insert the checkpoint row for a not-yet-seen `{prKey, commitSha}`, allocating the next offset, and
+   * tolerate the fence firing. `recordCheckpoint`'s `findOne`-then-insert is racy: a concurrent/duplicate
+   * persist-round can insert the SAME SHA between our read and our write, so the insert hits
+   * `UNIQUE(pr_key, commit_sha)`. Rather than surface it as a spurious job failure, re-read the winner's
+   * row and REUSE its offset — the exact idempotent-on-SHA outcome the non-racing path yields. If the
+   * collision was instead a pure offset race with a DIFFERENT SHA (`UNIQUE(pr_key, checkpoint_offset)`),
+   * the SHA re-read misses and we rethrow, letting the job retry allocate a fresh offset. Returns the
+   * offset the SHA is durably bound to. */
+  static async #insertCheckpointFenced(
+    checkpoints: Table<WorldCheckpointRow>,
+    prKey: string,
+    roundNo: number,
+    commitSha: string,
+    now: string,
+  ): Promise<number> {
+    const offset = await WorldStore.#nextOffsetOn(checkpoints, prKey);
+    try {
+      await checkpoints.insert({
+        pr_key: prKey,
+        round_no: roundNo,
+        checkpoint_offset: offset,
+        commit_sha: commitSha,
+        created_at: now,
+      });
+      return offset;
+    } catch (err) {
+      if (!WorldStore.#isFenceCollision(err)) throw err;
+      const raced = await checkpoints.findOne({ pr_key: prKey, commit_sha: commitSha });
+      if (!raced) throw err;
+      return raced.checkpoint_offset;
+    }
+  }
+
+  /**
+   * Record a push-checkpoint: allocate the next offset, persist `{commitSha}`, and append the round's
+   * irreversible effects to the ledger (each fenced by `UNIQUE(pr_key, idempotency_key)`). Returns
+   * the allocated offset — the SAME offset the mind's `session.checkpoint(...)` is joined to (see
+   * ./checkpoint.ts), which is what keeps mind + world from diverging.
+   *
+   * ATOMIC: the checkpoint row and its whole effect ledger are written inside ONE transaction, so a
+   * crash/error part-way can never leave a checkpoint whose fence is missing some/all of its ledger
+   * rows — which would let a restore re-apply an effect that already landed. Any throw rolls the whole
+   * write back (offset allocation included).
+   *
+   * Idempotent on the effect fence: an effect whose idempotency key is already in the ledger is not
+   * re-inserted (so a duplicate record can never manufacture a second real effect). The checkpoint
+   * row itself is guarded by `UNIQUE(pr_key, checkpoint_offset)`.
+   *
+   * Idempotent on the commit SHA: a re-record of the SAME `{prKey, commitSha}` (a retried/duplicate
+   * persist-round job) REUSES the existing checkpoint's offset instead of allocating a fresh one.
+   * Allocating a new offset would make a duplicate the newest `lastCheckpoint` while its effect tail
+   * is empty (the global `(pr_key, idempotency_key)` fence skips the already-recorded effects), so a
+   * later `restoreWorld` would read the empty tail and IGNORE genuinely-pending effects recorded on
+   * the earlier offset — silent effect loss. Reusing the offset keeps the pending tail attached to
+   * the surviving newest checkpoint; any newly-supplied effect is appended at that same offset.
+   */
+  async recordCheckpoint(input: RecordCheckpointInput): Promise<number> {
+    const { prKey, roundNo, commitSha } = input;
+    const effects: readonly Effect[] = input.effects ?? [{ kind: "push", idempotencyKey: commitSha }];
+    const applied = input.applied ?? true;
+    const now = new Date().toISOString();
+    return this.#data.open().tx(async (t) => {
+      const checkpoints = t.table<WorldCheckpointRow>("world_checkpoints", "id");
+      const effectsTable = t.table<WorldEffectRow>("world_effects", "id");
+      const existing = await checkpoints.findOne({ pr_key: prKey, commit_sha: commitSha });
+      const offset = existing
+        ? existing.checkpoint_offset
+        : await WorldStore.#insertCheckpointFenced(checkpoints, prKey, roundNo, commitSha, now);
+      let seq = await WorldStore.#nextSeqOn(effectsTable, prKey, offset);
+      for (const effect of effects) {
+        await WorldStore.#appendEffect(effectsTable, prKey, offset, seq++, effect, applied, now);
+      }
+      return offset;
+    });
+  }
+
+  /** Append one effect to the ledger via `effects`, collapsing a re-record of an idempotency key
+   * already present to the durable fence's no-op (the second record of one real effect is never a
+   * second row). A re-record still RECONCILES the surviving row's `applied` flag: a tail effect first
+   * recorded pending (`applied=false`) and later re-recorded once it landed (`applied=true`) must
+   * advance the fence to realised, or a later `restoreWorld` would re-apply an already-executed side
+   * effect. Static so a transaction-scoped `Table` can be threaded in (see {@link recordCheckpoint}). */
+  static async #appendEffect(
+    effects: Table<WorldEffectRow>,
+    prKey: string,
+    offset: number,
+    seq: number,
+    effect: Effect,
+    applied: boolean,
+    now: string,
+  ): Promise<void> {
+    const existing = await effects.findOne({ pr_key: prKey, idempotency_key: effect.idempotencyKey });
+    if (existing) {
+      await WorldStore.#reconcileApplied(effects, existing, applied);
+      return;
+    }
+    try {
+      await effects.insert({
+        pr_key: prKey,
+        checkpoint_offset: offset,
+        seq,
+        kind: effect.kind,
+        idempotency_key: effect.idempotencyKey,
+        description: effect.description ?? null,
+        applied: applied ? 1 : 0,
+        created_at: now,
+      });
+    } catch (err) {
+      // A concurrent/duplicate writer recorded this idempotency key between our `findOne` and our
+      // `insert` — the fence firing IS the intended outcome (one real effect → exactly one row), so
+      // treat the collision as the same no-op the `existing` short-circuit above already is, not a
+      // surfaced error that fails the persist-round. Still reconcile the raced row's `applied` flag,
+      // exactly as the `existing` branch does, so a landed effect isn't left pending on the winner row.
+      if (!WorldStore.#isFenceCollision(err)) throw err;
+      const raced = await effects.findOne({ pr_key: prKey, idempotency_key: effect.idempotencyKey });
+      if (raced) await WorldStore.#reconcileApplied(effects, raced, applied);
+    }
+  }
+
+  /** The newest push-checkpoint for a PR, or `null` when the PR has none (nothing pushed yet, so
+   * nothing to reconstruct — the caller keeps the freshly-provisioned worktree). */
+  async lastCheckpoint(prKey: string): Promise<LastCheckpoint | null> {
+    const rows = await this.#checkpoints().find({ pr_key: prKey });
+    if (rows.length === 0) return null;
+    const newest = rows.reduce((a, b) => (b.checkpoint_offset > a.checkpoint_offset ? b : a));
+    return { offset: newest.checkpoint_offset, commitSha: newest.commit_sha, roundNo: newest.round_no };
+  }
+
+  /** The effect tail recorded at a checkpoint offset, in `seq` order — the sequence the restore path
+   * fence-replays after checking the working tree out to that checkpoint's SHA. `seq` is the intended
+   * order, but it is allocated by a racy read-max-plus-one (`#nextSeqOn`) and the schema has no
+   * `UNIQUE(pr_key, checkpoint_offset, seq)`, so two concurrent inserts at one offset CAN land the same
+   * `seq`. The monotonic autoincrement `id` breaks that tie so the tail is deterministic (a stable
+   * insertion order) even under a `seq` collision — never a non-deterministic replay/audit order. */
+  async effectTail(prKey: string, offset: number): Promise<Effect[]> {
+    const rows = await this.#effects().find({ pr_key: prKey, checkpoint_offset: offset });
+    return rows
+      .sort((a, b) => a.seq - b.seq || a.id - b.id)
+      .map((r) => ({
+        kind: r.kind,
+        idempotencyKey: r.idempotency_key,
+        ...(r.description == null ? {} : { description: r.description }),
+      }));
+  }
+
+  /** The durable {@link Fence} bound to a PR: `isApplied` is true once an effect's idempotency key is
+   * in the ledger AND realised (`applied=1`); `markApplied` flips a pending effect to realised (or
+   * records a newly-applied one). This is the seam `fenceReplay` folds a tail over. */
+  fenceFor(prKey: string, offset: number): Fence {
+    const effects = this.#effects();
+    return {
+      async isApplied(idempotencyKey: string): Promise<boolean> {
+        const row = await effects.findOne({ pr_key: prKey, idempotency_key: idempotencyKey });
+        return !!row && row.applied === 1;
+      },
+      async markApplied(effect: Effect): Promise<void> {
+        const row = await effects.findOne({ pr_key: prKey, idempotency_key: effect.idempotencyKey });
+        if (row) {
+          await WorldStore.#reconcileApplied(effects, row, true);
+          return;
+        }
+        try {
+          await effects.insert({
+            pr_key: prKey,
+            checkpoint_offset: offset,
+            // Append AFTER the tail already recorded at this offset — restarting at `seq 0` would
+            // collide with a sibling effect at the same offset and make `effectTail`'s tie-sort
+            // (`a.seq - b.seq`) non-deterministic, destabilising restore/audit ordering.
+            seq: await WorldStore.#nextSeqOn(effects, prKey, offset),
+            kind: effect.kind,
+            idempotency_key: effect.idempotencyKey,
+            description: effect.description ?? null,
+            applied: 1,
+            created_at: new Date().toISOString(),
+          });
+        } catch (err) {
+          if (!WorldStore.#isFenceCollision(err)) throw err;
+          // A concurrent restore/replay recorded this key between our `findOne` and our `insert`. The
+          // desired end-state is simply "applied", which is already (or nearly) achieved — reconcile to
+          // it by re-reading and flipping `applied`, rather than failing the restore over a fence we
+          // WANTED to hold.
+          const raced = await effects.findOne({ pr_key: prKey, idempotency_key: effect.idempotencyKey });
+          if (raced) await WorldStore.#reconcileApplied(effects, raced, true);
+        }
+      },
+    };
+  }
+}

package/app/world-marker.test.ts

@@ -0,0 +1,79 @@
+// Red/green for the persist-round world-marker contract boundary (issue #324, ADR 0062 Slice 4/5).
+//
+// `worldMarker` arrives from the c8ctl harness OUT-OF-PROCESS, so both the fence key and the effect
+// kind are untrusted. `worldMarkerOf` must (a) TRIM `idempotencyKey` so whitespace variants of one
+// real effect collapse to a single fence key (not distinct ledger rows that defeat the fence) and
+// (b) reject an effect whose `kind` is not one of the canonical `EFFECT_KINDS`, so an unexpected kind
+// can never enter the durable ledger.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { worldMarkerOf } from "../workers/persist-round/worker.ts";
+
+// A well-formed 40-hex commit SHA — the ONLY shape `worldMarkerOf` now accepts for `commitSha`,
+// since it is used as an EXACT checkout target on restore.
+const SHA = "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678";
+
+test("worldMarkerOf returns null when there is no marker or no commit SHA", () => {
+  assertEquals(worldMarkerOf({}), null);
+  assertEquals(worldMarkerOf({ worldMarker: { effects: [] } }), null);
+  assertEquals(worldMarkerOf({ worldMarker: { commitSha: "   " } }), null);
+});
+
+test("worldMarkerOf rejects a commitSha that is not a well-formed 40-hex SHA", () => {
+  // A branch name / arbitrary ref — would reconstruct to a moved tip, not an exact tree.
+  assertEquals(worldMarkerOf({ worldMarker: { commitSha: "main" } }), null);
+  // An abbreviated / short SHA — ambiguous, not a full object name.
+  assertEquals(worldMarkerOf({ worldMarker: { commitSha: "a1b2c3d" } }), null);
+  // 39 hex (one short) and 41 hex (one long) — length must be exactly 40.
+  assertEquals(worldMarkerOf({ worldMarker: { commitSha: "a".repeat(39) } }), null);
+  assertEquals(worldMarkerOf({ worldMarker: { commitSha: "a".repeat(41) } }), null);
+  // A non-hex character in an otherwise 40-char string.
+  assertEquals(worldMarkerOf({ worldMarker: { commitSha: `g${"a".repeat(39)}` } }), null);
+});
+
+test("worldMarkerOf trims a whitespace-tainted idempotencyKey so the fence key is canonical", () => {
+  const m = worldMarkerOf({
+    worldMarker: { commitSha: `  ${SHA}  `, effects: [{ kind: "pr-comment", idempotencyKey: "  c-1\n" }] },
+  });
+  assertEquals(m, { commitSha: SHA, effects: [{ kind: "pr-comment", idempotencyKey: "c-1" }] });
+});
+
+test("worldMarkerOf drops an effect whose kind is not a known EffectKind", () => {
+  const m = worldMarkerOf({
+    worldMarker: {
+      commitSha: SHA,
+      effects: [
+        { kind: "push", idempotencyKey: "sha-a" },
+        { kind: "delete-branch", idempotencyKey: "x-1" }, // unknown kind — must be rejected
+        { kind: "merge", idempotencyKey: "  " }, // blank key — must be rejected
+      ],
+    },
+  });
+  assertEquals(m, { commitSha: SHA, effects: [{ kind: "push", idempotencyKey: "sha-a" }] });
+});
+
+test("worldMarkerOf omits effects entirely when every effect is invalid", () => {
+  const m = worldMarkerOf({
+    worldMarker: { commitSha: SHA, effects: [{ kind: "bogus", idempotencyKey: "y-1" }] },
+  });
+  assertEquals(m, { commitSha: SHA });
+});
+
+test("worldMarkerOf keeps a trimmed non-empty description and drops a blank one", () => {
+  const m = worldMarkerOf({
+    worldMarker: {
+      commitSha: SHA,
+      effects: [
+        { kind: "push", idempotencyKey: "sha-a", description: "  landed the fix  " },
+        { kind: "merge", idempotencyKey: "m-1", description: "   " },
+      ],
+    },
+  });
+  assertEquals(m, {
+    commitSha: SHA,
+    effects: [
+      { kind: "push", idempotencyKey: "sha-a", description: "landed the fix" },
+      { kind: "merge", idempotencyKey: "m-1" },
+    ],
+  });
+});

package/db/migrations/049_world_checkpoint.sql

@@ -0,0 +1,84 @@
+-- 049_world_checkpoint.sql — issue #324 (ADR 0062, Slice 4/5): the **world** half of durable
+-- agent-session resume. Durable resume splits into `mind` (the harness conversation; Slices 1–3)
+-- and `world` (the git working tree + irreversible side effects; this slice). A replacement
+-- activation lands on a FRESH worktree, so restoring the mind is useless unless the world is
+-- reconstructed to the same turn boundary.
+--
+-- THE INVERSION OF OPERATION. The authoritative durable store for committed work is ALREADY the
+-- git remote — the round `git push`ed a SHA. So world-restore INVERTS the forward op: the round's
+-- outbound `git push` becomes an inbound `git fetch && git checkout <sha>` on resume. We DERIVE the
+-- tree from `remote SHA + effect-tail`; we never snapshot it into a log (no duplicate source of
+-- truth — AGENTS.md "derivation over duplication"). The lossy frontier is work after the last push,
+-- which is exactly why the resume boundary is a PUSH-checkpoint.
+--
+-- Two tables, both keyed by the PR under convergence (`pr_key` = `<owner>/<repo>#<n>`):
+--
+--   world_checkpoints — one row per push-checkpoint (a durable resume boundary). `checkpoint_offset`
+--     is a per-PR monotonic counter (0,1,2,…). At each push the app records `{commit_sha}` AND joins
+--     it to the mind's `session.checkpoint(...)` at the SAME offset, so mind + world always commit at
+--     one turn boundary — the divergence guard (harness thinks it hasn't pushed but the push landed,
+--     or vice-versa) is closed structurally by the shared offset.
+--
+--   world_effects — the EFFECT LEDGER + FENCE. One row per irreversible action (git push → commit
+--     SHA; PR comment → comment id; `gh merge` → merge key), each with an `idempotency_key`. On
+--     restore we replay the post-checkpoint effect tail THROUGH THE FENCE so an already-applied effect
+--     is SKIPPED, not repeated. `UNIQUE(pr_key, idempotency_key)` is the durable fence: an effect
+--     recorded once cannot be double-applied, and `applied` records whether its side effect has been
+--     realised (1) or is a pending tail entry to replay (0).
+--
+-- EXPAND (additive) phase: two new FK-free tables and their indexes; nothing is dropped or renamed.
+-- The store is FK-free by design (like the 045 admission-staging twins): a checkpoint may be recorded
+-- for an in-flight PR whose `pull_requests` row a store desync momentarily lost, and the heal path
+-- must not FK-fail. Numbered after the current highest prefix on origin/main (048). The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE TABLE IF NOT EXISTS world_checkpoints (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  pr_key            TEXT NOT NULL,           -- "<owner>/<repo>#<number>" the checkpoint belongs to
+  round_no          INTEGER NOT NULL,        -- convergence round that produced the push
+  checkpoint_offset INTEGER NOT NULL,        -- per-PR monotonic resume boundary (0,1,2,…)
+  commit_sha        TEXT NOT NULL,           -- the pushed SHA the fresh worktree is reconstructed to
+  created_at        TEXT NOT NULL,
+  -- One checkpoint per (pr, offset): the join records mind + world at the SAME offset, so a duplicate
+  -- offset for one PR would mean two worlds claiming one turn boundary — reject it.
+  UNIQUE(pr_key, checkpoint_offset),
+  -- One checkpoint per (pr, commit SHA): `recordCheckpoint` is idempotent on `{pr_key, commit_sha}`
+  -- (it `findOne`s the existing row and REUSES its offset rather than allocating a fresh one), but the
+  -- application check alone is racy — a concurrent/duplicate persist-round could still land two rows
+  -- for one SHA, and `findOne` would then pick an arbitrary offset, reintroducing the "newest
+  -- checkpoint shadows the real effect tail" silent-effect-loss class. This constraint makes the
+  -- invariant durable: a second row for the same SHA is rejected at the schema, so the offset a SHA
+  -- maps to is unique and stable.
+  UNIQUE(pr_key, commit_sha)
+);
+
+-- The newest checkpoint for a PR is `MAX(checkpoint_offset)`; index the lookup the restore path runs.
+CREATE INDEX IF NOT EXISTS idx_world_checkpoints_pr
+  ON world_checkpoints(pr_key, checkpoint_offset);
+
+CREATE TABLE IF NOT EXISTS world_effects (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  pr_key            TEXT NOT NULL,           -- the PR whose ledger this effect belongs to
+  checkpoint_offset INTEGER NOT NULL,        -- the exact checkpoint boundary this effect was recorded at
+  seq               INTEGER NOT NULL,        -- intra-checkpoint order the fence replays effects in
+  kind              TEXT NOT NULL,           -- push | pr-comment | merge (an irreversible action class)
+  idempotency_key   TEXT NOT NULL,           -- commit SHA / comment id / merge key — the fence key
+  description       TEXT,                    -- human audit note (nullable)
+  applied           INTEGER NOT NULL DEFAULT 0,  -- 1 once its side effect is realised; 0 = pending tail
+  created_at        TEXT NOT NULL,
+  -- `applied` is a strict boolean domain — the fence reads it as "already realised?", so a stray
+  -- value (a future writer bug, a corrupt row on this externalised durability boundary) would make
+  -- the replay silently mis-skip or re-apply an effect. Pin it to {0,1} at the schema. (`kind` is
+  -- deliberately NOT CHECK-constrained here: its valid set is the canonical `EFFECT_KINDS` tuple in
+  -- app/world/effect-ledger.ts and is already enforced at the write boundary by `isEffectKind`;
+  -- re-listing the values in SQL would be a second source of truth that drifts when a kind is added.)
+  CHECK (applied IN (0, 1)),
+  -- The durable FENCE: an effect's idempotency key is unique within a PR, so replaying a tail can
+  -- never re-record — and hence never re-apply — an effect that already landed.
+  UNIQUE(pr_key, idempotency_key)
+);
+
+-- The restore path reads the effect tail recorded at a checkpoint's exact `checkpoint_offset`, in
+-- `seq` order (an exact-offset lookup, not a range scan).
+CREATE INDEX IF NOT EXISTS idx_world_effects_pr_offset
+  ON world_effects(pr_key, checkpoint_offset, seq);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.100.0",
+  "version": "0.101.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/worldDb.ts

@@ -0,0 +1,103 @@
+// A test-only DataLayer over a real in-memory `node:sqlite` db with the world-restore schema
+// (`db/migrations/049_world_checkpoint.sql`) applied, for exercising `app/world/store.ts` and the
+// `app/world/checkpoint.ts` orchestration against a REAL SQLite engine — so the durable fence (the
+// `UNIQUE(pr_key, idempotency_key)` constraint) and the monotonic offset are proven, not mocked.
+import { readFileSync } from "node:fs";
+import { DatabaseSync, type SQLInputValue } from "node:sqlite";
+import { afterEach } from "node:test";
+import { fileURLToPath } from "node:url";
+import type { DataLayer } from "@nanobpm/urban";
+
+const openDbs = new Set<DatabaseSync>();
+afterEach(() => {
+  for (const raw of openDbs) {
+    if (openDbs.delete(raw)) raw.close();
+  }
+});
+
+function coerce(p: unknown): SQLInputValue {
+  if (p === null || p === undefined) return null;
+  if (typeof p === "boolean") return p ? 1 : 0;
+  return p as SQLInputValue;
+}
+
+const quote = (id: string) => `"${id.replace(/"/g, '""')}"`;
+
+/** A minimal async `Table<T>`-shaped gateway over one real SQLite table — the insert/find/findOne/
+ * update/get subset the world store uses. Mirrors the runtime `Table<T>` semantics: `insert` omits
+ * `undefined` keys (schema default governs), `update` skips `undefined` keys and clears on `null`. */
+function gateway(db: DatabaseSync, name: string, pk: string) {
+  return {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async insert(row: any): Promise<number | bigint> {
+      const keys = Object.keys(row).filter((k) => row[k] !== undefined);
+      const cols = keys.map(quote).join(", ");
+      const placeholders = keys.map(() => "?").join(", ");
+      const r = db.prepare(`INSERT INTO ${quote(name)} (${cols}) VALUES (${placeholders})`).run(...keys.map((k) => coerce(row[k])));
+      return pk === "id" ? r.lastInsertRowid : (row[pk] as number);
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async find(where: any = {}): Promise<any[]> {
+      const keys = Object.keys(where);
+      const clause = keys.length ? `WHERE ${keys.map((k) => `${quote(k)} = ?`).join(" AND ")}` : "";
+      return db.prepare(`SELECT * FROM ${quote(name)} ${clause}`).all(...keys.map((k) => coerce(where[k])));
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async findOne(where: any = {}): Promise<any> {
+      return (await this.find(where))[0];
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async get(id: any): Promise<any> {
+      return db.prepare(`SELECT * FROM ${quote(name)} WHERE ${quote(pk)} = ?`).get(coerce(id));
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async update(id: any, patch: any): Promise<number> {
+      const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
+      if (keys.length === 0) return 0;
+      const set = keys.map((k) => `${quote(k)} = ?`).join(", ");
+      const r = db.prepare(`UPDATE ${quote(name)} SET ${set} WHERE ${quote(pk)} = ?`).run(...keys.map((k) => coerce(patch[k])), coerce(id));
+      return Number(r.changes);
+    },
+  };
+}
+
+/** A minimal self-referential `DataSource`-shaped gateway over the real db: the `table` surface plus
+ * a real `tx()` that BEGIN/COMMIT/ROLLBACKs on the underlying SQLite connection, so the world store's
+ * atomic `recordCheckpoint` (checkpoint + effects in one transaction) is exercised against genuine
+ * transaction semantics rather than mocked. `tx(fn)` passes the SAME source object to `fn`, so a test
+ * that decorates `table` on the returned source sees its decoration inside the transaction too. */
+type MemDataSource = {
+  table: (name: string, pk?: string) => ReturnType<typeof gateway>;
+  tx<T>(fn: (t: MemDataSource) => Promise<T>): Promise<T>;
+};
+
+function openDataSource(db: DatabaseSync): MemDataSource {
+  const ds: MemDataSource = {
+    table: (name, pk = "id") => gateway(db, name, pk),
+    async tx(fn) {
+      db.exec("BEGIN");
+      try {
+        const r = await fn(ds);
+        db.exec("COMMIT");
+        return r;
+      } catch (e) {
+        db.exec("ROLLBACK");
+        throw e;
+      }
+    },
+  };
+  return ds;
+}
+
+/** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
+export function memWorldData(): { 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);
+  const data = {
+    table: (name: string, pk = "id") => gateway(db, name, pk),
+    open: () => openDataSource(db),
+  } as unknown as DataLayer;
+  return { data, db };
+}