@cueloop/schema 0.1.0-alpha.83 → 0.1.0-alpha.85

package/package.json

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

package/src/feedback.ts

@@ -250,6 +250,7 @@ export function feedbackForSession(
   outcome: MessageOutcome,
   summary: string,
   actionBodies?: Record<string, string>,
+  annotations: Annotation[] = session.annotations,
 ): string {
   return renderFeedback({
     outcome,
@@ -257,7 +258,7 @@ export function feedbackForSession(
     artifactContent: session.artifact.content,
     workingCopy: session.workingCopy,
     artifactType: session.artifact.type,
-    annotations: session.annotations,
+    annotations,
     artifactPath: session.artifact.meta.prototypePath ?? session.artifact.meta.planPath,
     sessionId: session.id,
     actionBodies,

package/src/history.ts

@@ -10,7 +10,7 @@
  * feedback document read what this module derives.
  */
 
-import type { Annotation, Thread, Message } from "./types";
+import type { Annotation, Thread, Message, TextCut } from "./types";
 
 export type EntryAuthor = "agent" | "reviewer";
 
@@ -22,7 +22,13 @@ interface EntryBase {
 }
 
 export type SessionEntry =
-  | (EntryBase & { type: "revision"; by: EntryAuthor; content: string })
+  | (EntryBase & {
+      type: "revision";
+      by: EntryAuthor;
+      content: string;
+      /** Exact character Cuts that produced a reviewer revision. */
+      textCuts?: TextCut[];
+    })
   | (EntryBase & { type: "comment"; annotationId: string })
   | (EntryBase & { type: "comment-removed"; annotationId: string })
   | (EntryBase & { type: "message"; message: Message })

package/src/markdown.ts

@@ -1,7 +1,6 @@
 /**
- * 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
+ * Markdown block model: parse source into addressable blocks with source line
+ * ranges and project their text offsets back to source on demand. Round-trip safe for the
  * subset cueloop plans use; unknown constructs fall back to paragraph blocks
  * so no content is ever lost.
  */
@@ -30,6 +29,12 @@ export interface Block {
   lineEnd: number;
 }
 
+export interface BlockTextSourceSegment {
+  textStart: number;
+  textEnd: number;
+  sourceStart: number;
+}
+
 /**
  * The leading block markers the parser strips from a line: headings (h1-h3),
  * bullet list, ordered list, and blockquote. Single source of truth so the
@@ -210,6 +215,101 @@ function nextBlock(lines: string[], lineIndex: number): BlockScan {
   return paragraphBlock(lines, lineIndex);
 }
 
+/** Project marker-free block text boundaries onto the source consumed by the parser. */
+function blockSourceSegments(
+  sourceLines: string[],
+  block: Block,
+  sourceStart = sourceLines
+    .slice(0, block.lineStart)
+    .reduce((offset, line) => offset + line.length + 1, 0),
+): BlockTextSourceSegment[] | undefined {
+  const rawLines = sourceLines.slice(block.lineStart, block.lineEnd + 1);
+  let contentLines: Array<{ rawLine: number; prefix: number }>;
+
+  if (block.kind === "code") {
+    const hasClosingFence = rawLines.at(-1)?.startsWith("```") ?? false;
+    const end = hasClosingFence ? rawLines.length - 1 : rawLines.length;
+
+    contentLines = rawLines.slice(1, end).map((_, index) => ({ rawLine: index + 1, prefix: 0 }));
+  } else if (block.kind === "frontmatter") {
+    contentLines = rawLines.slice(1, -1).map((_, index) => ({ rawLine: index + 1, prefix: 0 }));
+  } else if (block.kind === "quote") {
+    contentLines = rawLines.map((_, rawLine) => ({ rawLine, prefix: 2 }));
+  } else if (
+    block.kind === "h1" ||
+    block.kind === "h2" ||
+    block.kind === "h3" ||
+    block.kind === "li" ||
+    block.kind === "oli"
+  ) {
+    contentLines = [{ rawLine: 0, prefix: rawLines[0]!.length - block.text.length }];
+  } else {
+    contentLines = rawLines.map((_, rawLine) => ({ rawLine, prefix: 0 }));
+  }
+  const content = contentLines
+    .map(({ rawLine, prefix }) => rawLines[rawLine]!.slice(prefix))
+    .join("\n");
+
+  if (content !== block.text) return undefined;
+  const rawLineStarts: number[] = [];
+  let rawOffset = 0;
+
+  for (const line of rawLines) {
+    rawLineStarts.push(rawOffset);
+    rawOffset += line.length + 1;
+  }
+  let textOffset = 0;
+  const segments = contentLines.map(({ rawLine, prefix }) => {
+    const line = rawLines[rawLine]!.slice(prefix);
+    const lineStart = sourceStart + rawLineStarts[rawLine]! + prefix;
+    const segment = {
+      textStart: textOffset,
+      textEnd: textOffset + line.length,
+      sourceStart: lineStart,
+    };
+
+    textOffset += line.length + 1;
+
+    return segment;
+  });
+
+  return segments;
+}
+
+/** Project several parsed blocks onto source offsets without splitting the Markdown per block. */
+export function blockTextSourceSegments(
+  markdown: string,
+  blocks: readonly Block[],
+): Array<readonly BlockTextSourceSegment[] | undefined> {
+  const sourceLines = markdown.split("\n");
+  const lineStarts: number[] = [];
+  let sourceOffset = 0;
+
+  for (const line of sourceLines) {
+    lineStarts.push(sourceOffset);
+    sourceOffset += line.length + 1;
+  }
+
+  return blocks.map((block) =>
+    blockSourceSegments(sourceLines, block, lineStarts[block.lineStart] ?? sourceOffset),
+  );
+}
+
+/** Resolve a marker-free block-text boundary through the parser's source projection. */
+export function sourceOffsetAt(
+  markdown: string,
+  block: Block,
+  textOffset: number,
+): number | undefined {
+  for (const segment of blockSourceSegments(markdown.split("\n"), block) ?? []) {
+    if (textOffset < segment.textStart || textOffset > segment.textEnd) continue;
+
+    return segment.sourceStart + textOffset - segment.textStart;
+  }
+
+  return undefined;
+}
+
 export function parseBlocks(markdown: string): Block[] {
   const lines = markdown.split("\n");
   const blocks: Block[] = [];

package/src/path-view.test.ts

@@ -37,6 +37,7 @@ function threaded(): SessionHistory {
     type: "revision",
     by: "reviewer",
     content: "Plan v1 edited",
+    textCuts: [{ start: 5, end: 8, quote: "v1 " }],
     createdAt: AT,
   }).history;
   history = appendEntry(history, { type: "comment", annotationId: "a2", createdAt: AT }).history;
@@ -52,6 +53,7 @@ describe("viewOfPath", () => {
     // Assert
     expect(view.content).toBe("Plan v1");
     expect(view.workingCopy).toBe("Plan v1 edited");
+    expect(view.textCuts).toEqual([{ start: 5, end: 8, quote: "v1 " }]);
     expect(view.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
     expect(view.shelvedAnnotations).toEqual([]);
   });
@@ -73,9 +75,11 @@ describe("viewOfPath", () => {
 
     // Assert
     expect(back.workingCopy).toBeUndefined();
+    expect(back.textCuts).toBeUndefined();
     expect(back.annotations.map((entry) => entry.id)).toEqual(["a1"]);
     expect(back.shelvedAnnotations.map((entry) => entry.id)).toEqual(["a2"]);
     expect(forward.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect(forward.textCuts).toEqual([{ start: 5, end: 8, quote: "v1 " }]);
     expect(forward.shelvedAnnotations).toEqual([]);
   });
 
@@ -119,6 +123,7 @@ describe("applyPathView", () => {
     applyPathView(session, {
       content: "Plan v1",
       workingCopy: undefined,
+      textCuts: undefined,
       annotations: [annotation("a1"), annotation("a2")],
       shelvedAnnotations: [],
     });

package/src/path-view.ts

@@ -7,13 +7,15 @@
  */
 
 import { derivePath, followBranch, MAIN_BRANCH, pathOf, type SessionHistory } from "./history";
-import type { Annotation, Thread } from "./types";
+import type { Annotation, Thread, TextCut } from "./types";
 
 export interface PathView {
   /** The last agent revision on the path: what the artifact shows. */
   content: string;
   /** The reviewer's edits over it, when the path's head is a reviewer revision. */
   workingCopy: string | undefined;
+  /** Exact character Cuts attached to the reviewer revision at the path head. */
+  textCuts: TextCut[] | undefined;
   /** The comments open on the path, in path order. */
   annotations: Annotation[];
   /** Every other comment the session knows. */
@@ -45,6 +47,7 @@ export function viewOfPath(history: SessionHistory, known: Annotation[]): PathVi
   return {
     content,
     workingCopy: derived.head.content === content ? undefined : derived.head.content,
+    textCuts: derived.head.by === "reviewer" ? derived.head.textCuts : undefined,
     annotations,
     shelvedAnnotations: [...byId.values()],
   };
@@ -54,6 +57,8 @@ export function viewOfPath(history: SessionHistory, known: Annotation[]): PathVi
 export function applyPathView(session: Thread, view: PathView): void {
   session.artifact = { ...session.artifact, content: view.content };
   session.annotations = view.annotations;
+  if (view.textCuts?.length) session.textCuts = view.textCuts;
+  else delete session.textCuts;
   if (view.workingCopy === undefined) delete session.workingCopy;
   else session.workingCopy = view.workingCopy;
   if (view.shelvedAnnotations.length === 0) delete session.shelvedAnnotations;

package/src/types.test.ts

@@ -45,7 +45,7 @@ describe("WORKFLOW_KINDS", () => {
 describe("messageAllows", () => {
   test("only approve maps to allow", () => {
     expect(messageAllows("approved")).toBe(true);
-    expect(messageAllows("changes_requested")).toBe(false);
+    expect(messageAllows("comment")).toBe(false);
     expect(messageAllows("changes_requested")).toBe(false);
   });
 });

package/src/types.ts

@@ -232,7 +232,8 @@ export interface PendingDelivery {
   message: Message;
 }
 
-export type MessageOutcome = "approved" | "changes_requested";
+export const MESSAGE_OUTCOMES = ["comment", "approved", "changes_requested"] as const;
+export type MessageOutcome = (typeof MESSAGE_OUTCOMES)[number];
 
 export interface Message {
   /** Stable identity used to deduplicate at-least-once harness delivery. */
@@ -241,6 +242,8 @@ export interface Message {
   summary: string;
   /** The structured review document sent to the harness. */
   body: string;
+  /** Annotation snapshots included in this delivery, for incremental sends. */
+  annotations?: Annotation[];
   sentAt: string;
 }
 
@@ -294,6 +297,13 @@ export interface ShareLink {
   shareBranch?: string;
 }
 
+/** One exact character range removed from the submitted artifact source. */
+export interface TextCut {
+  start: number;
+  end: number;
+  quote: string;
+}
+
 export interface Thread {
   schemaVersion: string;
   id: string;
@@ -317,6 +327,8 @@ export interface Thread {
    * Undefined = no direct edits.
    */
   workingCopy?: string;
+  /** Exact source ranges behind character Cuts in the current working copy. */
+  textCuts?: TextCut[];
   /**
    * File paths the reviewer marked viewed during the guided walk (diff
    * sessions). Persisting with the session means a resumed review keeps its

package/src/working-copy.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { cutBlock, restoreBlock, restoreLine, sourceChunk } from "./working-copy";
+import {
+  applyTextCuts,
+  blockCutSourceRange,
+  cutBlock,
+  cutTextRange,
+  mergeTextCut,
+  restoreTextCut,
+  restoreBlock,
+  restoreLine,
+  sourceChunk,
+} from "./working-copy";
 import { parseBlocks, type Block } from "./markdown";
 
 const BASE = `# Plan
@@ -64,6 +74,134 @@ describe("cutBlock", () => {
     expect(cut).not.toContain("const x");
     expect(cut).toContain("- second item");
   });
+
+  test.each(["Plan", "spans two lines", "first item", "const x"])(
+    "reports the exact source interval cut from %s",
+    (text) => {
+      const target = block(BASE, text);
+      const range = blockCutSourceRange(BASE, target);
+
+      expect(BASE.slice(0, range.start) + BASE.slice(range.end)).toBe(cutBlock(BASE, target));
+    },
+  );
+});
+
+describe("cutTextRange", () => {
+  test("cuts only the selected characters inside a block", () => {
+    const paragraph = block(BASE, "spans two lines");
+    const start = paragraph.text.indexOf("paragraph");
+    const cut = cutTextRange(BASE, paragraph, start, paragraph, start + "paragraph".length);
+
+    expect(cut).toContain("A  that\nspans two lines.");
+    expect(cut).toContain("## Context");
+    expect(cut).toContain("- first item");
+  });
+
+  test("preserves a list marker around a partial cut", () => {
+    const item = block(BASE, "first item");
+    const cut = cutTextRange(BASE, item, 0, item, "first ".length);
+
+    expect(cut).toContain("- item");
+    expect(cut).not.toContain("- first item");
+  });
+
+  test.each([
+    ["heading", "# remove keep", "#  keep"],
+    ["ordered list", "12. remove keep", "12.  keep"],
+    ["fenced code", "```ts\nremove keep\n```", "```ts\n keep\n```"],
+    ["frontmatter", "---\nname: remove keep\n---", "---\nname:  keep\n---"],
+    ["table", "| remove | keep |\n| --- | --- |", "|  | keep |\n| --- | --- |"],
+  ])("preserves %s source markers", (_label, source, expected) => {
+    const target = block(source, "remove");
+    const start = target.text.indexOf("remove");
+
+    expect(cutTextRange(source, target, start, target, start + "remove".length)).toBe(expected);
+  });
+
+  test("cuts an exact range across marked quote lines", () => {
+    const source = "> keep alpha\n> remove beta\n> keep gamma";
+    const quote = parseBlocks(source)[0]!;
+    const start = quote.text.indexOf("alpha");
+    const end = quote.text.indexOf("keep gamma");
+
+    const cut = cutTextRange(source, quote, start, quote, end);
+
+    expect(cut).toBe("> keep keep gamma");
+  });
+
+  test("cuts an exact range across separate blocks", () => {
+    const source = "Keep before remove this.\n\n- remove that keep after";
+    const blocks = parseBlocks(source);
+    const first = blocks[0]!;
+    const second = blocks[1]!;
+    const start = first.text.indexOf("remove");
+    const end = second.text.indexOf("keep after");
+
+    const cut = cutTextRange(source, first, start, second, end);
+
+    expect(cut).toBe("Keep before keep after");
+  });
+});
+
+describe("exact text Cuts", () => {
+  test("stores and applies the selected source characters exactly", () => {
+    const source = "It lands under unin Threads then in the sidebar.";
+    const start = source.indexOf("under");
+    const end = source.indexOf(" in the sidebar");
+    const cuts = mergeTextCut(source, [], start, end);
+
+    expect(cuts).toEqual([{ start, end, quote: "under unin Threads then" }]);
+    expect(applyTextCuts(source, cuts)).toBe("It lands  in the sidebar.");
+  });
+
+  test("merges overlapping and adjacent ranges in one linear source interval", () => {
+    const source = "alpha beta gamma delta";
+    const first = mergeTextCut(source, [], 6, 10);
+    const merged = mergeTextCut(source, first, 10, 16);
+
+    expect(merged).toEqual([{ start: 6, end: 16, quote: "beta gamma" }]);
+    expect(applyTextCuts(source, merged)).toBe("alpha  delta");
+  });
+
+  test("returns the original references for no-op ranges", () => {
+    const source = "unchanged";
+    const cuts = [{ start: 0, end: 2, quote: "un" }];
+
+    expect(mergeTextCut(source, cuts, 4, 4)).toBe(cuts);
+    expect(applyTextCuts(source, [])).toBe(source);
+  });
+
+  test("applies out-of-order Cuts and ignores stale or overlapping records", () => {
+    const source = "alpha beta gamma";
+
+    expect(
+      applyTextCuts(source, [
+        { start: 11, end: 16, quote: "gamma" },
+        { start: 0, end: 5, quote: "alpha" },
+        { start: 2, end: 8, quote: "stale" },
+        { start: 6, end: 10, quote: "beta" },
+      ]),
+    ).toBe("  ");
+  });
+
+  test("restores an exact subrange without disturbing the rest of its Cut", () => {
+    const source = "alpha beta gamma delta";
+    const cuts = mergeTextCut(source, [], 6, 16);
+    const restored = restoreTextCut(source, cuts, 11, 16);
+
+    expect(restored).toEqual([{ start: 6, end: 11, quote: "beta " }]);
+    expect(applyTextCuts(source, restored ?? [])).toBe("alpha gamma delta");
+  });
+
+  test("does not restore across separate Cuts", () => {
+    const source = "alpha beta gamma delta";
+    const cuts = [
+      { start: 6, end: 10, quote: "beta" },
+      { start: 11, end: 16, quote: "gamma" },
+    ];
+
+    expect(restoreTextCut(source, cuts, 6, 16)).toBeNull();
+  });
 });
 
 describe("restoreBlock", () => {

package/src/working-copy.ts

@@ -1,11 +1,90 @@
-/**
- * Working-copy block surgery: the only module that slices raw source text by
- * Block line ranges. Cut removes a block's lines; restore re-inserts a base
- * block's chunk and reports when the working copy round-trips back to the
- * submitted revision (pristine). Callers never touch lineStart/lineEnd.
- */
+/** Working-copy source surgery for block and character cuts plus block restoration. */
+
+import { parseBlocks, sourceOffsetAt, type Block } from "./markdown";
+import type { TextCut } from "./types";
+
+/** Add one source range and normalize overlaps without copying on a no-op. */
+export function mergeTextCut(
+  source: string,
+  cuts: readonly TextCut[],
+  start: number,
+  end: number,
+): TextCut[] {
+  const boundedStart = Math.max(0, Math.min(start, source.length));
+  const boundedEnd = Math.max(boundedStart, Math.min(end, source.length));
+
+  if (boundedEnd === boundedStart) {
+    // SAFETY: a no-op returns the caller's array unchanged; callers never mutate the result.
+    return cuts as TextCut[];
+  }
+  const ranges = [
+    ...cuts.map((cut) => ({ start: cut.start, end: cut.end })),
+    { start: boundedStart, end: boundedEnd },
+  ]
+    .map((range) => ({
+      start: Math.max(0, Math.min(range.start, source.length)),
+      end: Math.max(0, Math.min(range.end, source.length)),
+    }))
+    .filter((range) => range.end > range.start)
+    .toSorted((left, right) => left.start - right.start || left.end - right.end);
+  const merged: Array<{ start: number; end: number }> = [];
+
+  for (const range of ranges) {
+    const previous = merged.at(-1);
+
+    if (previous && range.start <= previous.end) previous.end = Math.max(previous.end, range.end);
+    else merged.push(range);
+  }
+
+  return merged.map((range) => ({
+    ...range,
+    quote: source.slice(range.start, range.end),
+  }));
+}
+
+/** Restore a selected part of one contiguous character Cut. */
+export function restoreTextCut(
+  source: string,
+  cuts: readonly TextCut[],
+  start: number,
+  end: number,
+): TextCut[] | null {
+  const cutIndex = cuts.findIndex((cut) => cut.start <= start && end <= cut.end);
+
+  if (cutIndex === -1 || end <= start) return null;
+  const cut = cuts[cutIndex]!;
+  const replacements: TextCut[] = [];
+
+  if (cut.start < start) {
+    replacements.push({ start: cut.start, end: start, quote: source.slice(cut.start, start) });
+  }
+  if (end < cut.end) {
+    replacements.push({ start: end, end: cut.end, quote: source.slice(end, cut.end) });
+  }
+
+  return [...cuts.slice(0, cutIndex), ...replacements, ...cuts.slice(cutIndex + 1)];
+}
+
+/** Apply valid source ranges in source order, ignoring stale or overlapping records. */
+export function applyTextCuts(source: string, cuts: readonly TextCut[]): string {
+  if (cuts.length === 0) return source;
+  let cursor = 0;
+  const pieces: string[] = [];
 
-import { parseBlocks, type Block } from "./markdown";
+  for (const cut of cuts.toSorted(
+    (left, right) => left.start - right.start || left.end - right.end,
+  )) {
+    if (cut.start < cursor || cut.start < 0 || cut.end > source.length || cut.end <= cut.start)
+      continue;
+    if (source.slice(cut.start, cut.end) !== cut.quote) continue;
+
+    pieces.push(source.slice(cursor, cut.start));
+    cursor = cut.end;
+  }
+  pieces.push(source.slice(cursor));
+
+  return pieces.join("");
+}
 
 /** Chunk of the base source a block occupies (for restore and display). */
 export function sourceChunk(base: string, block: Block): string {
@@ -25,6 +104,44 @@ export function cutBlock(working: string, block: Block): string {
   return [...before, ...after].join("\n");
 }
 
+/** Source interval removed by a whole-block Cut, including its leading blank-line padding. */
+export function blockCutSourceRange(source: string, block: Block) {
+  const lines = source.split("\n");
+  let startLine = block.lineStart;
+
+  while (startLine > 0 && lines[startLine - 1]!.trim() === "") startLine--;
+  const lineStarts = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source.charCodeAt(index) === 10) lineStarts.push(index + 1);
+  }
+
+  return {
+    start: lineStarts[startLine] ?? source.length,
+    end: lineStarts[block.lineEnd + 1] ?? source.length,
+  };
+}
+
+/**
+ * Remove exactly the selected block-text range while retaining surrounding
+ * Markdown markers. A cross-block range also removes the source between its
+ * endpoint characters.
+ */
+export function cutTextRange(
+  working: string,
+  startBlock: Block,
+  start: number,
+  endBlock: Block,
+  end: number,
+): string {
+  const sourceStart = sourceOffsetAt(working, startBlock, start) ?? -1;
+  const sourceEnd = sourceOffsetAt(working, endBlock, end) ?? -1;
+
+  if (sourceStart < 0 || sourceEnd <= sourceStart) return working;
+
+  return working.slice(0, sourceStart) + working.slice(sourceEnd);
+}
+
 /** The line a restored block re-enters at: the next surviving block's start. */
 export function restoreLine(next: Block | undefined, workingLineCount: number): number {
   return next ? next.lineStart : workingLineCount;