gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/src/resources/extensions/gsd/tests/test-helpers.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Tests for test-helpers.ts — the source-inspection and timing helpers
+ * introduced in #4773 / #4774 to replace brittle fixed-byte slice and
+ * magic-number sleep patterns in the test suite.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { extractSourceRegion, waitForCondition, findLine } from "./test-helpers.ts";
+
+// ─── extractSourceRegion ──────────────────────────────────────────────────
+
+test("extractSourceRegion returns empty string when start anchor missing", () => {
+  assert.equal(extractSourceRegion("const x = 1;", "missing"), "");
+});
+
+test("extractSourceRegion uses explicit end anchor when provided", () => {
+  const src = "START_TOKEN\nbody line\nEND_TOKEN tail";
+  const region = extractSourceRegion(src, "START_TOKEN", "END_TOKEN");
+  assert.ok(region.includes("START_TOKEN"));
+  assert.ok(region.includes("body line"));
+  assert.ok(!region.includes("END_TOKEN"));
+});
+
+test("extractSourceRegion stops at next private method boundary", () => {
+  const src = [
+    "class Foo {",
+    "  private alpha(): void {",
+    "    const a = 1;",
+    "    someCall();",
+    "  }",
+    "",
+    "  private beta(): void {",
+    "    const b = 2;",
+    "  }",
+    "}",
+  ].join("\n");
+
+  // Anchor on alpha's declaration; helper should stop at the next
+  // private method (beta), not on alpha itself.
+  const region = extractSourceRegion(src, "private alpha");
+  assert.ok(region.includes("alpha"));
+  assert.ok(region.includes("someCall()"));
+  assert.ok(!region.includes("beta"));
+});
+
+test("extractSourceRegion stops at next top-level function", () => {
+  const src = [
+    "function alpha() {",
+    "  throw new Error('alpha');",
+    "}",
+    "",
+    "function beta() {",
+    "  return 2;",
+    "}",
+  ].join("\n");
+
+  const region = extractSourceRegion(src, "function alpha");
+  assert.ok(region.includes("throw new Error"));
+  assert.ok(!region.includes("beta"));
+});
+
+test("extractSourceRegion returns to end-of-source when no terminator found", () => {
+  const src = "just one line";
+  assert.equal(extractSourceRegion(src, "just"), "just one line");
+});
+
+// ─── waitForCondition ─────────────────────────────────────────────────────
+
+test("waitForCondition returns immediately when condition is true", async () => {
+  const result = await waitForCondition(() => true);
+  assert.equal(result, true);
+});
+
+test("waitForCondition waits and returns when condition becomes true", async () => {
+  let flipped = false;
+  setTimeout(() => { flipped = true; }, 30);
+  const result = await waitForCondition(() => flipped, { intervalMs: 5 });
+  assert.equal(result, true);
+});
+
+test("waitForCondition throws after timeout with description", async () => {
+  await assert.rejects(
+    waitForCondition(() => false, { timeoutMs: 50, intervalMs: 5, description: "the flag to flip" }),
+    /waiting for the flag to flip/i,
+  );
+});
+
+test("waitForCondition surfaces last error on timeout", async () => {
+  await assert.rejects(
+    waitForCondition(
+      () => { throw new Error("probe failed"); },
+      { timeoutMs: 30, intervalMs: 5, description: "probe" },
+    ),
+    /probe failed/,
+  );
+});
+
+test("waitForCondition returns the truthy value (not just true)", async () => {
+  let n = 0;
+  const result = await waitForCondition(() => {
+    n++;
+    return n >= 3 ? { ready: true, iteration: n } : null;
+  }, { intervalMs: 5 });
+  // The helper only resolves when the condition returns a truthy value, so
+  // result cannot be null here. Assert it and narrow for the follow-ups.
+  assert.ok(result, "waitForCondition must resolve with a truthy value, not null");
+  assert.equal(result.ready, true);
+  assert.equal(result.iteration, 3);
+});
+
+// ─── findLine ─────────────────────────────────────────────────────────────
+
+test("findLine locates a line by regex", () => {
+  const output = "header\nstatus: ok\nfooter";
+  const match = findLine(output, /^status:/);
+  assert.equal(match.index, 1);
+  assert.equal(match.text, "status: ok");
+});
+
+test("findLine locates a line by predicate", () => {
+  const output = "a\nb\nc";
+  const match = findLine(output, (l) => l === "b");
+  assert.equal(match.index, 1);
+  assert.equal(match.text, "b");
+});
+
+test("findLine throws with preview when no line matches", () => {
+  assert.throws(
+    () => findLine("a\nb\nc", /NOTFOUND/),
+    /First 10 lines/,
+  );
+});
+
+test("findLine resets lastIndex between lines for /g regex patterns", () => {
+  // Without the reset, RegExp.test with /g flag stateful-advances lastIndex
+  // and can skip matches on subsequent calls. Verify the reset keeps
+  // per-line testing deterministic.
+  const output = "foo\nfoo\nfoo";
+  const globalRe = /foo/g;
+  const match = findLine(output, globalRe);
+  assert.equal(match.index, 0);
+  // Second call on the same pattern must also match — would fail without reset
+  const match2 = findLine(output, globalRe);
+  assert.equal(match2.index, 0);
+});

