@cueloop/schema 0.1.0-alpha.63 → 0.1.0-alpha.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.63",
+  "version": "0.1.0-alpha.65",
   "description": "The ReviewSession primitive: types, markdown block model, quote-primary anchors, feedback serialization",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {

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
 
@@ -140,7 +140,11 @@ describe("anchor cascade", () => {
     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: "" };
+    const anchor = {
+      quote: "Review sesssions currently live",
+      prefix: "",
+      suffix: "",
+    };
 
     // Act
     const resolved = resolveAnchor(anchor, blocks)!;
@@ -207,3 +211,112 @@ describe("anchor cascade", () => {
     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 SessionStore 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 SessionStore 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("SessionStore class", "SessionStore 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 SessionStore 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);
+  });
+});

package/src/anchor.ts

@@ -10,6 +10,10 @@
  *   5. orphan     - none matched; keep the quote for display, drop the highlight
  * Prefix/suffix selectors and the recorded position break ties within a tier.
  * Never silently bind to the wrong text: fuzzy needs a high similarity floor.
+ *
+ * A quote may span consecutive blocks: its text is the blocks' text joined by
+ * BLOCK_SEPARATOR, and it resolves against the document joined the same way,
+ * so one comment can cover the tail of a paragraph and the bullets under it.
  */
 
 import type { Anchor } from "./types";
@@ -22,12 +26,18 @@ const ANCHOR_CONTEXT_CHARS = 24;
 /** Minimum similarity a fuzzy match needs before the resolver will trust it. */
 const FUZZY_MINIMUM_SIMILARITY = 0.75;
 
+/** Joins block texts in a spanning quote and in the document it resolves against. */
+export const BLOCK_SEPARATOR = "\n\n";
+
 /** How the quote bound to the block text, weakest binding named last. */
 export type AnchorMatchStrategy = "exact" | "trimmed" | "normalized" | "fuzzy";
 
 export interface ResolvedAnchor {
   blockIndex: number;
   start: number;
+  /** Last block of the quote; equals blockIndex unless the quote spans blocks. */
+  endBlockIndex: number;
+  /** Offset within the end block. */
   end: number;
   /** True whenever the binding was not an exact quote match. */
   approximate: boolean;
@@ -40,17 +50,32 @@ export function makeAnchor(
   blockIndex: number,
   start: number,
   end: number,
+  endBlockIndex: number = blockIndex,
 ): Anchor {
-  const blockText = blocks[blockIndex]?.text ?? "";
-
-  return {
-    quote: blockText.slice(start, end),
-    prefix: blockText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start),
-    suffix: blockText.slice(end, end + ANCHOR_CONTEXT_CHARS),
+  const startText = blocks[blockIndex]?.text ?? "";
+  const endText = blocks[endBlockIndex]?.text ?? "";
+  const quote = blocks
+    .slice(blockIndex, endBlockIndex + 1)
+    .map((block, offset, spanned) => {
+      const isFirst = offset === 0;
+      const isLast = offset === spanned.length - 1;
+
+      return block.text.slice(isFirst ? start : 0, isLast ? end : block.text.length);
+    })
+    .join(BLOCK_SEPARATOR);
+
+  const anchor: Anchor = {
+    quote,
+    prefix: startText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start),
+    suffix: endText.slice(end, end + ANCHOR_CONTEXT_CHARS),
     blockIndex,
     start,
     end,
   };
+
+  if (endBlockIndex !== blockIndex) anchor.endBlockIndex = endBlockIndex;
+
+  return anchor;
 }
 
 interface Candidate {
@@ -149,15 +174,183 @@ function resolved(candidate: Candidate, strategy: AnchorMatchStrategy): Resolved
   return {
     blockIndex: candidate.blockIndex,
     start: candidate.start,
+    endBlockIndex: candidate.blockIndex,
     end: candidate.end,
     approximate: strategy !== "exact",
     strategy,
   };
 }
 
+/* ------------------------------------------------ quotes spanning blocks */
+
+/** The blocks as one document, with where each block's text starts in it. */
+interface JoinedDocument {
+  text: string;
+  starts: number[];
+}
+
+function joinBlocks(blocks: Block[]): JoinedDocument {
+  const starts: number[] = [];
+  let text = "";
+
+  blocks.forEach((block, blockIndex) => {
+    if (blockIndex > 0) text += BLOCK_SEPARATOR;
+    starts.push(text.length);
+    text += block.text;
+  });
+
+  return { text, starts };
+}
+
+/**
+ * The block and in-block offset of a document offset. An offset inside a
+ * separator belongs to the block after it when it opens a range and to the
+ * block before it when it closes one, so a span never starts or ends on the
+ * blank line between blocks.
+ */
+interface BlockOffset {
+  blockIndex: number;
+  offset: number;
+}
+
+function locateInBlocks(
+  blocks: Block[],
+  starts: number[],
+  offset: number,
+  edge: "start" | "end",
+): BlockOffset {
+  let blockIndex = starts.findLastIndex((start) => start <= offset);
+
+  if (blockIndex < 0) blockIndex = 0;
+  const blockEnd = starts[blockIndex]! + blocks[blockIndex]!.text.length;
+
+  if (edge === "start" && offset >= blockEnd && blockIndex < blocks.length - 1) {
+    return { blockIndex: blockIndex + 1, offset: 0 };
+  }
+  if (edge === "end" && offset === starts[blockIndex] && blockIndex > 0) {
+    return {
+      blockIndex: blockIndex - 1,
+      offset: blocks[blockIndex - 1]!.text.length,
+    };
+  }
+
+  return {
+    blockIndex,
+    offset: Math.min(offset, blockEnd) - starts[blockIndex]!,
+  };
+}
+
+/** Context agreement plus position hints for a window of the joined document. */
+function documentScore(
+  anchor: Anchor,
+  documentText: string,
+  start: number,
+  end: number,
+  startBlockIndex: number,
+): number {
+  const prefix = documentText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start);
+  const suffix = documentText.slice(end, end + ANCHOR_CONTEXT_CHARS);
+  let score = 0;
+
+  if (prefix === anchor.prefix) score += 2;
+  if (suffix === anchor.suffix) score += 2;
+  if (anchor.blockIndex === startBlockIndex) score += 1;
+
+  return score;
+}
+
+interface DocumentCandidate {
+  start: number;
+  end: number;
+  score: number;
+}
+
+function findSpanningExact(
+  anchor: Anchor,
+  documentText: string,
+  quote: string,
+  starts: number[],
+  blocks: Block[],
+): DocumentCandidate[] {
+  const candidates: DocumentCandidate[] = [];
+
+  for (
+    let matchStart = documentText.indexOf(quote);
+    matchStart !== -1;
+    matchStart = documentText.indexOf(quote, matchStart + 1)
+  ) {
+    const matchEnd = matchStart + quote.length;
+    const startBlockIndex = locateInBlocks(blocks, starts, matchStart, "start").blockIndex;
+
+    candidates.push({
+      start: matchStart,
+      end: matchEnd,
+      score: documentScore(anchor, documentText, matchStart, matchEnd, startBlockIndex),
+    });
+  }
+
+  return candidates;
+}
+
+function resolvedSpan(
+  blocks: Block[],
+  starts: number[],
+  candidate: DocumentCandidate,
+  strategy: AnchorMatchStrategy,
+): ResolvedAnchor {
+  const startPosition = locateInBlocks(blocks, starts, candidate.start, "start");
+  const endPosition = locateInBlocks(blocks, starts, candidate.end, "end");
+
+  return {
+    blockIndex: startPosition.blockIndex,
+    start: startPosition.offset,
+    endBlockIndex: endPosition.blockIndex,
+    end: endPosition.offset,
+    approximate: strategy !== "exact",
+    strategy,
+  };
+}
+
+/** The cascade for a quote that spans blocks, run over the joined document. */
+function resolveSpanningAnchor(anchor: Anchor, blocks: Block[]): ResolvedAnchor | null {
+  const document = joinBlocks(blocks);
+  const best = (candidates: DocumentCandidate[]): DocumentCandidate | null =>
+    candidates.toSorted((left, right) => right.score - left.score)[0] ?? null;
+
+  const exact = best(
+    findSpanningExact(anchor, document.text, anchor.quote, document.starts, blocks),
+  );
+
+  if (exact) return resolvedSpan(blocks, document.starts, exact, "exact");
+
+  const trimmedQuote = anchor.quote.trim();
+
+  if (trimmedQuote !== anchor.quote) {
+    const trimmed = best(
+      findSpanningExact(anchor, document.text, trimmedQuote, document.starts, blocks),
+    );
+
+    if (trimmed) return resolvedSpan(blocks, document.starts, trimmed, "trimmed");
+  }
+
+  const fuzzy = fuzzyFindBestMatch(trimmedQuote, document.text, FUZZY_MINIMUM_SIMILARITY);
+
+  if (fuzzy) {
+    return resolvedSpan(
+      blocks,
+      document.starts,
+      { start: fuzzy.start, end: fuzzy.end, score: 0 },
+      "fuzzy",
+    );
+  }
+
+  return null;
+}
+
 /** Resolve an anchor against the current blocks, or null when orphaned. */
 export function resolveAnchor(anchor: Anchor, blocks: Block[]): ResolvedAnchor | null {
   if (anchor.quote === "") return null;
+  if (anchor.quote.includes(BLOCK_SEPARATOR)) return resolveSpanningAnchor(anchor, blocks);
 
   const exact = pickBest(findExactCandidates(anchor, blocks, anchor.quote));
 

package/src/feedback.test.ts

@@ -153,6 +153,73 @@ describe("renderFeedback", () => {
     expect(feedback).toContain("Please clarify.");
   });
 
+  test("a discussion renders as one item: the root comment, then its replies in order", () => {
+    // Arrange: a root, a later reply, an earlier reply, and a reply whose root is gone
+    const anchor = { quote: "daemon memory", prefix: "live only in ", suffix: " today." };
+
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        makeAnnotation({ id: "root", anchor, body: "Which daemon?" }),
+        makeAnnotation({
+          id: "late",
+          anchor,
+          body: "The local one, I think.",
+          replyTo: "root",
+          createdAt: "2026-08-07T00:02:00.000Z",
+        }),
+        makeAnnotation({
+          id: "early",
+          anchor,
+          body: "Worth stating in the plan.",
+          replyTo: "root",
+          author: "SHA256:ana",
+          createdAt: "2026-08-07T00:01:00.000Z",
+        }),
+        makeAnnotation({ id: "stray", anchor, body: "Standalone.", replyTo: "gone" }),
+      ],
+    });
+
+    // Assert: two items, replies listed under the root by time
+    expect(feedback).toContain("## Annotations (2)");
+    expect(feedback).toContain(
+      "Which daemon?\n\nReplies:\n\n- Worth stating in the plan.\n- The local one, I think.\n\nannotation id: `root`",
+    );
+    expect(feedback).toContain("### 2. Comment");
+    expect(feedback).toContain("Standalone.");
+    expect(feedback).not.toContain("annotation id: `late`");
+  });
+
+  test("a reply whose root was addressed leaves the document with it", () => {
+    // Arrange: the root is addressed, its reply is not marked, a stray reply's root is unknown
+    const anchor = { quote: "daemon memory", prefix: "live only in ", suffix: " today." };
+
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        makeAnnotation({
+          id: "root",
+          anchor,
+          body: "Which daemon?",
+          resolution: { revision: 2, source: "agent" },
+        }),
+        makeAnnotation({ id: "reply", anchor, body: "The local one.", replyTo: "root" }),
+        makeAnnotation({ id: "stray", anchor, body: "Standalone.", replyTo: "gone" }),
+      ],
+    });
+
+    // Assert: only the stray reply remains, as its own item
+    expect(feedback).toContain("## Annotations (1)");
+    expect(feedback).not.toContain("The local one.");
+    expect(feedback).toContain("Standalone.");
+  });
+
   test("orphaned anchors are flagged, never dropped", () => {
     // Act
     const feedback = renderFeedback({

package/src/feedback.ts

@@ -43,9 +43,23 @@ export function renderFeedback(input: FeedbackInput): string {
   // agent notes are the submitter's own context - never echoed back as
   // feedback - and annotations a previous revision already addressed stay out
   // of the next document, so the agent only ever sees the open items
-  const annotations = input.annotations.filter(
+  const open = input.annotations.filter(
     (annotation) => !isAgentNote(annotation) && !isAddressed(annotation),
   );
+  // a discussion is one item: the root comment, then its replies in order. A
+  // reply whose root was addressed leaves with it; only a reply whose root is
+  // gone entirely stands on its own
+  const openIds = new Set(open.map((annotation) => annotation.id));
+  const knownIds = new Set(input.annotations.map((annotation) => annotation.id));
+  const annotations = open.filter(
+    (annotation) =>
+      annotation.replyTo === undefined ||
+      (!openIds.has(annotation.replyTo) && !knownIds.has(annotation.replyTo)),
+  );
+  const repliesTo = (root: Annotation): Annotation[] =>
+    open
+      .filter((annotation) => annotation.replyTo === root.id)
+      .toSorted((left, right) => left.createdAt.localeCompare(right.createdAt));
   const isDiff = input.artifactType === "diff";
   const isPrototype = input.artifactType === "prototype";
   // A diff's annotations anchor to the submitted patch rows; resolve against it,
@@ -131,6 +145,14 @@ export function renderFeedback(input: FeedbackInput): string {
       lines.push("");
       lines.push(annotation.body);
       lines.push("");
+      const replies = repliesTo(annotation);
+
+      if (replies.length > 0) {
+        lines.push("Replies:");
+        lines.push("");
+        for (const reply of replies) lines.push(`- ${reply.body.replace(/\n/g, "\n  ")}`);
+        lines.push("");
+      }
       lines.push(`annotation id: \`${annotation.id}\``);
       lines.push("");
     });