@cueloop/schema 0.1.0-alpha.20 → 0.1.0-alpha.22

package/package.json

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

package/src/anchor.test.ts

@@ -21,74 +21,110 @@ function blocksOf(markdown: string) {
 
 describe("anchor cascade", () => {
   test("makeAnchor captures quote + context selectors", () => {
+    // Arrange
     const blocks = blocksOf(DOC);
     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 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 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 storageBlockIndex = blocks.findIndex((block) => block.text.includes("atomically"));
     // anchor on the SECOND "Sessions are written" occurrence
     const text = blocks[storageBlockIndex]!.text;
     const second = text.indexOf("Sessions are written", text.indexOf("Sessions are written") + 1);
     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", () => {
+    // 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("trimmed-quote fallback marks the resolution approximate", () => {
+    // Arrange
     const blocks = blocksOf("some text here");
     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
+
+    // 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 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();
   });
 });

package/src/diff.test.ts

@@ -7,9 +7,14 @@ describe("unifiedDiff", () => {
   });
 
   test("produces hunk headers with correct line numbers", () => {
+    // Arrange
     const oldText = ["l1", "l2", "l3", "l4", "l5", "l6", "l7", "l8"].join("\n");
     const newText = ["l1", "l2", "l3", "CHANGED", "l5", "l6", "l7", "l8"].join("\n");
+
+    // Act
     const diffLines = unifiedDiff(oldText, newText, 1)!;
+
+    // Assert
     expect(diffLines[0]!.kind).toBe("hunk");
     expect(diffLines[0]!.text).toBe("@@ -3,3 +3,3 @@");
     expect(diffLines.map((line) => line.text)).toEqual([
@@ -22,18 +27,28 @@ describe("unifiedDiff", () => {
   });
 
   test("distant changes split into separate hunks", () => {
+    // Arrange
     const oldLines = Array.from({ length: 30 }, (_, i) => `line ${i + 1}`);
     const newLines = [...oldLines];
     newLines[1] = "first change";
     newLines[27] = "second change";
+
+    // Act
     const diffLines = unifiedDiff(oldLines.join("\n"), newLines.join("\n"), 2)!;
+
+    // Assert
     expect(diffLines.filter((line) => line.kind === "hunk").length).toBe(2);
   });
 
   test("applies cleanly: reconstructing new text from old + diff", () => {
+    // Arrange
     const oldText = "keep\ndrop\nkeep2\nkeep3";
     const newText = "keep\nadded\nkeep2\nkeep3\ntail";
+
+    // Act
     const diffLines = unifiedDiff(oldText, newText, 50)!;
+
+    // Assert
     const rebuilt: string[] = [];
     for (const line of diffLines) {
       if (line.kind === "hunk") continue;
@@ -43,7 +58,10 @@ describe("unifiedDiff", () => {
   });
 
   test("unifiedDiffText carries file headers and path", () => {
+    // Act
     const diffText = unifiedDiffText("a", "b", "docs/plan.md")!;
+
+    // Assert
     expect(diffText.startsWith("--- a/docs/plan.md\n+++ b/docs/plan.md\n@@")).toBe(true);
   });
 });
@@ -56,7 +74,10 @@ describe("editStats", () => {
 
 describe("wordDiff", () => {
   test("preserves whitespace tokens and reconstructs both sides", () => {
+    // Act
     const ops = wordDiff("the quick brown fox", "the slow brown foxes");
+
+    // Assert
     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");
@@ -66,7 +87,10 @@ describe("wordDiff", () => {
 
 describe("lcsDiff", () => {
   test("custom equality", () => {
+    // Act
     const ops = lcsDiff([{ v: 1 }, { v: 2 }], [{ v: 2 }, { v: 3 }], (oldItem, newItem) => oldItem.v === newItem.v);
+
+    // Assert
     expect(ops.map((op) => op.kind)).toEqual(["del", "ctx", "add"]);
   });
 });

package/src/feedback.test.ts

@@ -25,6 +25,7 @@ function makeAnnotation(partial: Partial<Annotation> & { anchor: Annotation["anc
 
 describe("renderFeedback", () => {
   test("plan edits section carries the one unified diff, directive framing first", () => {
+    // Act
     const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "Tighten the storage section.",
@@ -33,6 +34,8 @@ describe("renderFeedback", () => {
       annotations: [],
       planPath: "docs/plan.md",
     });
+
+    // Assert
     expect(feedback).toContain("# Review: request changes");
     expect(feedback).toContain("Tighten the storage section.");
     expect(feedback).toContain("## Plan edits");
@@ -43,6 +46,7 @@ describe("renderFeedback", () => {
   });
 
   test("annotations are located by quote and section", () => {
+    // Act
     const feedback = renderFeedback({
       verdictKind: "comment",
       summary: "",
@@ -53,6 +57,8 @@ describe("renderFeedback", () => {
         }),
       ],
     });
+
+    // Assert
     expect(feedback).toContain("## Annotations (1)");
     expect(feedback).toContain("### 1. Comment (§ Context)");
     expect(feedback).toContain("> daemon memory");
@@ -60,6 +66,7 @@ describe("renderFeedback", () => {
   });
 
   test("suggestions render as replace/with pairs", () => {
+    // Act
     const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
@@ -72,39 +79,52 @@ describe("renderFeedback", () => {
         }),
       ],
     });
+
+    // Assert
     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", () => {
+    // Act
     const feedback = renderFeedback({
       verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
       annotations: [makeAnnotation({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } })],
     });
+
+    // Assert
     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", () => {
+    // Act
     const feedback = renderFeedback({
       verdictKind: "approve",
       summary: "",
       artifactContent: PLAN,
       annotations: [],
     });
+
+    // Assert
     expect(feedback).toContain("_No edits or annotations._");
   });
 
   test("agent notes never come back as feedback items", () => {
+    // Arrange
     const note = makeAnnotation({
       kind: "note",
       anchor: { quote: "src/a.ts", prefix: "", suffix: "" },
       body: "The agent's own explanation of the change.",
     });
+
+    // Act
     const noteOnly = renderFeedback({ verdictKind: "approve", summary: "", artifactContent: PLAN, annotations: [note] });
+
+    // Assert
     expect(noteOnly).toContain("_No edits or annotations._");
     expect(noteOnly).not.toContain("The agent's own explanation of the change.");
     const mixed = renderFeedback({
@@ -118,8 +138,11 @@ describe("renderFeedback", () => {
   });
 
   test("anchors resolve against the working copy when present", () => {
+    // Arrange
     // annotation made on text that only exists in the edited copy
     const working = PLAN.replace("## Storage", "## Persistence");
+
+    // Act
     const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
@@ -129,6 +152,8 @@ describe("renderFeedback", () => {
         makeAnnotation({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } }),
       ],
     });
+
+    // Assert
     expect(feedback).toContain("(§ Persistence)");
   });
 });

package/src/feedback.ts

@@ -5,7 +5,7 @@
  * by quoted text.
  */
 
-import { isAgentNote, type Annotation, type ReviewSession, type VerdictKind } from "./types";
+import { isAddressed, isAgentNote, type Annotation, type ReviewSession, type VerdictKind } from "./types";
 import { parseBlocks, sectionOf } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
@@ -20,14 +20,18 @@ export interface FeedbackInput {
   annotations: Annotation[];
   /** Path the agent knows the plan by, for direct reference. */
   planPath?: string;
+  /** Session id, so the document can teach the addressed-ids resubmit call. */
+  sessionId?: string;
 }
 
 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));
+  // 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((annotation) => !isAgentNote(annotation) && !isAddressed(annotation));
   const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
   const lines: string[] = [];
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
@@ -76,7 +80,20 @@ export function renderFeedback(input: FeedbackInput): string {
         lines.push(annotation.body);
       }
       lines.push("");
+      lines.push(`annotation id: \`${annotation.id}\``);
+      lines.push("");
     });
+    if (input.sessionId) {
+      lines.push("## Reporting what you addressed");
+      lines.push("");
+      lines.push("When you resubmit the revised plan, list the annotation ids you acted on -");
+      lines.push("they are marked addressed for the reviewer and leave the open list:");
+      lines.push("");
+      lines.push("```sh");
+      lines.push(`cueloop session submit-revision ${input.sessionId} --content-file ${path} --addressed <id,id,...>`);
+      lines.push("```");
+      lines.push("");
+    }
   }
 
   if (!diff && !annotations.length) {
@@ -94,6 +111,7 @@ export function feedbackForSession(session: ReviewSession, verdictKind: VerdictK
     workingCopy: session.workingCopy,
     annotations: session.annotations,
     planPath: session.artifact.meta.planPath,
+    sessionId: session.id,
   });
 }
 

package/src/herdr.test.ts

@@ -26,7 +26,10 @@ describe("returnPaneFor", () => {
   });
 
   test("env override wins, session meta is the fallback", () => {
+    // Arrange
     const inside = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p9" };
+
+    // Assert
     expect(returnPaneFor("w1:p1", inside)).toBe("w1:p1");
     expect(returnPaneFor("w1:p1", { ...inside, CUELOOP_RETURN_PANE: "w1:p2" })).toBe("w1:p2");
   });

package/src/markdown.test.ts

@@ -29,7 +29,10 @@ const y = 2;
 
 describe("parseBlocks", () => {
   test("parses every block kind with source line ranges", () => {
+    // Act
     const blocks = parseBlocks(SAMPLE);
+
+    // Assert
     expect(blocks.map((block) => block.kind)).toEqual([
       "h1",
       "h2",
@@ -51,14 +54,20 @@ describe("parseBlocks", () => {
   });
 
   test("multi-line paragraph keeps its text and range", () => {
+    // Arrange
     const blocks = parseBlocks(SAMPLE);
     const paragraph = blocks.find((block) => block.kind === "p")!;
+
+    // Assert
     expect(paragraph.text).toBe("A paragraph that\nspans two lines.");
     expect(paragraph.lineEnd - paragraph.lineStart).toBe(1);
   });
 
   test("line ranges index into the source", () => {
+    // Arrange
     const lines = SAMPLE.split("\n");
+
+    // Assert
     for (const block of parseBlocks(SAMPLE)) {
       if (block.kind === "code") {
         expect(lines[block.lineStart]!.startsWith("```")).toBe(true);
@@ -69,6 +78,7 @@ describe("parseBlocks", () => {
   });
 
   test("round-trips through blockToMd", () => {
+    // Arrange
     const blocks = parseBlocks(SAMPLE);
     let orderedItemCount = 0;
     const rebuilt = blocks
@@ -77,21 +87,33 @@ describe("parseBlocks", () => {
         return blockToMd(block, orderedItemCount || 1);
       })
       .join("\n\n");
+
+    // Act
     // re-parsing the rebuild yields the same kinds and texts
     const again = parseBlocks(rebuilt);
+
+    // Assert
     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", () => {
+    // Arrange
     const md = "| a | b |\n|---|---|\n| 1 | 2 |";
+
+    // Act
     const blocks = parseBlocks(md);
+
+    // Assert
     expect(blocks.map((block) => block.text).join("\n")).toContain("| a | b |");
   });
 });
 
 describe("sectionOf", () => {
   test("returns the nearest preceding heading", () => {
+    // Arrange
     const blocks = parseBlocks(SAMPLE);
+
+    // Assert
     const orderedItemIndex = blocks.findIndex((block) => block.kind === "oli");
     expect(sectionOf(blocks, orderedItemIndex)).toBe("Steps");
     const paragraphIndex = blocks.findIndex((block) => block.kind === "p");

package/src/types.test.ts

@@ -11,7 +11,10 @@ describe("verdictAllows", () => {
 
 describe("newAnnotationId", () => {
   test("unique by construction within a process, even on one millisecond", () => {
+    // Act
     const ids = new Set(Array.from({ length: 10_000 }, () => newAnnotationId()));
+
+    // Assert
     expect(ids.size).toBe(10_000);
     for (const id of ids) expect(id).toMatch(/^a_[0-9a-z]+_[0-9a-z]+$/);
   });

package/src/types.ts

@@ -72,9 +72,33 @@ export interface Annotation {
   body: string;
   /** Set by resolution when the quote can no longer be found. */
   orphan?: boolean;
+  /**
+   * SSH key fingerprint of a share collaborator who authored this note. Absent
+   * on the planner's own annotations; the sharing gateway stamps it so the
+   * planner can tell whose note is whose and never overwrite a collaborator's.
+   */
+  author?: string;
+  /**
+   * Set when a revision addressed this annotation: the agent reported the id
+   * on resubmit ("agent"), or the quoted text disappeared from the revised
+   * plan ("drift"). Addressed annotations leave the default rail view and the
+   * next feedback document, but are never deleted.
+   */
+  resolution?: AnnotationResolution;
   createdAt: string;
 }
 
+export interface AnnotationResolution {
+  /** The revision number whose submission addressed this annotation. */
+  revision: number;
+  source: "agent" | "drift";
+}
+
+/** An annotation a revision has addressed; it leaves the default views. */
+export function isAddressed(annotation: Annotation): boolean {
+  return annotation.resolution !== undefined;
+}
+
 export type VerdictKind = "comment" | "approve" | "request_changes";
 
 export interface Verdict {

package/src/working-copy.test.ts

@@ -35,19 +35,28 @@ describe("sourceChunk", () => {
 
 describe("cutBlock", () => {
   test("removes the block lines and the blank line before it", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "spans two lines"));
+
+    // Assert
     expect(cut).not.toContain("spans two lines");
     expect(cut).toContain("## Context\n\n- first item");
   });
 
   test("cut at the start of the document leaves the leading blank line", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "Plan"));
+
+    // Assert
     expect(cut).not.toContain("# Plan");
     expect(cut.trimStart().startsWith("## Context")).toBe(true);
   });
 
   test("cut at the end of the document keeps the rest intact", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "const x"));
+
+    // Assert
     expect(cut).not.toContain("const x");
     expect(cut).toContain("- second item");
   });
@@ -55,43 +64,66 @@ describe("cutBlock", () => {
 
 describe("restoreBlock", () => {
   test("restoring the only cut returns undefined - back to pristine", () => {
+    // Arrange
     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((candidate) => candidate.kind === "code");
+
+    // Act
     const restored = restoreBlock(BASE, cut, listItem, restoreLine(next, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("restore after another edit returns the merged working copy", () => {
+    // Arrange
     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");
+
+    // Act
     const restored = restoreBlock(BASE, edited, listItem, restoreLine(next, edited.split("\n").length));
+
+    // Assert
     expect(restored).toContain("- second item");
     expect(restored).toContain("first item reworded");
   });
 
   test("restore at the end of the document (no next block)", () => {
+    // Arrange
     const code = block(BASE, "const x");
     const cut = cutBlock(BASE, code);
+
+    // Act
     const restored = restoreBlock(BASE, cut, code, restoreLine(undefined, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("restore a multi-line block round-trips to pristine", () => {
+    // Arrange
     const paragraph = block(BASE, "spans two lines");
     const cut = cutBlock(BASE, paragraph);
     const next = parseBlocks(cut).find((block) => block.text === "first item");
+
+    // Act
     const restored = restoreBlock(BASE, cut, paragraph, restoreLine(next, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("signature rule ignores blank-line layout but not text changes", () => {
+    // Arrange
     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);
+
+    // Assert
     // extra blank lines elsewhere do not block pristine detection
     expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line)).toBeUndefined();
     // a real text change keeps the working copy alive
@@ -102,7 +134,10 @@ describe("restoreBlock", () => {
 
 describe("restoreLine", () => {
   test("next surviving block's start, or the line count at the end", () => {
+    // Arrange
     const listItem = block(BASE, "first item");
+
+    // Assert
     expect(restoreLine(listItem, 99)).toBe(listItem.lineStart);
     expect(restoreLine(undefined, 99)).toBe(99);
   });