package/src/resources/extensions/gsd/tests/test-helpers.ts

@@ -59,3 +59,143 @@ export function createTestContext() {
 
   return { assertEq, assertTrue, assertMatch, assertNoMatch, report };
 }
+
+// ─── Source-inspection helpers ────────────────────────────────────────────────
+//
+// Replace brittle fixed-byte slice patterns like `src.slice(idx, idx + 6000)`
+// with structural boundary detection. See #4773, #4774.
+
+/**
+ * Extract a region of source between a start anchor and either an explicit
+ * end anchor or, if none is given, a set of reasonable structural
+ * terminators (next `private `/`export `/`function `/`class `/`interface `/
+ * `//` section separator). Falls back to end-of-source if none match.
+ *
+ * Use this instead of `src.slice(startIdx, startIdx + N)` when searching
+ * for patterns within a specific method or region — the start anchor is
+ * what the caller already has, and the end is determined by structure,
+ * not by a magic byte count that breaks under refactors.
+ *
+ * @param src        The source text.
+ * @param startAnchor Literal substring that marks the start of the region.
+ *                   Typically a function name, a section header comment, or
+ *                   a distinctive statement.
+ * @param endAnchor  Optional. Either a literal substring that marks the end,
+ *                   or `{ fromIdx: number }` to find the *next* occurrence
+ *                   of `startAnchor` at or after `fromIdx` (useful when the
+ *                   anchor appears multiple times and a positional search
+ *                   is required). When omitted, structural terminators are
+ *                   used.
+ *
+ * Returns the extracted region (including the start anchor), or an empty
+ * string if `startAnchor` is not found.
+ */
+export function extractSourceRegion(
+  src: string,
+  startAnchor: string,
+  endAnchor?: string | { fromIdx: number },
+): string {
+  const fromIdx = typeof endAnchor === "object" && endAnchor !== null
+    ? endAnchor.fromIdx
+    : 0;
+  const endLiteral = typeof endAnchor === "string" ? endAnchor : undefined;
+
+  const startIdx = src.indexOf(startAnchor, fromIdx);
+  if (startIdx < 0) return "";
+
+  if (endLiteral) {
+    const endIdx = src.indexOf(endLiteral, startIdx + startAnchor.length);
+    return endIdx > 0 ? src.slice(startIdx, endIdx) : src.slice(startIdx);
+  }
+
+  // Heuristic terminators — the next sibling declaration/section.
+  const terminators = [
+    "\n  private ",
+    "\n  public ",
+    "\n  protected ",
+    "\n  static ",
+    "\nexport function ",
+    "\nexport async function ",
+    "\nfunction ",
+    "\nasync function ",
+    "\nexport class ",
+    "\nclass ",
+    "\nexport interface ",
+    "\ninterface ",
+    "\n// ─", // section separator comments
+    "\n/** ", // next docblock
+  ];
+
+  let earliestEnd = -1;
+  for (const t of terminators) {
+    const idx = src.indexOf(t, startIdx + startAnchor.length);
+    if (idx > 0 && (earliestEnd < 0 || idx < earliestEnd)) earliestEnd = idx;
+  }
+
+  return earliestEnd > 0 ? src.slice(startIdx, earliestEnd) : src.slice(startIdx);
+}
+
+/**
+ * Poll `condition()` until it returns truthy or `timeoutMs` elapses.
+ * Returns the truthy value from `condition()`, or throws on timeout.
+ *
+ * Use this instead of `await new Promise(r => setTimeout(r, <magic-ms>))`
+ * when waiting for a state change that tests produce. The fixed-sleep
+ * pattern is flaky: too short → race; too long → slow tests.
+ *
+ * @param condition  Predicate. Returns truthy when done. May be async.
+ * @param opts.timeoutMs  Max total wait. Defaults to 2000ms.
+ * @param opts.intervalMs Poll interval. Defaults to 10ms.
+ * @param opts.description Included in the timeout error for debuggability.
+ */
+export async function waitForCondition<T>(
+  condition: () => T | Promise<T>,
+  opts: { timeoutMs?: number; intervalMs?: number; description?: string } = {},
+): Promise<T> {
+  const timeoutMs = opts.timeoutMs ?? 2000;
+  const intervalMs = opts.intervalMs ?? 10;
+  const deadline = Date.now() + timeoutMs;
+  let lastErr: unknown;
+  while (Date.now() < deadline) {
+    try {
+      const result = await condition();
+      if (result) return result;
+    } catch (e) {
+      lastErr = e;
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  const desc = opts.description ?? "condition";
+  const errSuffix = lastErr instanceof Error ? ` (last error: ${lastErr.message})` : "";
+  throw new Error(`waitForCondition timed out after ${timeoutMs}ms waiting for ${desc}${errSuffix}`);
+}
+
+/**
+ * Find the first line in rendered output that matches a predicate. Returns
+ * the line's index and text, or throws if no line matches.
+ *
+ * Use this instead of `lines[N]` indexing when the N is positional and
+ * could shift under formatting changes.
+ */
+export function findLine(
+  output: string,
+  predicate: RegExp | ((line: string) => boolean),
+): { index: number; text: string } {
+  const lines = output.split("\n");
+  const fn = predicate instanceof RegExp
+    ? (l: string) => {
+        // RegExp.test is stateful when the pattern has /g or /y flags
+        // (maintains lastIndex across calls). Reset before each test so
+        // matches on different lines don't silently skip.
+        if (predicate.global || predicate.sticky) predicate.lastIndex = 0;
+        return predicate.test(l);
+      }
+    : predicate;
+  for (let i = 0; i < lines.length; i++) {
+    if (fn(lines[i]!)) return { index: i, text: lines[i]! };
+  }
+  const preview = lines.slice(0, 10).join("\n");
+  throw new Error(
+    `findLine: no line matched. First 10 lines were:\n${preview}`,
+  );
+}

package/src/resources/extensions/gsd/tests/token-profile.test.ts

@@ -14,6 +14,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -127,7 +128,13 @@ test("profile: balanced profile skips research, reassess, and slice research (AD
 
 test("profile: quality profile skips research, slice research, and reassess (ADR-003)", () => {
   const qualityIdx = preferencesSrc.indexOf('case "quality":');
-  const qualityBlock = preferencesSrc.slice(qualityIdx, qualityIdx + 300);
+  // preferencesSrc is concatenated from multiple modules — bound the region
+  // with the next case marker so the assertion stays tightly scoped.
+  const qualityBlock = extractSourceRegion(
+    preferencesSrc,
+    'case "quality":',
+    'case "burn-max":',
+  );
   assert.ok(qualityBlock.includes("skip_research: true"), "quality should skip research");
   assert.ok(qualityBlock.includes("skip_slice_research: true"), "quality should skip slice research");
   assert.ok(qualityBlock.includes("skip_reassess: true"), "quality should skip reassess");

package/src/resources/extensions/gsd/tests/triage-resolution.test.ts

@@ -258,6 +258,55 @@ test("resolution: markCaptureExecuted is idempotent", () => {
   }
 });
 
+// ─── executeTriageResolutions + note execution (#3578) ──────────────────────
+
+test("resolution: executeTriageResolutions stamps note captures as executed", () => {
+  const tmp = makeTempDir("res-exec-note");
+  try {
+    const id = appendCapture(tmp, "FYI the API changed");
+    markCaptureResolved(tmp, id, "note", "acknowledged", "informational");
+
+    const result = executeTriageResolutions(tmp, "M001", "S01");
+
+    // The note should now be marked as executed
+    const all = loadAllCaptures(tmp);
+    assert.strictEqual(all.length, 1);
+    assert.strictEqual(all[0].executed, true, "note capture should be marked as executed");
+
+    // It should appear in the actions log
+    assert.ok(
+      result.actions.some(a => a.includes(id) && a.includes("Note acknowledged")),
+      "actions should include a note-acknowledged entry",
+    );
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("resolution: executeTriageResolutions does not double-stamp already-executed notes", () => {
+  const tmp = makeTempDir("res-exec-note-idem");
+  try {
+    const id = appendCapture(tmp, "informational note");
+    markCaptureResolved(tmp, id, "note", "acknowledged", "info");
+
+    // First execution — stamps the note
+    executeTriageResolutions(tmp, "M001", "S01");
+
+    // Second execution — should be a no-op for the note
+    const result2 = executeTriageResolutions(tmp, "M001", "S01");
+
+    assert.strictEqual(result2.actions.length, 0, "second call should produce no actions");
+
+    // Verify the Executed field was not duplicated in the file
+    const filePath = join(tmp, ".gsd", "CAPTURES.md");
+    const content = readFileSync(filePath, "utf-8");
+    const executedMatches = content.match(/\*\*Executed:\*\*/g);
+    assert.strictEqual(executedMatches?.length, 1, "should have exactly one Executed field");
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
 // ─── loadActionableCaptures ──────────────────────────────────────────────────
 
 test("resolution: loadActionableCaptures returns only unexecuted actionable captures", () => {
@@ -387,8 +436,7 @@ test("resolution: executeTriageResolutions handles mixed classifications", () =>
     assert.strictEqual(result.injected, 1, "should inject 1 task");
     assert.strictEqual(result.replanned, 0);
     assert.strictEqual(result.quickTasks.length, 1, "should queue 1 quick-task");
-    // inject + quick-task + note acknowledged = 3 actions (defer still excluded)
-    assert.strictEqual(result.actions.length, 3, "should have 3 action entries (defer excluded, note now included)");
+    assert.strictEqual(result.actions.length, 3, "should have 3 action entries (inject + quick-task + note acknowledged; defer excluded)");
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }

package/src/resources/extensions/gsd/tests/turn-epoch.test.ts

@@ -0,0 +1,162 @@
+// Project: gsd-pi — Tests for the auto/turn-epoch stale-write guard.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  _resetTurnEpoch,
+  bumpTurnGeneration,
+  describeTurnEpoch,
+  getCurrentTurnGeneration,
+  isStaleWrite,
+  runWithTurnGeneration,
+} from "../auto/turn-epoch.ts";
+
+test("turn-epoch: generation starts at 0 and bumps monotonically", () => {
+  _resetTurnEpoch();
+  assert.equal(getCurrentTurnGeneration(), 0);
+  assert.equal(bumpTurnGeneration("test-a"), 1);
+  assert.equal(bumpTurnGeneration("test-b"), 2);
+  assert.equal(getCurrentTurnGeneration(), 2);
+});
+
+test("turn-epoch: isStaleWrite returns false when no turn context captured", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("no-context");
+  // Called outside runWithTurnGeneration — safe default is false.
+  assert.equal(isStaleWrite("out-of-band"), false);
+});
+
+test("turn-epoch: isStaleWrite returns false inside a fresh turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    assert.equal(isStaleWrite("fresh"), false);
+  });
+});
+
+test("turn-epoch: isStaleWrite returns true after the epoch bumps mid-turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    bumpTurnGeneration("recovery-fires");
+    assert.equal(isStaleWrite("stale"), true);
+  });
+});
+
+test("turn-epoch: nested turns each see their own captured generation", () => {
+  _resetTurnEpoch();
+  const outerGen = getCurrentTurnGeneration();
+  runWithTurnGeneration(outerGen, () => {
+    assert.equal(isStaleWrite("outer-fresh"), false);
+    bumpTurnGeneration("bump-between");
+    const innerGen = getCurrentTurnGeneration();
+    runWithTurnGeneration(innerGen, () => {
+      // Inner context saw the bumped generation at capture time — fresh.
+      assert.equal(isStaleWrite("inner-fresh"), false);
+    });
+    // Back to outer context — still stale because outerGen < current.
+    assert.equal(isStaleWrite("outer-after-bump"), true);
+  });
+});
+
+test("turn-epoch: describeTurnEpoch surfaces captured vs current", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("seed");
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    let snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured);
+    assert.equal(snapshot.stale, false);
+
+    bumpTurnGeneration("supersede");
+    snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured + 1);
+    assert.equal(snapshot.stale, true);
+  });
+
+  // Outside the turn — captured is null, stale is false.
+  const outside = describeTurnEpoch();
+  assert.equal(outside.captured, null);
+  assert.equal(outside.stale, false);
+});
+
+test("turn-epoch: AsyncLocalStorage propagates across awaits", async () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  await runWithTurnGeneration(captured, async () => {
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 1));
+    bumpTurnGeneration("async-bump");
+    await Promise.resolve();
+    assert.equal(isStaleWrite("post-await"), true);
+  });
+});
+
+// ─── Source-level invariant checks for recoverTimedOutUnit ──────────────────
+//
+// The recoverTimedOutUnit function has two branch families:
+// - ADVANCE branches: the unit is done, loop moves on — these MUST bump.
+// - STEERING branches: the same LLM turn is kept alive with a steering
+//   message — these MUST NOT bump (otherwise the retry's legitimate writes
+//   get marked stale).
+//
+// The whole function must contain zero raw `resolveAgentEnd` calls with the
+// "timeout-recovery" _synthetic marker — all advance paths go through
+// bumpAndResolveSynthetic. And there must be no top-level bump call.
+
+test("recoverTimedOutUnit: no raw `resolveAgentEnd({ _synthetic: \"timeout-recovery\" })` calls remain", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const rawSyntheticResolve =
+    /resolveAgentEnd\s*\(\s*\{\s*messages:\s*\[\s*\]\s*,\s*_synthetic:\s*["']timeout-recovery/;
+  assert.equal(
+    rawSyntheticResolve.test(src),
+    false,
+    "auto-timeout-recovery.ts must funnel advance paths through bumpAndResolveSynthetic — a raw resolveAgentEnd with _synthetic:\"timeout-recovery\" would leak orphan writes",
+  );
+});
+
+test("recoverTimedOutUnit: no top-level bumpTurnGeneration — steering branches must not supersede", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  // The only bump surface allowed is via bumpAndResolveSynthetic (advance
+  // paths) — a direct bumpTurnGeneration call in this file would bump even
+  // when the function later decides to take a steering retry branch.
+  assert.equal(
+    /\bbumpTurnGeneration\s*\(/.test(src),
+    false,
+    "auto-timeout-recovery.ts must not call bumpTurnGeneration directly — use bumpAndResolveSynthetic so bump and supersede are atomic and tied to advance-only branches",
+  );
+});
+
+test("recoverTimedOutUnit: bumpAndResolveSynthetic appears exactly four times (one per advance branch)", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const matches = src.match(/bumpAndResolveSynthetic\s*\(/g) ?? [];
+  assert.equal(
+    matches.length,
+    4,
+    `expected 4 advance-branch supersede sites (durableComplete, execute-task-exhausted, artifact-already-exists, non-execute-exhausted); found ${matches.length}`,
+  );
+});

package/src/resources/extensions/gsd/tests/uok-contracts.test.ts

@@ -3,12 +3,16 @@ import assert from "node:assert/strict";
 
 import type {
   AuditEventEnvelope,
+  UokDispatchEnvelope,
   GateResult,
   TurnContract,
   TurnResult,
   UokNodeKind,
+  WriteRecord,
+  WriterToken,
 } from "../uok/contracts.ts";
 import { buildAuditEnvelope } from "../uok/audit.ts";
+import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -84,3 +88,50 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
 });
