@nanobpm/nano-workforce 0.100.0 → 0.101.0

package/app/world/effect-ledger.test.ts

@@ -0,0 +1,86 @@
+// Tests for the effect ledger + fence (issue #324, ADR 0062 Slice 4/5, the WORLD half). The fence is
+// the guarantee behind the acceptance criterion "no duplicate push/comment (fence holds)": on a
+// resume the post-checkpoint effect tail is replayed, and an already-applied effect must be SKIPPED,
+// never re-executed. These prove the pure fold in isolation (no DB, no git).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { type Effect, type Fence, fenceReplay } from "./effect-ledger.ts";
+
+/** An in-memory fence over a `Set` of applied idempotency keys. */
+function memFence(applied: string[] = []): Fence & { keys: Set<string> } {
+  const keys = new Set(applied);
+  return {
+    keys,
+    isApplied: (k: string) => keys.has(k),
+    markApplied: (e: Effect) => {
+      keys.add(e.idempotencyKey);
+    },
+  };
+}
+
+const push = (sha: string): Effect => ({ kind: "push", idempotencyKey: sha });
+const comment = (id: string): Effect => ({ kind: "pr-comment", idempotencyKey: id });
+
+test("fenceReplay skips an already-applied effect and never re-applies it (the fence holds)", async () => {
+  const fence = memFence(["sha-1", "comment-9"]);
+  const applied: string[] = [];
+  const outcome = await fenceReplay([push("sha-1"), comment("comment-9")], fence, (e) => {
+    applied.push(e.idempotencyKey);
+  });
+  assertEquals(applied, [], "no effect is re-applied — both were already in the fence");
+  assertEquals(
+    outcome.skipped.map((e) => e.idempotencyKey),
+    ["sha-1", "comment-9"],
+    "both effects are reported skipped",
+  );
+  assertEquals(outcome.applied.length, 0);
+});
+
+test("fenceReplay applies only the genuinely-missing tail effect (crash after push, before comment)", async () => {
+  // The replacement activation crashed after the push landed but before its trailing comment: the
+  // push is fenced, the comment is not. Only the comment must replay.
+  const fence = memFence(["sha-1"]);
+  const applied: string[] = [];
+  const outcome = await fenceReplay([push("sha-1"), comment("comment-9")], fence, (e) => {
+    applied.push(e.idempotencyKey);
+  });
+  assertEquals(applied, ["comment-9"], "only the missing comment is applied");
+  assertEquals(outcome.applied.map((e) => e.idempotencyKey), ["comment-9"]);
+  assertEquals(outcome.skipped.map((e) => e.idempotencyKey), ["sha-1"]);
+  assert(fence.keys.has("comment-9"), "the applied effect is now recorded so a later resume skips it");
+});
+
+test("fenceReplay applies effects strictly in order (a comment referencing a push never precedes it)", async () => {
+  const fence = memFence();
+  const order: string[] = [];
+  await fenceReplay([push("sha-1"), comment("c-1"), comment("c-2")], fence, (e) => {
+    order.push(e.idempotencyKey);
+  });
+  assertEquals(order, ["sha-1", "c-1", "c-2"], "the fold preserves recorded order");
+});
+
+test("fenceReplay collapses a duplicate idempotency key within one tail to a single apply", async () => {
+  // Two ledger entries with one key denote ONE real effect; the second is always a skip even before
+  // the durable fence sees it (a malformed tail must not double-apply).
+  const fence = memFence();
+  const applied: string[] = [];
+  const outcome = await fenceReplay([comment("c-1"), comment("c-1")], fence, (e) => {
+    applied.push(e.idempotencyKey);
+  });
+  assertEquals(applied, ["c-1"], "the effect is applied exactly once");
+  assertEquals(outcome.skipped.length, 1, "the duplicate is skipped");
+});
+
+test("a second replay of the same tail is a total no-op — idempotent resume", async () => {
+  const fence = memFence();
+  const tail = [push("sha-1"), comment("c-1")];
+  const applyCount = { n: 0 };
+  await fenceReplay(tail, fence, () => {
+    applyCount.n++;
+  });
+  assertEquals(applyCount.n, 2, "first replay applies both");
+  await fenceReplay(tail, fence, () => {
+    applyCount.n++;
+  });
+  assertEquals(applyCount.n, 2, "second replay applies nothing — the fence holds across resumes");
+});

package/app/world/effect-ledger.ts

