@cueloop/schema 0.1.0-alpha.9 → 0.1.0-alpha.90

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0-alpha.90",
+  "description": "The Thread primitive: types, markdown block model, quote-primary anchors, feedback serialization",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/schema"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -9,21 +23,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
   "engines": {
     "bun": ">=1.3.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/schema"
-  },
-  "homepage": "https://github.com/mmurakaru/cueloop#readme",
-  "bugs": {
-    "url": "https://github.com/mmurakaru/cueloop/issues"
-  },
-  "description": "The ReviewSession primitive: types, markdown block model, quote-primary anchors, feedback serialization"
-}
+  }
+}

package/src/anchor.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { parseBlocks } from "./markdown";
-import { makeAnchor, resolveAnchor } from "./anchor";
+import { BLOCK_SEPARATOR, makeAnchor, resolveAnchor } from "./anchor";
 
 const DOC = `# Plan
 
@@ -15,80 +15,380 @@ 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", () => {
+    // Arrange
     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"));
+
+    // Act
+    const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15); // "Review sessions"
+
+    // Assert
+    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", () => {
+    // Arrange
     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"
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    expect(resolved.blockIndex).toBe(contextBlockIndex);
+    expect(resolved.start).toBe(7);
+    expect(resolved.approximate).toBe(false);
   });
 
   test("survives text changes before the quote (quote search)", () => {
+    // Arrange
     const blocks = blocksOf(DOC);
-    const ctxIdx = blocks.findIndex((b) => b.text.startsWith("Review sessions"));
-    const a = makeAnchor(blocks, ctxIdx, 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 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"),
+    );
+
+    // Act
+    const resolved = resolveAnchor(anchor, edited)!;
+
+    // Assert
+    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", () => {
+    // Arrange
     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,
+    );
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    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);
+    // Arrange
+    const repeatedWords = "word word word";
+    const blocks = blocksOf(repeatedWords);
+    const anchor = makeAnchor(blocks, 0, 5, 9); // middle "word"
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    expect(resolved.start).toBe(5);
+  });
+
+  test("binds a quote that still carries its leading list marker", () => {
+    // Arrange
+    // an agent copied the source line verbatim, including the "- " bullet, but
+    // the parsed list block strips the marker from its text
+    const blocks = blocksOf("## Notes\n\n- This is a dummy plan - confirm the item");
+    const anchor = { quote: "- This is a dummy plan", prefix: "", suffix: "" };
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    expect(resolved).not.toBeNull();
+    expect(resolved.strategy).toBe("normalized");
+    expect(blocks[resolved.blockIndex]!.text.slice(resolved.start, resolved.end)).toBe(
+      "This is a dummy plan",
+    );
+  });
+
+  test("binds a heading quote that still carries its leading hashes", () => {
+    // Arrange
+    const blocks = blocksOf(DOC);
+    const anchor = { quote: "## Storage", prefix: "", suffix: "" };
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    expect(resolved.strategy).toBe("normalized");
+    expect(blocks[resolved.blockIndex]!.text).toBe("Storage");
+  });
+
+  test("fuzzy tier binds a lightly edited quote", () => {
+    // Arrange
+    const blocks = blocksOf(DOC);
+    const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
+    // a typo the reviewer never saw: "sesssions"
+    const anchor = {
+      quote: "Review sesssions currently live",
+      prefix: "",
+      suffix: "",
+    };
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    expect(resolved.strategy).toBe("fuzzy");
+    expect(resolved.blockIndex).toBe(contextBlockIndex);
+    expect(resolved.approximate).toBe(true);
+  });
+
+  test("exact matches report the exact strategy", () => {
+    // Arrange
+    const blocks = blocksOf(DOC);
+    const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
+    const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15);
+
+    // Act
+    const resolved = resolveAnchor(anchor, blocks)!;
+
+    // Assert
+    expect(resolved.strategy).toBe("exact");
+    expect(resolved.approximate).toBe(false);
   });
 
   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 };
+    // Arrange
+    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);
+
+    // Act
+    const resolved = resolveAnchor(anchor, edited);
+
+    // Assert
+    expect(resolved).not.toBeNull();
+    expect(resolved!.approximate).toBe(true);
   });
 
   test("orphans when the quote is gone entirely", () => {
+    // Arrange
     const blocks = blocksOf(DOC);
-    const ctxIdx = blocks.findIndex((b) => b.text.startsWith("Review sessions"));
-    const a = makeAnchor(blocks, ctxIdx, 0, 15);
-    const edited = blocksOf(DOC.replace(/Review sessions[^\n]*\n[^\n]*/, "Completely different text."));
-    expect(resolveAnchor(a, edited)).toBeNull();
+    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."),
+    );
+
+    // Assert
+    expect(resolveAnchor(anchor, edited)).toBeNull();
   });
 
   test("empty quote never binds", () => {
+    // Arrange
     const blocks = blocksOf(DOC);
+
+    // Assert
     expect(resolveAnchor({ quote: "", prefix: "", suffix: "" }, blocks)).toBeNull();
   });
 });
+
+describe("anchors spanning blocks", () => {
+  const SPANNING_DOC = `## Phase 1
+
+All persistence lives in a new module,
+so a crash can never leave a torn file on disk.
+
+- server/storage/store.ts - the ThreadStore class
+- server/storage/schema.ts - the on-disk record shape
+
+## Phase 2
+`;
+  const blocks = parseBlocks(SPANNING_DOC);
+  const paragraph = blocks.findIndex((block) => block.text.startsWith("All persistence"));
+  const secondBullet = blocks.findIndex((block) => block.text.startsWith("server/storage/schema"));
+  const start = blocks[paragraph]!.text.indexOf("so a crash");
+  const end = "server/storage/schema.ts".length;
+  const anchor = makeAnchor(blocks, paragraph, start, end, secondBullet);
+
+  test("the quote is the spanned text joined by a blank line, with an end block hint", () => {
+    // Assert
+    expect(anchor.quote).toBe(
+      [
+        "so a crash can never leave a torn file on disk.",
+        "server/storage/store.ts - the ThreadStore class",
+        "server/storage/schema.ts",
+      ].join(BLOCK_SEPARATOR),
+    );
+    expect(anchor.blockIndex).toBe(paragraph);
+    expect(anchor.endBlockIndex).toBe(secondBullet);
+    expect(anchor.suffix).toBe(" - the on-disk record sh");
+  });
+
+  test("a single-block anchor carries no end block hint", () => {
+    // Assert
+    expect(makeAnchor(blocks, paragraph, 0, 3)).not.toHaveProperty("endBlockIndex");
+  });
+
+  test("resolves exactly back onto the first and last block offsets", () => {
+    // Act
+    const resolved = resolveAnchor(anchor, blocks);
+
+    // Assert
+    expect(resolved).toEqual({
+      blockIndex: paragraph,
+      start,
+      endBlockIndex: secondBullet,
+      end,
+      approximate: false,
+      strategy: "exact",
+    });
+  });
+
+  test("follows the span when blocks are inserted above it", () => {
+    // Arrange: a new paragraph shifts every block index by one
+    const shifted = parseBlocks(
+      SPANNING_DOC.replace("## Phase 1\n", "## Phase 1\n\nA new intro.\n"),
+    );
+
+    // Act
+    const resolved = resolveAnchor(anchor, shifted);
+
+    // Assert
+    expect(resolved?.blockIndex).toBe(paragraph + 1);
+    expect(resolved?.endBlockIndex).toBe(secondBullet + 1);
+    expect(resolved?.start).toBe(start);
+    expect(resolved?.end).toBe(end);
+  });
+
+  test("re-binds fuzzily after a light edit inside the span", () => {
+    // Arrange
+    const edited = parseBlocks(SPANNING_DOC.replace("ThreadStore class", "ThreadStore type"));
+
+    // Act
+    const resolved = resolveAnchor(anchor, edited);
+
+    // Assert: still one span from the paragraph to the second bullet
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(resolved?.approximate).toBe(true);
+    expect(resolved?.blockIndex).toBe(paragraph);
+    expect(resolved?.endBlockIndex).toBe(secondBullet);
+  });
+
+  test("orphans when the spanned passage is gone", () => {
+    // Arrange
+    const gutted = parseBlocks("## Phase 1\n\nSomething else entirely.\n");
+
+    // Assert
+    expect(resolveAnchor(anchor, gutted)).toBeNull();
+  });
+
+  test("a match landing on a separator edge is pulled onto the neighbouring block", () => {
+    // Arrange: a quote whose exact text starts with the separator only exists
+    // when its first block portion is empty, which makeAnchor never produces;
+    // simulate the stale case directly
+    const staleAnchor = {
+      ...anchor,
+      quote: `${BLOCK_SEPARATOR}server/storage/store.ts - the ThreadStore class`,
+    };
+
+    // Act
+    const resolved = resolveAnchor(staleAnchor, blocks);
+
+    // Assert: the span opens at the bullet, not on the blank line above it
+    expect(resolved?.blockIndex).toBe(secondBullet - 1);
+    expect(resolved?.start).toBe(0);
+    expect(resolved?.endBlockIndex).toBe(secondBullet - 1);
+  });
+});
+
+describe("fuzzy work budget", () => {
+  function largePlan(paragraphs: number): string {
+    const lines = ["# Plan", ""];
+
+    for (let index = 0; index < paragraphs; index++) {
+      lines.push(
+        `This is paragraph number ${index} describing the migration of the session store and its atomic write path in enough prose to be a realistic block a reviewer might quote.`,
+        "",
+      );
+    }
+
+    return lines.join("\n");
+  }
+
+  test("a stale anchor over a large plan stays bounded across all its blocks", () => {
+    // Arrange - a 160-block plan whose quoted paragraph was edited so the exact text is gone,
+    // forcing the fuzzy tier over every block; a per-block budget would freeze for many seconds
+    const blocks = parseBlocks(largePlan(160));
+    const quoted = Math.floor(blocks.length / 2);
+    const anchor = makeAnchor(blocks, quoted, 0, Math.min(blocks[quoted]!.text.length, 140));
+    const edited = blocks.map((block) => ({
+      ...block,
+      text: block.text.replaceAll("migration", "rollout").replaceAll("session", "record"),
+    }));
+
+    // Act
+    const started = Date.now();
+    const resolved = resolveAnchor(anchor, edited);
+    const elapsed = Date.now() - started;
+
+    // Assert - it rebinds via the fuzzy tier, and one shared budget keeps it far under a freeze
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  test("still binds when a distinctive quote moved down a few blocks and was edited", () => {
+    // Arrange - a distinctive quote among unrelated blocks; the agent inserts paragraphs above it
+    // (shifting it down) and edits one word, so exact/normalized miss and the outward scan must
+    // reach the shifted block before the shared budget runs out
+    const original =
+      "The canonical migration store commits every session write atomically along one path.";
+    const plan = (target: string): string => {
+      const lines = ["# Plan", ""];
+
+      for (let index = 0; index < 40; index++) {
+        lines.push(
+          index === 20
+            ? target
+            : `Filler paragraph ${index} covers an unrelated topic in its own words.`,
+          "",
+        );
+      }
+
+      return lines.join("\n");
+    };
+    const before = parseBlocks(plan(original));
+    const quoted = before.findIndex((block) => block.text === original);
+    const anchor = makeAnchor(before, quoted, 0, original.length);
+    const edited = original.replace("atomically", "carefully");
+    const shifted = parseBlocks(
+      plan(edited).replace("# Plan\n", "# Plan\n\nInserted A.\n\nInserted B.\n\nInserted C.\n"),
+    );
+
+    // Act
+    const resolved = resolveAnchor(anchor, shifted);
+
+    // Assert - rebinds via fuzzy onto the shifted block, not orphaned or bound to a neighbour
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(shifted[resolved!.blockIndex]!.text).toBe(edited);
+  });
+});