+
+test("uok dispatch envelope carries scheduler reason and constraints", () => {
+  const envelope: UokDispatchEnvelope = buildDispatchEnvelope({
+    action: "dispatch",
+    node: {
+      kind: "unit",
+      dependsOn: ["plan-gate"],
+      reads: ["M001-ROADMAP.md"],
+      writes: ["M001/S01/T01-SUMMARY.md"],
+    },
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    prompt: "do work",
+    reasonCode: "dependency",
+    summary: "all dependencies are closed and output path is available",
+    evidence: { readyTaskCount: 1 },
+  });
+
+  assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.reason.reasonCode, "dependency");
+  assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
+  assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+});
+
+test("uok writer records serialize sequence metadata", () => {
+  const token: WriterToken = {
+    tokenId: "token-1",
+    traceId: "trace-1",
+    turnId: "turn-1",
+    acquiredAt: new Date().toISOString(),
+    owner: "uok",
+  };
+
+  const record: WriteRecord = {
+    writerToken: token,
+    sequence: { traceId: token.traceId, turnId: token.turnId, sequence: 7 },
+    category: "audit",
+    operation: "append",
+    path: ".gsd/audit/events.jsonl",
+    ts: new Date().toISOString(),
+  };
+
+  const roundTrip = JSON.parse(JSON.stringify(record)) as WriteRecord;
+  assert.equal(roundTrip.writerToken.tokenId, "token-1");
+  assert.equal(roundTrip.sequence.sequence, 7);
+  assert.equal(roundTrip.category, "audit");
+});

package/src/resources/extensions/gsd/tests/uok-execution-graph.test.ts

@@ -5,6 +5,7 @@ import {
   selectConflictFreeBatch,
   selectReactiveDispatchBatch,
   buildSidecarQueueNodes,
+  buildExecutionGraphSnapshot,
   scheduleSidecarQueue,
 } from "../uok/execution-graph.ts";
 
@@ -67,3 +68,18 @@ test("uok execution graph sidecar scheduler preserves deterministic queue order"
     queue.map((item) => item.unitId),
   );
 });
+
+test("uok execution graph snapshot captures deterministic order and conflicts", () => {
+  const snapshot = buildExecutionGraphSnapshot(
+    [
+      { id: "b", kind: "unit", dependsOn: ["a"], writes: ["src/shared.ts"] },
+      { id: "a", kind: "unit", dependsOn: [], writes: ["src/a.ts"] },
+      { id: "c", kind: "verification", dependsOn: [], writes: ["src/shared.ts"] },
+    ],
+    "before-unit",
+  );
+
+  assert.equal(snapshot.phase, "before-unit");
+  assert.deepEqual(snapshot.order, ["a", "b", "c"]);
+  assert.ok(snapshot.conflicts.some((c) => c.file === "src/shared.ts"));
+});