@@ -0,0 +1,103 @@
+// nano-workforce — the effect ledger + fence for durable agent-session resume (issue #324, ADR 0062
+// Slice 4/5, the WORLD half).
+//
+// Durable resume reconstructs the git working tree by INVERTING the forward op: the round's outbound
+// `git push` becomes an inbound `git fetch && git checkout <sha>` (see ./checkpoint.ts). But a round
+// also performs OTHER irreversible actions that are NOT captured by the pushed tree — a PR comment, a
+// `gh merge`. Replaying blindly on a resume would DUPLICATE them (a second identical review comment,
+// a re-attempted merge). The fence stops that: every irreversible action is recorded in an EFFECT
+// LEDGER with an idempotency key (the effect's natural identity — a commit SHA, a comment id, a merge
+// key). On restore we replay the post-checkpoint effect tail THROUGH the fence, so an already-applied
+// effect is SKIPPED, not repeated.
+//
+// This module is PURE (no I/O): the durable ledger lives in ./store.ts, the git inversion in
+// ./git.ts, and the orchestration in ./checkpoint.ts. Keeping the fence a pure fold makes the
+// "no duplicate effect on replay" invariant unit-testable without a database or a real git tree.
+
+/** The classes of irreversible action the world-restore fence guards. Each maps to a natural
+ * idempotency key: a `push` to its commit SHA, a `pr-comment` to the comment id, a `merge` to the
+ * merge key. Anything reversible (a scratch file write reconstructed by the checkout) is NOT an
+ * effect — only actions whose re-execution would be observable to the outside world belong here.
+ *
+ * The runtime tuple is the ONE canonical list (derivation over duplication): {@link EffectKind} is
+ * derived from it, and a contract boundary that must validate an externally-supplied kind (e.g. the
+ * `worldMarker` the harness reports) checks membership against it rather than re-listing the values. */
+export const EFFECT_KINDS = ["push", "pr-comment", "merge"] as const;
+export type EffectKind = (typeof EFFECT_KINDS)[number];
+
+/** True when `kind` is one of the known {@link EFFECT_KINDS}. The guard a contract boundary uses to
+ * reject an unexpected effect kind before it enters the durable ledger. */
+export function isEffectKind(kind: unknown): kind is EffectKind {
+  return typeof kind === "string" && EFFECT_KINDS.some((k) => k === kind);
+}
+
+/** True when `sha` is a well-formed 40-hex git commit SHA (a full object name). The world-restore
+ * marker's `commitSha` is used as an EXACT checkout target (`git fetch && git checkout <sha>`), so a
+ * branch name, an abbreviated/short ref, or a whitespace-tainted value could reconstruct to a moved
+ * branch tip or fail restore — undermining the "reconstruct the exact tree at <sha>" contract. Both
+ * the EMIT boundary (`repoEnvelopeVars`) and the READ boundary (`worldMarkerOf`) validate through
+ * this ONE canonical matcher so the two can never drift. */
+export function isCommitSha(sha: unknown): sha is string {
+  return typeof sha === "string" && /^[0-9a-f]{40}$/i.test(sha);
+}
+
+/** One irreversible action in the effect ledger. `idempotencyKey` is the effect's natural identity —
+ * the value that makes "did this already happen?" answerable WITHOUT re-doing it. Two ledger entries
+ * with the same key denote the same real-world effect, so the fence collapses them to one. */
+export interface Effect {
+  readonly kind: EffectKind;
+  /** The effect's natural, stable identity (commit SHA / comment id / merge key). The fence key. */
+  readonly idempotencyKey: string;
+  /** A human audit note (optional) — never load-bearing for fence identity. */
+  readonly description?: string;
+}
+
+/** The durable fence seam the replay folds over. `isApplied` answers "has this effect's idempotency
+ * key already landed?" from the ledger; `markApplied` records that an effect has now been realised so
+ * a LATER resume skips it too. Both are async so a real SQLite-backed ledger (./store.ts) satisfies
+ * them, while an in-memory `Set` satisfies them in tests. */
+export interface Fence {
+  isApplied(idempotencyKey: string): boolean | Promise<boolean>;
+  markApplied(effect: Effect): void | Promise<void>;
+}
+
+/** The breakdown of a fenced replay: which tail effects were (re)applied and which the fence skipped
+ * because they had already landed. `skipped` being the whole already-applied prefix is what makes a
+ * resume idempotent — the acceptance criterion "no duplicate push/comment (fence holds)". */
+export interface FenceOutcome {
+  readonly applied: Effect[];
+  readonly skipped: Effect[];
+}
+
+/**
+ * Replay an ordered effect tail through the fence: for each effect IN ORDER, if the fence already
+ * has its idempotency key it is skipped (never re-applied); otherwise `apply` runs the real side
+ * effect and the fence records it as applied so no later resume repeats it.
+ *
+ * The ordering is load-bearing — effects must replay in the sequence they were recorded (a comment
+ * that references a push must not run before it) — so this is a strict left-fold, never a parallel
+ * map. `apply` is invoked ONLY for genuinely-missing effects, which is the whole point: a replacement
+ * activation that crashed AFTER a push but BEFORE its trailing comment replays only the comment.
+ */
+export async function fenceReplay(
+  effects: readonly Effect[],
+  fence: Fence,
+  apply: (effect: Effect) => void | Promise<void>,
+): Promise<FenceOutcome> {
+  const applied: Effect[] = [];
+  const skipped: Effect[] = [];
+  const seenThisReplay = new Set<string>();
+  for (const effect of effects) {
+    // Guard against a duplicate key WITHIN this tail too (a malformed ledger), not just against the
+    // durable fence — two entries with one key are one effect, so the second is always a skip.
+    if (seenThisReplay.has(effect.idempotencyKey) || (await fence.isApplied(effect.idempotencyKey))) {
+      skipped.push(effect);
+      continue;
+    }
+    await apply(effect);
+    await fence.markApplied(effect);
+    seenThisReplay.add(effect.idempotencyKey);
+    applied.push(effect);
+  }
+  return { applied, skipped };
+}

