@cueloop/schema 0.1.0-alpha.15 → 0.1.0-alpha.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {

package/src/anchor.test.ts

@@ -15,76 +15,76 @@ Sessions are written as one JSON document per session. Sessions are written
 atomically.
 `;
 
-function blocksOf(md: string) {
-  return parseBlocks(md);
+function blocksOf(markdown: string) {
+  return parseBlocks(markdown);
 }
 
 describe("anchor cascade", () => {
   test("makeAnchor captures quote + context selectors", () => {
     const blocks = blocksOf(DOC);
-    const ctxIdx = blocks.findIndex((b) => b.text.startsWith("Review sessions"));
-    const a = makeAnchor(blocks, ctxIdx, 0, 15); // "Review sessions"
-    expect(a.quote).toBe("Review sessions");
-    expect(a.prefix).toBe("");
-    expect(a.suffix.startsWith(" currently")).toBe(true);
+    const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
+    const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15); // "Review sessions"
+    expect(anchor.quote).toBe("Review sessions");
+    expect(anchor.prefix).toBe("");
+    expect(anchor.suffix.startsWith(" currently")).toBe(true);
   });
 
   test("resolves at the recorded position when unchanged", () => {
     const blocks = blocksOf(DOC);
-    const ctxIdx = blocks.findIndex((b) => b.text.startsWith("Review sessions"));
-    const a = makeAnchor(blocks, ctxIdx, 7, 15); // "sessions"
-    const r = resolveAnchor(a, blocks)!;
-    expect(r.blockIndex).toBe(ctxIdx);
-    expect(r.start).toBe(7);
-    expect(r.approximate).toBe(false);
+    const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
+    const anchor = makeAnchor(blocks, contextBlockIndex, 7, 15); // "sessions"
+    const resolved = resolveAnchor(anchor, blocks)!;
+    expect(resolved.blockIndex).toBe(contextBlockIndex);
+    expect(resolved.start).toBe(7);
+    expect(resolved.approximate).toBe(false);
   });
 
   test("survives text changes before the quote (quote search)", () => {
     const blocks = blocksOf(DOC);
-    const ctxIdx = blocks.findIndex((b) => b.text.startsWith("Review sessions"));
-    const a = makeAnchor(blocks, ctxIdx, 0, 15);
+    const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
+    const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15);
     const edited = blocksOf(DOC.replace("Review sessions currently", "PREFIX. Review sessions now"));
-    const r = resolveAnchor(a, edited)!;
-    const idx = edited.findIndex((b) => b.text.includes("Review sessions"));
-    expect(r.blockIndex).toBe(idx);
-    expect(edited[r.blockIndex]!.text.slice(r.start, r.end)).toBe("Review sessions");
+    const resolved = resolveAnchor(anchor, edited)!;
+    const editedBlockIndex = edited.findIndex((block) => block.text.includes("Review sessions"));
+    expect(resolved.blockIndex).toBe(editedBlockIndex);
+    expect(edited[resolved.blockIndex]!.text.slice(resolved.start, resolved.end)).toBe("Review sessions");
   });
 
   test("prefix/suffix selectors disambiguate repeated quotes", () => {
     const blocks = blocksOf(DOC);
-    const storIdx = blocks.findIndex((b) => b.text.includes("atomically"));
+    const storageBlockIndex = blocks.findIndex((block) => block.text.includes("atomically"));
     // anchor on the SECOND "Sessions are written" occurrence
-    const text = blocks[storIdx]!.text;
+    const text = blocks[storageBlockIndex]!.text;
     const second = text.indexOf("Sessions are written", text.indexOf("Sessions are written") + 1);
-    const a = makeAnchor(blocks, storIdx, second, second + "Sessions are written".length);
-    const r = resolveAnchor(a, blocks)!;
-    expect(r.start).toBe(second);
+    const anchor = makeAnchor(blocks, storageBlockIndex, second, second + "Sessions are written".length);
+    const resolved = resolveAnchor(anchor, blocks)!;
+    expect(resolved.start).toBe(second);
   });
 
   test("position hint breaks ties when context also repeats", () => {
-    const md = "word word word";
-    const blocks = blocksOf(md);
-    const a = makeAnchor(blocks, 0, 5, 9); // middle "word"
-    const r = resolveAnchor(a, blocks)!;
-    expect(r.start).toBe(5);
+    const repeatedWords = "word word word";
+    const blocks = blocksOf(repeatedWords);
+    const anchor = makeAnchor(blocks, 0, 5, 9); // middle "word"
+    const resolved = resolveAnchor(anchor, blocks)!;
+    expect(resolved.start).toBe(5);
   });
 
   test("trimmed-quote fallback marks the resolution approximate", () => {
     const blocks = blocksOf("some text here");
-    const a = { quote: " text ", prefix: "some", suffix: "here", blockIndex: 0, start: 4, end: 10 };
+    const anchor = { quote: " text ", prefix: "some", suffix: "here", blockIndex: 0, start: 4, end: 10 };
     const edited = blocksOf("some\ntext\nhere");
     // " text " (with spaces) is gone, "text" survives
-    const r = resolveAnchor(a, edited);
-    expect(r).not.toBeNull();
-    expect(r!.approximate).toBe(true);
+    const resolved = resolveAnchor(anchor, edited);
+    expect(resolved).not.toBeNull();
+    expect(resolved!.approximate).toBe(true);
   });
 
   test("orphans when the quote is gone entirely", () => {
     const blocks = blocksOf(DOC);
-    const ctxIdx = blocks.findIndex((b) => b.text.startsWith("Review sessions"));
-    const a = makeAnchor(blocks, ctxIdx, 0, 15);
+    const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
+    const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15);
     const edited = blocksOf(DOC.replace(/Review sessions[^\n]*\n[^\n]*/, "Completely different text."));
-    expect(resolveAnchor(a, edited)).toBeNull();
+    expect(resolveAnchor(anchor, edited)).toBeNull();
   });
 
   test("empty quote never binds", () => {

package/src/anchor.ts

@@ -1,6 +1,6 @@
 /**
- * Anchor resolution: the quote-primary cascade (map #2, #22, verified in the
- * edit-mode deep-dive). Anchors resolve against the current block list:
+ * Anchor resolution: the quote-primary cascade. Anchors resolve against the
+ * current block list:
  *   1. exact quote in a block (prefix/suffix selectors break ties,
  *      position hint breaks remaining ties)
  *   2. trimmed quote
@@ -11,7 +11,8 @@
 import type { Anchor } from "./types";
 import type { Block } from "./markdown";
 
-const CONTEXT = 24;
+/** Characters of surrounding text captured as prefix/suffix selectors. */
+const ANCHOR_CONTEXT_CHARS = 24;
 
 export interface ResolvedAnchor {
   blockIndex: number;
@@ -22,11 +23,11 @@ export interface ResolvedAnchor {
 }
 
 export function makeAnchor(blocks: Block[], blockIndex: number, start: number, end: number): Anchor {
-  const t = blocks[blockIndex]?.text ?? "";
+  const blockText = blocks[blockIndex]?.text ?? "";
   return {
-    quote: t.slice(start, end),
-    prefix: t.slice(Math.max(0, start - CONTEXT), start),
-    suffix: t.slice(end, end + CONTEXT),
+    quote: blockText.slice(start, end),
+    prefix: blockText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start),
+    suffix: blockText.slice(end, end + ANCHOR_CONTEXT_CHARS),
     blockIndex,
     start,
     end,
@@ -38,21 +39,21 @@ interface Candidate extends ResolvedAnchor {
 }
 
 function findCandidates(anchor: Anchor, blocks: Block[], quote: string): Candidate[] {
-  const out: Candidate[] = [];
-  blocks.forEach((b, blockIndex) => {
-    const text = b.text;
-    for (let i = text.indexOf(quote); i !== -1; i = text.indexOf(quote, i + 1)) {
-      const pre = text.slice(Math.max(0, i - CONTEXT), i);
-      const suf = text.slice(i + quote.length, i + quote.length + CONTEXT);
+  const candidates: Candidate[] = [];
+  blocks.forEach((block, blockIndex) => {
+    const text = block.text;
+    for (let matchStart = text.indexOf(quote); matchStart !== -1; matchStart = text.indexOf(quote, matchStart + 1)) {
+      const prefix = text.slice(Math.max(0, matchStart - ANCHOR_CONTEXT_CHARS), matchStart);
+      const suffix = text.slice(matchStart + quote.length, matchStart + quote.length + ANCHOR_CONTEXT_CHARS);
       let score = 0;
-      if (pre === anchor.prefix) score += 2;
-      if (suf === anchor.suffix) score += 2;
+      if (prefix === anchor.prefix) score += 2;
+      if (suffix === anchor.suffix) score += 2;
       if (anchor.blockIndex === blockIndex) score += 1;
-      if (anchor.blockIndex === blockIndex && anchor.start === i) score += 1;
-      out.push({ blockIndex, start: i, end: i + quote.length, approximate: false, score });
+      if (anchor.blockIndex === blockIndex && anchor.start === matchStart) score += 1;
+      candidates.push({ blockIndex, start: matchStart, end: matchStart + quote.length, approximate: false, score });
     }
   });
-  return out;
+  return candidates;
 }
 
 /** Resolve an anchor against the current blocks, or null when orphaned. */
@@ -68,7 +69,7 @@ export function resolveAnchor(anchor: Anchor, blocks: Block[]): ResolvedAnchor |
     }
   }
   if (candidates.length === 0) return null;
-  candidates.sort((a, b) => b.score - a.score);
+  candidates.sort((left, right) => right.score - left.score);
   const best = candidates[0]!;
   return { ...best, approximate };
 }

package/src/diff.test.ts

@@ -9,10 +9,10 @@ describe("unifiedDiff", () => {
   test("produces hunk headers with correct line numbers", () => {
     const oldText = ["l1", "l2", "l3", "l4", "l5", "l6", "l7", "l8"].join("\n");
     const newText = ["l1", "l2", "l3", "CHANGED", "l5", "l6", "l7", "l8"].join("\n");
-    const d = unifiedDiff(oldText, newText, 1)!;
-    expect(d[0]!.t).toBe("hunk");
-    expect(d[0]!.text).toBe("@@ -3,3 +3,3 @@");
-    expect(d.map((l) => l.text)).toEqual([
+    const diffLines = unifiedDiff(oldText, newText, 1)!;
+    expect(diffLines[0]!.kind).toBe("hunk");
+    expect(diffLines[0]!.text).toBe("@@ -3,3 +3,3 @@");
+    expect(diffLines.map((line) => line.text)).toEqual([
       "@@ -3,3 +3,3 @@",
       " l3",
       "-l4",
@@ -26,25 +26,25 @@ describe("unifiedDiff", () => {
     const newLines = [...oldLines];
     newLines[1] = "first change";
     newLines[27] = "second change";
-    const d = unifiedDiff(oldLines.join("\n"), newLines.join("\n"), 2)!;
-    expect(d.filter((l) => l.t === "hunk").length).toBe(2);
+    const diffLines = unifiedDiff(oldLines.join("\n"), newLines.join("\n"), 2)!;
+    expect(diffLines.filter((line) => line.kind === "hunk").length).toBe(2);
   });
 
   test("applies cleanly: reconstructing new text from old + diff", () => {
     const oldText = "keep\ndrop\nkeep2\nkeep3";
     const newText = "keep\nadded\nkeep2\nkeep3\ntail";
-    const d = unifiedDiff(oldText, newText, 50)!;
+    const diffLines = unifiedDiff(oldText, newText, 50)!;
     const rebuilt: string[] = [];
-    for (const l of d) {
-      if (l.t === "hunk") continue;
-      if (l.t === "ctx" || l.t === "add") rebuilt.push(l.text.slice(1));
+    for (const line of diffLines) {
+      if (line.kind === "hunk") continue;
+      if (line.kind === "ctx" || line.kind === "add") rebuilt.push(line.text.slice(1));
     }
     expect(rebuilt.join("\n")).toBe(newText);
   });
 
   test("unifiedDiffText carries file headers and path", () => {
-    const t = unifiedDiffText("a", "b", "docs/plan.md")!;
-    expect(t.startsWith("--- a/docs/plan.md\n+++ b/docs/plan.md\n@@")).toBe(true);
+    const diffText = unifiedDiffText("a", "b", "docs/plan.md")!;
+    expect(diffText.startsWith("--- a/docs/plan.md\n+++ b/docs/plan.md\n@@")).toBe(true);
   });
 });
 
@@ -57,8 +57,8 @@ describe("editStats", () => {
 describe("wordDiff", () => {
   test("preserves whitespace tokens and reconstructs both sides", () => {
     const ops = wordDiff("the quick brown fox", "the slow brown foxes");
-    const oldSide = ops.filter((o) => o.t !== "add").map((o) => o.a).join("");
-    const newSide = ops.filter((o) => o.t !== "del").map((o) => o.b).join("");
+    const oldSide = ops.filter((op) => op.kind !== "add").map((op) => op.oldValue).join("");
+    const newSide = ops.filter((op) => op.kind !== "del").map((op) => op.newValue).join("");
     expect(oldSide).toBe("the quick brown fox");
     expect(newSide).toBe("the slow brown foxes");
   });
@@ -66,7 +66,7 @@ describe("wordDiff", () => {
 
 describe("lcsDiff", () => {
   test("custom equality", () => {
-    const ops = lcsDiff([{ v: 1 }, { v: 2 }], [{ v: 2 }, { v: 3 }], (x, y) => x.v === y.v);
-    expect(ops.map((o) => o.t)).toEqual(["del", "ctx", "add"]);
+    const ops = lcsDiff([{ v: 1 }, { v: 2 }], [{ v: 2 }, { v: 3 }], (oldItem, newItem) => oldItem.v === newItem.v);
+    expect(ops.map((op) => op.kind)).toEqual(["del", "ctx", "add"]);
   });
 });

package/src/diff.ts

@@ -1,52 +1,58 @@
 /**
  * Line/token diffing and unified-diff serialization. The working copy
- * serializes as ONE unified diff against the submitted revision (map #2).
+ * serializes as ONE unified diff against the submitted revision.
  * Pure algorithms, no IO.
  */
 
-export type DiffOpType = "ctx" | "del" | "add";
+export type DiffOpKind = "ctx" | "del" | "add";
 
 export interface DiffOp<T = string> {
-  t: DiffOpType;
+  kind: DiffOpKind;
   /** Present for ctx and del. */
-  a?: T;
+  oldValue?: T;
   /** Present for ctx and add. */
-  b?: T;
+  newValue?: T;
 }
 
 /** LCS diff over arrays. O(n*m) - fine for plan-sized documents. */
-export function lcsDiff<T>(a: T[], b: T[], eq: (x: T, y: T) => boolean = (x, y) => x === y): DiffOp<T>[] {
-  const n = a.length;
-  const m = b.length;
-  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
-  for (let i = n - 1; i >= 0; i--) {
-    for (let j = m - 1; j >= 0; j--) {
-      dp[i]![j] = eq(a[i]!, b[j]!) ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
+export function lcsDiff<T>(
+  oldItems: T[],
+  newItems: T[],
+  equals: (oldItem: T, newItem: T) => boolean = (oldItem, newItem) => oldItem === newItem,
+): DiffOp<T>[] {
+  const oldCount = oldItems.length;
+  const newCount = newItems.length;
+  const longestCommon: number[][] = Array.from({ length: oldCount + 1 }, () => new Array<number>(newCount + 1).fill(0));
+  for (let oldIndex = oldCount - 1; oldIndex >= 0; oldIndex--) {
+    for (let newIndex = newCount - 1; newIndex >= 0; newIndex--) {
+      longestCommon[oldIndex]![newIndex] = equals(oldItems[oldIndex]!, newItems[newIndex]!)
+        ? longestCommon[oldIndex + 1]![newIndex + 1]! + 1
+        : Math.max(longestCommon[oldIndex + 1]![newIndex]!, longestCommon[oldIndex]![newIndex + 1]!);
     }
   }
-  const out: DiffOp<T>[] = [];
-  let i = 0;
-  let j = 0;
-  while (i < n && j < m) {
-    if (eq(a[i]!, b[j]!)) {
-      out.push({ t: "ctx", a: a[i], b: b[j] });
-      i++;
-      j++;
-    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
-      out.push({ t: "del", a: a[i] });
-      i++;
+  const ops: DiffOp<T>[] = [];
+  let oldIndex = 0;
+  let newIndex = 0;
+  while (oldIndex < oldCount && newIndex < newCount) {
+    if (equals(oldItems[oldIndex]!, newItems[newIndex]!)) {
+      ops.push({ kind: "ctx", oldValue: oldItems[oldIndex], newValue: newItems[newIndex] });
+      oldIndex++;
+      newIndex++;
+    } else if (longestCommon[oldIndex + 1]![newIndex]! >= longestCommon[oldIndex]![newIndex + 1]!) {
+      ops.push({ kind: "del", oldValue: oldItems[oldIndex] });
+      oldIndex++;
     } else {
-      out.push({ t: "add", b: b[j] });
-      j++;
+      ops.push({ kind: "add", newValue: newItems[newIndex] });
+      newIndex++;
     }
   }
-  while (i < n) out.push({ t: "del", a: a[i++] });
-  while (j < m) out.push({ t: "add", b: b[j++] });
-  return out;
+  while (oldIndex < oldCount) ops.push({ kind: "del", oldValue: oldItems[oldIndex++] });
+  while (newIndex < newCount) ops.push({ kind: "add", newValue: newItems[newIndex++] });
+  return ops;
 }
 
 export interface UnifiedLine {
-  t: DiffOpType | "hunk";
+  kind: DiffOpKind | "hunk";
   text: string;
 }
 
@@ -56,58 +62,64 @@ export interface UnifiedLine {
  */
 export function unifiedDiff(oldText: string, newText: string, context = 3): UnifiedLine[] | null {
   const ops = lcsDiff(oldText.split("\n"), newText.split("\n"));
-  if (!ops.some((o) => o.t !== "ctx")) return null;
-  let ol = 1;
-  let nl = 1;
-  const rows = ops.map((o) => {
-    const r = {
-      t: o.t,
-      text: (o.t === "add" ? o.b : o.a) ?? "",
-      ol: o.t !== "add" ? ol : null,
-      nl: o.t !== "del" ? nl : null,
+  if (!ops.some((op) => op.kind !== "ctx")) return null;
+  let oldLineNumber = 1;
+  let newLineNumber = 1;
+  const rows = ops.map((op) => {
+    const row = {
+      kind: op.kind,
+      text: (op.kind === "add" ? op.newValue : op.oldValue) ?? "",
+      oldLine: op.kind !== "add" ? oldLineNumber : null,
+      newLine: op.kind !== "del" ? newLineNumber : null,
     };
-    if (o.t !== "add") ol++;
-    if (o.t !== "del") nl++;
-    return r;
+    if (op.kind !== "add") oldLineNumber++;
+    if (op.kind !== "del") newLineNumber++;
+    return row;
   });
   const keep = new Array<boolean>(rows.length).fill(false);
-  rows.forEach((r, idx) => {
-    if (r.t !== "ctx") {
-      for (let k = Math.max(0, idx - context); k <= Math.min(rows.length - 1, idx + context); k++) keep[k] = true;
+  rows.forEach((row, rowIndex) => {
+    if (row.kind !== "ctx") {
+      for (
+        let keepIndex = Math.max(0, rowIndex - context);
+        keepIndex <= Math.min(rows.length - 1, rowIndex + context);
+        keepIndex++
+      ) {
+        keep[keepIndex] = true;
+      }
     }
   });
   const hunks: { rows: (typeof rows)[number][] }[] = [];
-  let cur: { rows: (typeof rows)[number][] } | null = null;
-  rows.forEach((r, idx) => {
-    if (!keep[idx]) {
-      cur = null;
+  let openHunk: { rows: (typeof rows)[number][] } | null = null;
+  rows.forEach((row, rowIndex) => {
+    if (!keep[rowIndex]) {
+      openHunk = null;
       return;
     }
-    if (!cur) {
-      cur = { rows: [] };
-      hunks.push(cur);
+    if (!openHunk) {
+      openHunk = { rows: [] };
+      hunks.push(openHunk);
     }
-    cur.rows.push(r);
+    openHunk.rows.push(row);
   });
-  const out: UnifiedLine[] = [];
-  for (const h of hunks) {
-    const oStart = h.rows.find((r) => r.ol !== null)?.ol ?? 1;
-    const nStart = h.rows.find((r) => r.nl !== null)?.nl ?? 1;
-    const oCount = h.rows.filter((r) => r.t !== "add").length;
-    const nCount = h.rows.filter((r) => r.t !== "del").length;
-    out.push({ t: "hunk", text: `@@ -${oStart},${oCount} +${nStart},${nCount} @@` });
-    for (const r of h.rows) {
-      out.push({ t: r.t, text: (r.t === "add" ? "+" : r.t === "del" ? "-" : " ") + r.text });
+  const lines: UnifiedLine[] = [];
+  for (const hunk of hunks) {
+    const oldStart = hunk.rows.find((row) => row.oldLine !== null)?.oldLine ?? 1;
+    const newStart = hunk.rows.find((row) => row.newLine !== null)?.newLine ?? 1;
+    const oldCount = hunk.rows.filter((row) => row.kind !== "add").length;
+    const newCount = hunk.rows.filter((row) => row.kind !== "del").length;
+    lines.push({ kind: "hunk", text: `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@` });
+    for (const row of hunk.rows) {
+      lines.push({ kind: row.kind, text: (row.kind === "add" ? "+" : row.kind === "del" ? "-" : " ") + row.text });
     }
   }
-  return out;
+  return lines;
 }
 
 /** Render a unified diff as text with file headers. */
 export function unifiedDiffText(oldText: string, newText: string, path = "plan.md", context = 3): string | null {
-  const d = unifiedDiff(oldText, newText, context);
-  if (!d) return null;
-  return [`--- a/${path}`, `+++ b/${path}`, ...d.map((l) => l.text)].join("\n");
+  const lines = unifiedDiff(oldText, newText, context);
+  if (!lines) return null;
+  return [`--- a/${path}`, `+++ b/${path}`, ...lines.map((line) => line.text)].join("\n");
 }
 
 export interface EditStats {
@@ -116,16 +128,16 @@ export interface EditStats {
 }
 
 export function editStats(oldText: string, newText: string): EditStats {
-  const d = unifiedDiff(oldText, newText, 0);
-  if (!d) return { added: 0, removed: 0 };
+  const lines = unifiedDiff(oldText, newText, 0);
+  if (!lines) return { added: 0, removed: 0 };
   return {
-    added: d.filter((r) => r.t === "add").length,
-    removed: d.filter((r) => r.t === "del").length,
+    added: lines.filter((line) => line.kind === "add").length,
+    removed: lines.filter((line) => line.kind === "del").length,
   };
 }
 
 /** Word-level diff ops for tracked-changes rendering. Whitespace-preserving. */
 export function wordDiff(oldText: string, newText: string): DiffOp[] {
-  const tok = (s: string) => s.split(/(\s+)/).filter((x) => x !== "");
-  return lcsDiff(tok(oldText), tok(newText));
+  const tokenize = (text: string) => text.split(/(\s+)/).filter((token) => token !== "");
+  return lcsDiff(tokenize(oldText), tokenize(newText));
 }

package/src/feedback.test.ts

@@ -13,7 +13,7 @@ Review sessions live only in daemon memory today.
 Sessions are written as one JSON document per session.
 `;
 
-function ann(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): Annotation {
+function makeAnnotation(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): Annotation {
   return {
     id: "a1",
     kind: "comment",
@@ -25,7 +25,7 @@ function ann(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): A
 
 describe("renderFeedback", () => {
   test("plan edits section carries the one unified diff, directive framing first", () => {
-    const out = renderFeedback({
+    const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "Tighten the storage section.",
       artifactContent: PLAN,
@@ -33,83 +33,102 @@ describe("renderFeedback", () => {
       annotations: [],
       planPath: "docs/plan.md",
     });
-    expect(out).toContain("# Review: request changes");
-    expect(out).toContain("Tighten the storage section.");
-    expect(out).toContain("## Plan edits");
-    expect(out).toContain("Apply this exact diff first");
-    expect(out).toContain("--- a/docs/plan.md");
-    expect(out).toContain("-Sessions are written as one JSON document per session.");
-    expect(out).toContain("+Sessions are written as one JSON record per session.");
+    expect(feedback).toContain("# Review: request changes");
+    expect(feedback).toContain("Tighten the storage section.");
+    expect(feedback).toContain("## Plan edits");
+    expect(feedback).toContain("Apply this exact diff first");
+    expect(feedback).toContain("--- a/docs/plan.md");
+    expect(feedback).toContain("-Sessions are written as one JSON document per session.");
+    expect(feedback).toContain("+Sessions are written as one JSON record per session.");
   });
 
   test("annotations are located by quote and section", () => {
-    const out = renderFeedback({
+    const feedback = renderFeedback({
       verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
       annotations: [
-        ann({
+        makeAnnotation({
           anchor: { quote: "daemon memory", prefix: "live only in ", suffix: " today." },
         }),
       ],
     });
-    expect(out).toContain("## Annotations (1)");
-    expect(out).toContain("### 1. Comment (§ Context)");
-    expect(out).toContain("> daemon memory");
-    expect(out).toContain("Please clarify.");
+    expect(feedback).toContain("## Annotations (1)");
+    expect(feedback).toContain("### 1. Comment (§ Context)");
+    expect(feedback).toContain("> daemon memory");
+    expect(feedback).toContain("Please clarify.");
   });
 
   test("suggestions render as replace/with pairs", () => {
-    const out = renderFeedback({
+    const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
       artifactContent: PLAN,
       annotations: [
-        ann({
+        makeAnnotation({
           kind: "suggestion",
           body: "one durable JSON record",
           anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
         }),
       ],
     });
-    expect(out).toContain("### 1. Suggested change (§ Storage)");
-    expect(out).toContain("Replace:\n> one JSON document");
-    expect(out).toContain("With:\n> one durable JSON record");
+    expect(feedback).toContain("### 1. Suggested change (§ Storage)");
+    expect(feedback).toContain("Replace:\n> one JSON document");
+    expect(feedback).toContain("With:\n> one durable JSON record");
   });
 
   test("orphaned anchors are flagged, never dropped", () => {
-    const out = renderFeedback({
+    const feedback = renderFeedback({
       verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
-      annotations: [ann({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } })],
+      annotations: [makeAnnotation({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } })],
     });
-    expect(out).toContain("[orphaned anchor: the quoted text is no longer present]");
-    expect(out).toContain("> text that is gone");
+    expect(feedback).toContain("[orphaned anchor: the quoted text is no longer present]");
+    expect(feedback).toContain("> text that is gone");
   });
 
   test("empty review says so explicitly", () => {
-    const out = renderFeedback({
+    const feedback = renderFeedback({
       verdictKind: "approve",
       summary: "",
       artifactContent: PLAN,
       annotations: [],
     });
-    expect(out).toContain("_No edits or annotations._");
+    expect(feedback).toContain("_No edits or annotations._");
+  });
+
+  test("agent notes never come back as feedback items", () => {
+    const note = makeAnnotation({
+      kind: "note",
+      anchor: { quote: "src/a.ts", prefix: "", suffix: "" },
+      body: "The agent's own explanation of the change.",
+    });
+    const noteOnly = renderFeedback({ verdictKind: "approve", summary: "", artifactContent: PLAN, annotations: [note] });
+    expect(noteOnly).toContain("_No edits or annotations._");
+    expect(noteOnly).not.toContain("The agent's own explanation of the change.");
+    const mixed = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [note, makeAnnotation({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } })],
+    });
+    expect(mixed).toContain("## Annotations (1)");
+    expect(mixed).not.toContain("The agent's own explanation of the change.");
   });
 
   test("anchors resolve against the working copy when present", () => {
     // annotation made on text that only exists in the edited copy
     const working = PLAN.replace("## Storage", "## Persistence");
-    const out = renderFeedback({
+    const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
       artifactContent: PLAN,
       workingCopy: working,
       annotations: [
-        ann({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } }),
+        makeAnnotation({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } }),
       ],
     });
-    expect(out).toContain("(§ Persistence)");
+    expect(feedback).toContain("(§ Persistence)");
   });
 });

package/src/feedback.ts

@@ -1,11 +1,11 @@
 /**
  * feedback.md: the ONE structured markdown document the agent receives on
- * resolve (map #2, verified in the edit-mode deep-dive). Directive framing -
- * soft phrasing gets ignored by models: the plan diff is applied verbatim
- * first, then every annotation is addressed, located by quoted text.
+ * resolve. Directive framing - soft phrasing gets ignored by models: the plan
+ * diff is applied verbatim first, then every annotation is addressed, located
+ * by quoted text.
  */
 
-import type { Annotation, ReviewSession, VerdictKind } from "./types";
+import { isAgentNote, type Annotation, type ReviewSession, type VerdictKind } from "./types";
 import { parseBlocks, sectionOf } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
@@ -22,10 +22,12 @@ export interface FeedbackInput {
   planPath?: string;
 }
 
-const quoteLines = (s: string) => "> " + s.replace(/\n/g, "\n> ");
+const quoteLines = (text: string) => "> " + text.replace(/\n/g, "\n> ");
 
 export function renderFeedback(input: FeedbackInput): string {
   const path = input.planPath ?? "plan.md";
+  // agent notes are the submitter's own context - never echoed back as feedback
+  const annotations = input.annotations.filter((annotation) => !isAgentNote(annotation));
   const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
   const lines: string[] = [];
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
@@ -49,35 +51,35 @@ export function renderFeedback(input: FeedbackInput): string {
     lines.push("");
   }
 
-  if (input.annotations.length) {
-    lines.push(`## Annotations (${input.annotations.length})`);
+  if (annotations.length) {
+    lines.push(`## Annotations (${annotations.length})`);
     lines.push("");
     lines.push(`Address every item. Locate each one in ${path} by its quoted text.`);
     lines.push("");
-    input.annotations.forEach((a, i) => {
-      const res = resolveAnchor(a.anchor, blocks);
-      const sec = res ? sectionOf(blocks, res.blockIndex) : "";
-      const loc = sec ? ` (§ ${sec})` : "";
-      const flag = res === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
-      if (a.kind === "suggestion") {
-        lines.push(`### ${i + 1}. Suggested change${loc}${flag}`);
+    annotations.forEach((annotation, annotationIndex) => {
+      const resolved = resolveAnchor(annotation.anchor, blocks);
+      const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
+      const location = sectionTitle ? ` (§ ${sectionTitle})` : "";
+      const orphanFlag = resolved === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
+      if (annotation.kind === "suggestion") {
+        lines.push(`### ${annotationIndex + 1}. Suggested change${location}${orphanFlag}`);
         lines.push("");
         lines.push("Replace:");
-        lines.push(quoteLines(a.anchor.quote));
+        lines.push(quoteLines(annotation.anchor.quote));
         lines.push("With:");
-        lines.push(quoteLines(a.body));
+        lines.push(quoteLines(annotation.body));
       } else {
-        lines.push(`### ${i + 1}. ${capitalize(a.kind)}${loc}${flag}`);
+        lines.push(`### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`);
         lines.push("");
-        lines.push(quoteLines(a.anchor.quote));
+        lines.push(quoteLines(annotation.anchor.quote));
         lines.push("");
-        lines.push(a.body);
+        lines.push(annotation.body);
       }
       lines.push("");
     });
   }
 
-  if (!diff && !input.annotations.length) {
+  if (!diff && !annotations.length) {
     lines.push("_No edits or annotations._");
     lines.push("");
   }
@@ -95,6 +97,6 @@ export function feedbackForSession(session: ReviewSession, verdictKind: VerdictK
   });
 }
 
-function capitalize(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
 }

package/src/markdown.test.ts

@@ -30,7 +30,7 @@ const y = 2;
 describe("parseBlocks", () => {
   test("parses every block kind with source line ranges", () => {
     const blocks = parseBlocks(SAMPLE);
-    expect(blocks.map((b) => b.kind)).toEqual([
+    expect(blocks.map((block) => block.kind)).toEqual([
       "h1",
       "h2",
       "p",
@@ -43,7 +43,7 @@ describe("parseBlocks", () => {
       "quote",
       "hr",
     ]);
-    const code = blocks.find((b) => b.kind === "code")!;
+    const code = blocks.find((block) => block.kind === "code")!;
     expect(code.lang).toBe("ts");
     expect(code.text).toBe("const x = 1;\nconst y = 2;");
     // fence lines included in the source range
@@ -52,49 +52,49 @@ describe("parseBlocks", () => {
 
   test("multi-line paragraph keeps its text and range", () => {
     const blocks = parseBlocks(SAMPLE);
-    const p = blocks.find((b) => b.kind === "p")!;
-    expect(p.text).toBe("A paragraph that\nspans two lines.");
-    expect(p.lineEnd - p.lineStart).toBe(1);
+    const paragraph = blocks.find((block) => block.kind === "p")!;
+    expect(paragraph.text).toBe("A paragraph that\nspans two lines.");
+    expect(paragraph.lineEnd - paragraph.lineStart).toBe(1);
   });
 
   test("line ranges index into the source", () => {
     const lines = SAMPLE.split("\n");
-    for (const b of parseBlocks(SAMPLE)) {
-      if (b.kind === "code") {
-        expect(lines[b.lineStart]!.startsWith("```")).toBe(true);
-      } else if (b.kind === "h2") {
-        expect(lines[b.lineStart]!.startsWith("## ")).toBe(true);
+    for (const block of parseBlocks(SAMPLE)) {
+      if (block.kind === "code") {
+        expect(lines[block.lineStart]!.startsWith("```")).toBe(true);
+      } else if (block.kind === "h2") {
+        expect(lines[block.lineStart]!.startsWith("## ")).toBe(true);
       }
     }
   });
 
   test("round-trips through blockToMd", () => {
     const blocks = parseBlocks(SAMPLE);
-    let oli = 0;
+    let orderedItemCount = 0;
     const rebuilt = blocks
-      .map((b) => {
-        oli = b.kind === "oli" ? oli + 1 : 0;
-        return blockToMd(b, oli || 1);
+      .map((block) => {
+        orderedItemCount = block.kind === "oli" ? orderedItemCount + 1 : 0;
+        return blockToMd(block, orderedItemCount || 1);
       })
       .join("\n\n");
     // re-parsing the rebuild yields the same kinds and texts
     const again = parseBlocks(rebuilt);
-    expect(again.map((b) => [b.kind, b.text])).toEqual(blocks.map((b) => [b.kind, b.text]));
+    expect(again.map((block) => [block.kind, block.text])).toEqual(blocks.map((block) => [block.kind, block.text]));
   });
 
   test("unknown constructs degrade to paragraphs, no content lost", () => {
     const md = "| a | b |\n|---|---|\n| 1 | 2 |";
     const blocks = parseBlocks(md);
-    expect(blocks.map((b) => b.text).join("\n")).toContain("| a | b |");
+    expect(blocks.map((block) => block.text).join("\n")).toContain("| a | b |");
   });
 });
 
 describe("sectionOf", () => {
   test("returns the nearest preceding heading", () => {
     const blocks = parseBlocks(SAMPLE);
-    const oliIdx = blocks.findIndex((b) => b.kind === "oli");
-    expect(sectionOf(blocks, oliIdx)).toBe("Steps");
-    const pIdx = blocks.findIndex((b) => b.kind === "p");
-    expect(sectionOf(blocks, pIdx)).toBe("Context");
+    const orderedItemIndex = blocks.findIndex((block) => block.kind === "oli");
+    expect(sectionOf(blocks, orderedItemIndex)).toBe("Steps");
+    const paragraphIndex = blocks.findIndex((block) => block.kind === "p");
+    expect(sectionOf(blocks, paragraphIndex)).toBe("Context");
   });
 });

package/src/markdown.ts

@@ -1,6 +1,6 @@
 /**
- * Markdown block model (map #22): parse source into addressable blocks that
- * record their source line ranges. Rendered→source mapping is block+line
+ * Markdown block model: parse source into addressable blocks that record
+ * their source line ranges. Rendered-to-source mapping is block+line
  * granular; the quote carries sub-block precision. Round-trip safe for the
  * subset cueloop plans use; unknown constructs fall back to paragraph blocks
  * so no content is ever lost.
@@ -19,113 +19,113 @@ export interface Block {
   lineEnd: number;
 }
 
-function isMarkerLine(l: string): boolean {
+function isMarkerLine(line: string): boolean {
   return (
-    l.startsWith("```") ||
-    l.startsWith("# ") ||
-    l.startsWith("## ") ||
-    l.startsWith("### ") ||
-    l.startsWith("> ") ||
-    /^- /.test(l) ||
-    /^\d+\. /.test(l) ||
-    /^(---|\*\*\*|___)\s*$/.test(l)
+    line.startsWith("```") ||
+    line.startsWith("# ") ||
+    line.startsWith("## ") ||
+    line.startsWith("### ") ||
+    line.startsWith("> ") ||
+    /^- /.test(line) ||
+    /^\d+\. /.test(line) ||
+    /^(---|\*\*\*|___)\s*$/.test(line)
   );
 }
 
-export function parseBlocks(md: string): Block[] {
-  const lines = md.split("\n");
+export function parseBlocks(markdown: string): Block[] {
+  const lines = markdown.split("\n");
   const blocks: Block[] = [];
-  let i = 0;
-  while (i < lines.length) {
-    const l = lines[i]!;
-    if (l.trim() === "") {
-      i++;
+  let lineIndex = 0;
+  while (lineIndex < lines.length) {
+    const line = lines[lineIndex]!;
+    if (line.trim() === "") {
+      lineIndex++;
       continue;
     }
-    if (l.startsWith("```")) {
-      const start = i;
-      const lang = l.slice(3).trim() || undefined;
-      i++;
+    if (line.startsWith("```")) {
+      const start = lineIndex;
+      const lang = line.slice(3).trim() || undefined;
+      lineIndex++;
       const body: string[] = [];
-      while (i < lines.length && !lines[i]!.startsWith("```")) {
-        body.push(lines[i]!);
-        i++;
+      while (lineIndex < lines.length && !lines[lineIndex]!.startsWith("```")) {
+        body.push(lines[lineIndex]!);
+        lineIndex++;
       }
-      const end = Math.min(i, lines.length - 1);
-      i++;
+      const end = Math.min(lineIndex, lines.length - 1);
+      lineIndex++;
       blocks.push({ kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end });
-    } else if (l.startsWith("### ")) {
-      blocks.push({ kind: "h3", text: l.slice(4), lineStart: i, lineEnd: i });
-      i++;
-    } else if (l.startsWith("## ")) {
-      blocks.push({ kind: "h2", text: l.slice(3), lineStart: i, lineEnd: i });
-      i++;
-    } else if (l.startsWith("# ")) {
-      blocks.push({ kind: "h1", text: l.slice(2), lineStart: i, lineEnd: i });
-      i++;
-    } else if (/^(---|\*\*\*|___)\s*$/.test(l)) {
-      blocks.push({ kind: "hr", text: "", lineStart: i, lineEnd: i });
-      i++;
-    } else if (l.startsWith("> ")) {
-      const start = i;
+    } else if (line.startsWith("### ")) {
+      blocks.push({ kind: "h3", text: line.slice(4), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("## ")) {
+      blocks.push({ kind: "h2", text: line.slice(3), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("# ")) {
+      blocks.push({ kind: "h1", text: line.slice(2), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (/^(---|\*\*\*|___)\s*$/.test(line)) {
+      blocks.push({ kind: "hr", text: "", lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("> ")) {
+      const start = lineIndex;
       const body: string[] = [];
-      while (i < lines.length && lines[i]!.startsWith("> ")) {
-        body.push(lines[i]!.slice(2));
-        i++;
+      while (lineIndex < lines.length && lines[lineIndex]!.startsWith("> ")) {
+        body.push(lines[lineIndex]!.slice(2));
+        lineIndex++;
       }
-      blocks.push({ kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: i - 1 });
-    } else if (/^- /.test(l)) {
-      blocks.push({ kind: "li", text: l.slice(2), lineStart: i, lineEnd: i });
-      i++;
-    } else if (/^\d+\. /.test(l)) {
-      blocks.push({ kind: "oli", text: l.replace(/^\d+\. /, ""), lineStart: i, lineEnd: i });
-      i++;
+      blocks.push({ kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
+    } else if (/^- /.test(line)) {
+      blocks.push({ kind: "li", text: line.slice(2), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (/^\d+\. /.test(line)) {
+      blocks.push({ kind: "oli", text: line.replace(/^\d+\. /, ""), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
     } else {
-      const start = i;
+      const start = lineIndex;
       const body: string[] = [];
-      while (i < lines.length && lines[i]!.trim() !== "" && !isMarkerLine(lines[i]!)) {
-        body.push(lines[i]!);
-        i++;
+      while (lineIndex < lines.length && lines[lineIndex]!.trim() !== "" && !isMarkerLine(lines[lineIndex]!)) {
+        body.push(lines[lineIndex]!);
+        lineIndex++;
       }
-      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: i - 1 });
+      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
     }
   }
   return blocks;
 }
 
 /** Serialize one block back to its markdown chunk. */
-export function blockToMd(b: Block, ordinal = 1): string {
-  switch (b.kind) {
+export function blockToMd(block: Block, ordinal = 1): string {
+  switch (block.kind) {
     case "h1":
-      return "# " + b.text;
+      return "# " + block.text;
     case "h2":
-      return "## " + b.text;
+      return "## " + block.text;
     case "h3":
-      return "### " + b.text;
+      return "### " + block.text;
     case "li":
-      return "- " + b.text;
+      return "- " + block.text;
     case "oli":
-      return `${ordinal}. ` + b.text;
+      return `${ordinal}. ` + block.text;
     case "quote":
-      return b.text
+      return block.text
         .split("\n")
-        .map((l) => "> " + l)
+        .map((line) => "> " + line)
         .join("\n");
     case "code":
-      return "```" + (b.lang ?? "") + "\n" + b.text + "\n```";
+      return "```" + (block.lang ?? "") + "\n" + block.text + "\n```";
     case "hr":
       return "---";
     default:
-      return b.text;
+      return block.text;
   }
 }
 
 /** The section (nearest preceding heading) a block belongs to. */
 export function sectionOf(blocks: Block[], index: number): string {
-  let sec = "";
-  for (let i = 0; i <= index && i < blocks.length; i++) {
-    const b = blocks[i]!;
-    if (b.kind === "h1" || b.kind === "h2" || b.kind === "h3") sec = b.text;
+  let sectionTitle = "";
+  for (let blockIndex = 0; blockIndex <= index && blockIndex < blocks.length; blockIndex++) {
+    const block = blocks[blockIndex]!;
+    if (block.kind === "h1" || block.kind === "h2" || block.kind === "h3") sectionTitle = block.text;
   }
-  return sec;
+  return sectionTitle;
 }

package/src/types.ts

@@ -1,7 +1,7 @@
 /**
- * The ReviewSession primitive (map #2, #9). Everything in cueloop renders,
- * annotates, or resolves this one noun. This module is pure data shapes -
- * no IO, no dependencies.
+ * The ReviewSession primitive. Everything in cueloop renders, annotates, or
+ * resolves this one noun. This module is pure data shapes - no IO, no
+ * dependencies.
  */
 
 export const SCHEMA_VERSION = "1";
@@ -51,9 +51,19 @@ export interface Anchor {
   end?: number;
 }
 
-/** The annotation kind set is open (map #2); these are the built-ins. */
+/** The annotation kind set is open; these are the built-ins. */
 export type AnnotationKind = "comment" | "suggestion" | (string & {});
 
+/**
+ * Agent-authored context, not reviewer feedback: the guided walk's per-file
+ * notes (kind "note", anchored by the file path). Excluded from the feedback
+ * document and the reviewer's pending counts - an agent must never receive
+ * its own notes back as items to address.
+ */
+export function isAgentNote(annotation: Pick<Annotation, "kind">): boolean {
+  return annotation.kind === "note";
+}
+
 export interface Annotation {
   id: string;
   kind: AnnotationKind;
@@ -97,6 +107,12 @@ export interface ReviewSession {
    * Undefined = no direct edits.
    */
   workingCopy?: string;
+  /**
+   * File paths the reviewer marked viewed during the guided walk (diff
+   * sessions). Persisting with the session means a resumed review keeps its
+   * progress. Undefined = the walk never started.
+   */
+  viewedPaths?: string[];
   verdict: Verdict | null;
   status: SessionStatus;
   createdAt: string;

package/src/working-copy.test.ts

@@ -18,8 +18,8 @@ const y = 2;
 \`\`\`
 `;
 
-function block(md: string, text: string): Block {
-  return parseBlocks(md).find((b) => b.text.includes(text))!;
+function block(markdown: string, text: string): Block {
+  return parseBlocks(markdown).find((block) => block.text.includes(text))!;
 }
 
 describe("sourceChunk", () => {
@@ -55,19 +55,19 @@ describe("cutBlock", () => {
 
 describe("restoreBlock", () => {
   test("restoring the only cut returns undefined - back to pristine", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
     // the cut block re-enters before the code fence, the next surviving block
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, cut, li, restoreLine(next, cut.split("\n").length));
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
+    const restored = restoreBlock(BASE, cut, listItem, restoreLine(next, cut.split("\n").length));
     expect(restored).toBeUndefined();
   });
 
   test("restore after another edit returns the merged working copy", () => {
-    const li = block(BASE, "second item");
-    const edited = cutBlock(BASE, li).replace("first item", "first item reworded");
-    const next = parseBlocks(edited).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, edited, li, restoreLine(next, edited.split("\n").length));
+    const listItem = block(BASE, "second item");
+    const edited = cutBlock(BASE, listItem).replace("first item", "first item reworded");
+    const next = parseBlocks(edited).find((candidate) => candidate.kind === "code");
+    const restored = restoreBlock(BASE, edited, listItem, restoreLine(next, edited.split("\n").length));
     expect(restored).toContain("- second item");
     expect(restored).toContain("first item reworded");
   });
@@ -80,30 +80,30 @@ describe("restoreBlock", () => {
   });
 
   test("restore a multi-line block round-trips to pristine", () => {
-    const p = block(BASE, "spans two lines");
-    const cut = cutBlock(BASE, p);
-    const next = parseBlocks(cut).find((b) => b.text === "first item");
-    const restored = restoreBlock(BASE, cut, p, restoreLine(next, cut.split("\n").length));
+    const paragraph = block(BASE, "spans two lines");
+    const cut = cutBlock(BASE, paragraph);
+    const next = parseBlocks(cut).find((block) => block.text === "first item");
+    const restored = restoreBlock(BASE, cut, paragraph, restoreLine(next, cut.split("\n").length));
     expect(restored).toBeUndefined();
   });
 
   test("signature rule ignores blank-line layout but not text changes", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
     const line = restoreLine(next, cut.split("\n").length);
     // extra blank lines elsewhere do not block pristine detection
-    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), li, line)).toBeUndefined();
+    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line)).toBeUndefined();
     // a real text change keeps the working copy alive
-    const changed = restoreBlock(BASE, cut.replace("first", "1st"), li, line);
+    const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
     expect(changed).toContain("1st item");
   });
 });
 
 describe("restoreLine", () => {
   test("next surviving block's start, or the line count at the end", () => {
-    const li = block(BASE, "first item");
-    expect(restoreLine(li, 99)).toBe(li.lineStart);
+    const listItem = block(BASE, "first item");
+    expect(restoreLine(listItem, 99)).toBe(listItem.lineStart);
     expect(restoreLine(undefined, 99)).toBe(99);
   });
 });

package/src/working-copy.ts

@@ -34,7 +34,7 @@ export function restoreLine(next: Block | undefined, workingLineCount: number):
  */
 function signature(text: string): string {
   return parseBlocks(text)
-    .map((b) => b.kind + " " + b.text)
+    .map((block) => block.kind + " " + block.text)
     .join("\0");
 }
 
@@ -53,9 +53,9 @@ export function restoreBlock(
   const lines = working.split("\n");
   const before = lines.slice(0, beforeLine);
   const after = lines.slice(beforeLine);
-  const ins = sourceChunk(base, block).split("\n");
-  if (before.length && before[before.length - 1]!.trim() !== "") ins.unshift("");
-  if (after.length && after[0]!.trim() !== "") ins.push("");
-  const restored = [...before, ...ins, ...after].join("\n");
+  const insertedLines = sourceChunk(base, block).split("\n");
+  if (before.length && before[before.length - 1]!.trim() !== "") insertedLines.unshift("");
+  if (after.length && after[0]!.trim() !== "") insertedLines.push("");
+  const restored = [...before, ...insertedLines, ...after].join("\n");
   return signature(restored) === signature(base) ? undefined : restored;
 }