package/app/world/git.ts

@@ -0,0 +1,53 @@
+// nano-workforce — the git seam for world-restore (issue #324, ADR 0062 Slice 4/5, the WORLD half).
+//
+// World-restore INVERTS the round's forward `git push`: on a replacement activation the outbound push
+// of a SHA becomes an INBOUND `git fetch && git checkout <sha>` that reconstructs the exact working
+// tree on a fresh worktree. This module is the thin, INJECTABLE git port that inversion runs over —
+// `restoreWorld` (./checkpoint.ts) depends on the `GitRunner` interface, never on `child_process`
+// directly, so the restore orchestration is unit-testable against a fake runner (no real repo).
+//
+// The production runner shells out to the host `git` with an argument VECTOR (no shell), mirroring
+// `app/github.ts` `runGh` — a `pr_key`/SHA from the datastore is passed as an argv element and can
+// never inject a command.
+
+/** The minimal git surface world-restore needs — the inbound half of the push→pull inversion. */
+export interface GitRunner {
+  /** Fetch refs (and their objects) from `remote` so a subsequently-named SHA is reachable locally.
+   * The forward op pushed to this remote; fetching is its inverse. */
+  fetch(remote?: string): Promise<void>;
+  /** Check the working tree out to an exact commit SHA — the reconstruction step. Detaches HEAD at
+   * `<sha>`, which is precisely the durable resume boundary the round pushed. */
+  checkout(ref: string): Promise<void>;
+  /** Resolve a ref to its commit SHA (e.g. to confirm HEAD landed on the expected checkpoint). */
+  revParse(ref: string): Promise<string>;
+}
+
+/** Run the host `git` with the given args in `cwd` (no shell — args are an argv vector, so a
+ * datastore-sourced SHA cannot inject a command). Resolves stdout, rejects on non-zero exit with
+ * stderr as the message. Mirrors `app/github.ts` `runGh`. */
+async function runGit(args: string[], cwd?: string): Promise<string> {
+  const { execFile } = await import("node:child_process");
+  return await new Promise<string>((resolve, reject) => {
+    execFile("git", args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(String(stderr || "").trim() || err.message));
+      else resolve(String(stdout));
+    });
+  });
+}
+
+/** The production `GitRunner` over the host `git`, operating in `cwd` (the provisioned worktree).
+ * `fetch` requests the objects for a subsequent `checkout <sha>`; a bare SHA (not on a branch tip)
+ * is fetchable when the remote allows it, which is the reconstruct-to-exact-SHA case. */
+export function execGitRunner(cwd?: string): GitRunner {
+  return {
+    async fetch(remote = "origin") {
+      await runGit(["fetch", remote], cwd);
+    },
+    async checkout(ref) {
+      await runGit(["checkout", "--detach", ref], cwd);
+    },
+    async revParse(ref) {
+      return (await runGit(["rev-parse", ref], cwd)).trim();
+    },
+  };
+}

package/app/world/index.ts

@@ -0,0 +1,26 @@
+// nano-workforce — the WORLD half of durable agent-session resume (issue #324, ADR 0062 Slice 4/5).
+// Barrel over the world-restore surface: the effect ledger + fence, the durable store, the git
+// inversion seam, and the checkpoint JOIN + RESTORE orchestration.
+
+export {
+  type CheckpointSink,
+  type RestoreOptions,
+  recordWorldCheckpoint,
+  restoreWorld,
+  type SessionCheckpoint,
+  type WorldCheckpointInput,
+  type WorldCheckpointResult,
+  type WorldRestoreResult,
+} from "./checkpoint.ts";
+export {
+  EFFECT_KINDS,
+  type Effect,
+  type EffectKind,
+  type Fence,
+  type FenceOutcome,
+  fenceReplay,
+  isCommitSha,
+  isEffectKind,
+} from "./effect-ledger.ts";
+export { execGitRunner, type GitRunner } from "./git.ts";
+export { type LastCheckpoint, type RecordCheckpointInput, WorldStore } from "./store.ts";