@cueloop/schema 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@cueloop/schema",
+  "version": "0.1.0-alpha.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "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"
+  }
+}

package/src/anchor.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { parseBlocks } from "./markdown";
+import { makeAnchor, resolveAnchor } from "./anchor";
+
+const DOC = `# Plan
+
+## Context
+
+Review sessions currently live only in daemon memory. If the daemon crashes,
+every pending annotation is lost.
+
+## Storage
+
+Sessions are written as one JSON document per session. Sessions are written
+atomically.
+`;
+
+function blocksOf(md: string) {
+  return parseBlocks(md);
+}
+
+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);
+  });
+
+  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);
+  });
+
+  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 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");
+  });
+
+  test("prefix/suffix selectors disambiguate repeated quotes", () => {
+    const blocks = blocksOf(DOC);
+    const storIdx = blocks.findIndex((b) => b.text.includes("atomically"));
+    // anchor on the SECOND "Sessions are written" occurrence
+    const text = blocks[storIdx]!.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);
+  });
+
+  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);
+  });
+
+  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 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);
+  });
+
+  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 edited = blocksOf(DOC.replace(/Review sessions[^\n]*\n[^\n]*/, "Completely different text."));
+    expect(resolveAnchor(a, edited)).toBeNull();
+  });
+
+  test("empty quote never binds", () => {
+    const blocks = blocksOf(DOC);
+    expect(resolveAnchor({ quote: "", prefix: "", suffix: "" }, blocks)).toBeNull();
+  });
+});

package/src/anchor.ts

@@ -0,0 +1,74 @@
+/**
+ * Anchor resolution: the quote-primary cascade (map #2, #22, verified in the
+ * edit-mode deep-dive). 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
+ *   3. orphan - keep the quote for display, drop the highlight.
+ * Never silently bind to the wrong text.
+ */
+
+import type { Anchor } from "./types";
+import type { Block } from "./markdown";
+
+const CONTEXT = 24;
+
+export interface ResolvedAnchor {
+  blockIndex: number;
+  start: number;
+  end: number;
+  /** True when the quote had to be trimmed to bind. */
+  approximate: boolean;
+}
+
+export function makeAnchor(blocks: Block[], blockIndex: number, start: number, end: number): Anchor {
+  const t = blocks[blockIndex]?.text ?? "";
+  return {
+    quote: t.slice(start, end),
+    prefix: t.slice(Math.max(0, start - CONTEXT), start),
+    suffix: t.slice(end, end + CONTEXT),
+    blockIndex,
+    start,
+    end,
+  };
+}
+
+interface Candidate extends ResolvedAnchor {
+  score: number;
+}
+
+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);
+      let score = 0;
+      if (pre === anchor.prefix) score += 2;
+      if (suf === 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 });
+    }
+  });
+  return out;
+}
+
+/** 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;
+  let candidates = findCandidates(anchor, blocks, anchor.quote);
+  let approximate = false;
+  if (candidates.length === 0) {
+    const trimmed = anchor.quote.trim();
+    if (trimmed !== "" && trimmed !== anchor.quote) {
+      candidates = findCandidates(anchor, blocks, trimmed);
+      approximate = true;
+    }
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => b.score - a.score);
+  const best = candidates[0]!;
+  return { ...best, approximate };
+}

package/src/diff.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { lcsDiff, unifiedDiff, unifiedDiffText, editStats, wordDiff } from "./diff";
+
+describe("unifiedDiff", () => {
+  test("equal inputs return null, not an empty diff", () => {
+    expect(unifiedDiff("a\nb", "a\nb")).toBeNull();
+  });
+
+  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([
+      "@@ -3,3 +3,3 @@",
+      " l3",
+      "-l4",
+      "+CHANGED",
+      " l5",
+    ]);
+  });
+
+  test("distant changes split into separate hunks", () => {
+    const oldLines = Array.from({ length: 30 }, (_, i) => `line ${i + 1}`);
+    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);
+  });
+
+  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 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));
+    }
+    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);
+  });
+});
+
+describe("editStats", () => {
+  test("counts added and removed lines", () => {
+    expect(editStats("a\nb\nc", "a\nx\nc\nd")).toEqual({ added: 2, removed: 1 });
+  });
+});
+
+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("");
+    expect(oldSide).toBe("the quick brown fox");
+    expect(newSide).toBe("the slow brown foxes");
+  });
+});
+
+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"]);
+  });
+});

package/src/diff.ts

@@ -0,0 +1,131 @@
+/**
+ * Line/token diffing and unified-diff serialization. The working copy
+ * serializes as ONE unified diff against the submitted revision (map #2).
+ * Pure algorithms, no IO.
+ */
+
+export type DiffOpType = "ctx" | "del" | "add";
+
+export interface DiffOp<T = string> {
+  t: DiffOpType;
+  /** Present for ctx and del. */
+  a?: T;
+  /** Present for ctx and add. */
+  b?: 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]!);
+    }
+  }
+  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++;
+    } else {
+      out.push({ t: "add", b: b[j] });
+      j++;
+    }
+  }
+  while (i < n) out.push({ t: "del", a: a[i++] });
+  while (j < m) out.push({ t: "add", b: b[j++] });
+  return out;
+}
+
+export interface UnifiedLine {
+  t: DiffOpType | "hunk";
+  text: string;
+}
+
+/**
+ * Unified diff with hunk headers. Returns null when the inputs are equal -
+ * "no diff" is a distinct state from "empty diff".
+ */
+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 (o.t !== "add") ol++;
+    if (o.t !== "del") nl++;
+    return r;
+  });
+  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;
+    }
+  });
+  const hunks: { rows: (typeof rows)[number][] }[] = [];
+  let cur: { rows: (typeof rows)[number][] } | null = null;
+  rows.forEach((r, idx) => {
+    if (!keep[idx]) {
+      cur = null;
+      return;
+    }
+    if (!cur) {
+      cur = { rows: [] };
+      hunks.push(cur);
+    }
+    cur.rows.push(r);
+  });
+  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 });
+    }
+  }
+  return out;
+}
+
+/** 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");
+}
+
+export interface EditStats {
+  added: number;
+  removed: number;
+}
+
+export function editStats(oldText: string, newText: string): EditStats {
+  const d = unifiedDiff(oldText, newText, 0);
+  if (!d) return { added: 0, removed: 0 };
+  return {
+    added: d.filter((r) => r.t === "add").length,
+    removed: d.filter((r) => r.t === "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));
+}

package/src/feedback.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import { renderFeedback } from "./feedback";
+import type { Annotation } from "./types";
+
+const PLAN = `# Plan
+
+## Context
+
+Review sessions live only in daemon memory today.
+
+## Storage
+
+Sessions are written as one JSON document per session.
+`;
+
+function ann(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): Annotation {
+  return {
+    id: "a1",
+    kind: "comment",
+    body: "Please clarify.",
+    createdAt: "2026-08-07T00:00:00.000Z",
+    ...partial,
+  };
+}
+
+describe("renderFeedback", () => {
+  test("plan edits section carries the one unified diff, directive framing first", () => {
+    const out = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "Tighten the storage section.",
+      artifactContent: PLAN,
+      workingCopy: PLAN.replace("one JSON document", "one JSON record"),
+      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.");
+  });
+
+  test("annotations are located by quote and section", () => {
+    const out = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        ann({
+          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.");
+  });
+
+  test("suggestions render as replace/with pairs", () => {
+    const out = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        ann({
+          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");
+  });
+
+  test("orphaned anchors are flagged, never dropped", () => {
+    const out = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [ann({ 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");
+  });
+
+  test("empty review says so explicitly", () => {
+    const out = renderFeedback({
+      verdictKind: "approve",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [],
+    });
+    expect(out).toContain("_No edits or annotations._");
+  });
+
+  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({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: PLAN,
+      workingCopy: working,
+      annotations: [
+        ann({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } }),
+      ],
+    });
+    expect(out).toContain("(§ Persistence)");
+  });
+});

package/src/feedback.ts

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+
+import type { Annotation, ReviewSession, VerdictKind } from "./types";
+import { parseBlocks, sectionOf } from "./markdown";
+import { resolveAnchor } from "./anchor";
+import { unifiedDiffText } from "./diff";
+
+export interface FeedbackInput {
+  verdictKind: VerdictKind;
+  summary: string;
+  /** The submitted artifact content (latest revision). */
+  artifactContent: string;
+  /** The reviewer's working copy; undefined = no direct edits. */
+  workingCopy?: string;
+  annotations: Annotation[];
+  /** Path the agent knows the plan by, for direct reference. */
+  planPath?: string;
+}
+
+const quoteLines = (s: string) => "> " + s.replace(/\n/g, "\n> ");
+
+export function renderFeedback(input: FeedbackInput): string {
+  const path = input.planPath ?? "plan.md";
+  const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
+  const lines: string[] = [];
+  lines.push("# Review: " + input.verdictKind.replace("_", " "));
+  lines.push("");
+  if (input.summary.trim()) {
+    lines.push(input.summary.trim());
+    lines.push("");
+  }
+
+  const diff =
+    input.workingCopy !== undefined ? unifiedDiffText(input.artifactContent, input.workingCopy, path) : null;
+  if (diff) {
+    lines.push("## Plan edits");
+    lines.push("");
+    lines.push(`The reviewer edited ${path} directly. Apply this exact diff first;`);
+    lines.push("it is a unified diff against the version you submitted.");
+    lines.push("");
+    lines.push("```diff");
+    lines.push(diff);
+    lines.push("```");
+    lines.push("");
+  }
+
+  if (input.annotations.length) {
+    lines.push(`## Annotations (${input.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}`);
+        lines.push("");
+        lines.push("Replace:");
+        lines.push(quoteLines(a.anchor.quote));
+        lines.push("With:");
+        lines.push(quoteLines(a.body));
+      } else {
+        lines.push(`### ${i + 1}. ${capitalize(a.kind)}${loc}${flag}`);
+        lines.push("");
+        lines.push(quoteLines(a.anchor.quote));
+        lines.push("");
+        lines.push(a.body);
+      }
+      lines.push("");
+    });
+  }
+
+  if (!diff && !input.annotations.length) {
+    lines.push("_No edits or annotations._");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export function feedbackForSession(session: ReviewSession, verdictKind: VerdictKind, summary: string): string {
+  return renderFeedback({
+    verdictKind,
+    summary,
+    artifactContent: session.artifact.content,
+    workingCopy: session.workingCopy,
+    annotations: session.annotations,
+    planPath: session.artifact.meta.planPath,
+  });
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./markdown";
+export * from "./diff";
+export * from "./anchor";
+export * from "./feedback";

package/src/markdown.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { parseBlocks, blockToMd, sectionOf } from "./markdown";
+
+const SAMPLE = `# Title
+
+## Context
+
+A paragraph that
+spans two lines.
+
+- first item
+- second item
+
+\`\`\`ts
+const x = 1;
+const y = 2;
+\`\`\`
+
+## Steps
+
+1. do one
+2. do two
+
+> a quoted
+> aside
+
+---
+`;
+
+describe("parseBlocks", () => {
+  test("parses every block kind with source line ranges", () => {
+    const blocks = parseBlocks(SAMPLE);
+    expect(blocks.map((b) => b.kind)).toEqual([
+      "h1",
+      "h2",
+      "p",
+      "li",
+      "li",
+      "code",
+      "h2",
+      "oli",
+      "oli",
+      "quote",
+      "hr",
+    ]);
+    const code = blocks.find((b) => b.kind === "code")!;
+    expect(code.lang).toBe("ts");
+    expect(code.text).toBe("const x = 1;\nconst y = 2;");
+    // fence lines included in the source range
+    expect(code.lineEnd - code.lineStart).toBe(3);
+  });
+
+  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);
+  });
+
+  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);
+      }
+    }
+  });
+
+  test("round-trips through blockToMd", () => {
+    const blocks = parseBlocks(SAMPLE);
+    let oli = 0;
+    const rebuilt = blocks
+      .map((b) => {
+        oli = b.kind === "oli" ? oli + 1 : 0;
+        return blockToMd(b, oli || 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]));
+  });
+
+  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 |");
+  });
+});
+
+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");
+  });
+});

package/src/markdown.ts

@@ -0,0 +1,131 @@
+/**
+ * Markdown block model (map #22): parse source into addressable blocks that
+ * record their source line ranges. Rendered→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.
+ */
+
+export type BlockKind = "h1" | "h2" | "h3" | "p" | "li" | "oli" | "quote" | "code" | "hr";
+
+export interface Block {
+  kind: BlockKind;
+  /** Content with markers stripped; code blocks keep inner lines verbatim. */
+  text: string;
+  /** For code blocks: the fence info string ("ts", "diff", ...). */
+  lang?: string;
+  /** 0-based inclusive line range in the source this block occupies. */
+  lineStart: number;
+  lineEnd: number;
+}
+
+function isMarkerLine(l: string): boolean {
+  return (
+    l.startsWith("```") ||
+    l.startsWith("# ") ||
+    l.startsWith("## ") ||
+    l.startsWith("### ") ||
+    l.startsWith("> ") ||
+    /^- /.test(l) ||
+    /^\d+\. /.test(l) ||
+    /^(---|\*\*\*|___)\s*$/.test(l)
+  );
+}
+
+export function parseBlocks(md: string): Block[] {
+  const lines = md.split("\n");
+  const blocks: Block[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const l = lines[i]!;
+    if (l.trim() === "") {
+      i++;
+      continue;
+    }
+    if (l.startsWith("```")) {
+      const start = i;
+      const lang = l.slice(3).trim() || undefined;
+      i++;
+      const body: string[] = [];
+      while (i < lines.length && !lines[i]!.startsWith("```")) {
+        body.push(lines[i]!);
+        i++;
+      }
+      const end = Math.min(i, lines.length - 1);
+      i++;
+      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;
+      const body: string[] = [];
+      while (i < lines.length && lines[i]!.startsWith("> ")) {
+        body.push(lines[i]!.slice(2));
+        i++;
+      }
+      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++;
+    } else {
+      const start = i;
+      const body: string[] = [];
+      while (i < lines.length && lines[i]!.trim() !== "" && !isMarkerLine(lines[i]!)) {
+        body.push(lines[i]!);
+        i++;
+      }
+      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: i - 1 });
+    }
+  }
+  return blocks;
+}
+
+/** Serialize one block back to its markdown chunk. */
+export function blockToMd(b: Block, ordinal = 1): string {
+  switch (b.kind) {
+    case "h1":
+      return "# " + b.text;
+    case "h2":
+      return "## " + b.text;
+    case "h3":
+      return "### " + b.text;
+    case "li":
+      return "- " + b.text;
+    case "oli":
+      return `${ordinal}. ` + b.text;
+    case "quote":
+      return b.text
+        .split("\n")
+        .map((l) => "> " + l)
+        .join("\n");
+    case "code":
+      return "```" + (b.lang ?? "") + "\n" + b.text + "\n```";
+    case "hr":
+      return "---";
+    default:
+      return b.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;
+  }
+  return sec;
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+
+export const SCHEMA_VERSION = "1";
+
+/** A workspace is a repo/branch context holding review sessions. */
+export interface WorkspaceKey {
+  repoRoot: string;
+  branch: string;
+}
+
+export type ArtifactType = "plan" | "diff";
+
+export interface ArtifactMeta {
+  cwd?: string;
+  agent?: string;
+  /** Agent-native session id, for resume/fork context. */
+  agentSessionId?: string;
+  /** Path to the plan file on disk, so feedback can reference it. */
+  planPath?: string;
+  /** Pull request reference the diff came from, so the verdict can be posted back. */
+  pr?: string;
+  title?: string;
+}
+
+export interface Artifact {
+  type: ArtifactType;
+  /** Markdown source for plans; unified-diff text for diffs. */
+  content: string;
+  meta: ArtifactMeta;
+}
+
+/**
+ * Anchors are quote-primary selectors (Hypothesis-style), resolved against
+ * the artifact's current text by the cascade in anchor.ts. Position fields
+ * are hints, never authority.
+ */
+export interface Anchor {
+  quote: string;
+  prefix: string;
+  suffix: string;
+  /** Index of the block the anchor was made in (hint). */
+  blockIndex?: number;
+  /** Character offsets within that block's text (hint). */
+  start?: number;
+  end?: number;
+}
+
+/** The annotation kind set is open (map #2); these are the built-ins. */
+export type AnnotationKind = "comment" | "suggestion" | (string & {});
+
+export interface Annotation {
+  id: string;
+  kind: AnnotationKind;
+  anchor: Anchor;
+  /** Comment body, or the replacement text for suggestions. */
+  body: string;
+  /** Set by resolution when the quote can no longer be found. */
+  orphan?: boolean;
+  createdAt: string;
+}
+
+export type VerdictKind = "comment" | "approve" | "request_changes";
+
+export interface Verdict {
+  kind: VerdictKind;
+  summary: string;
+  /** The one structured feedback document sent to the agent. */
+  feedback: string;
+  resolvedAt: string;
+}
+
+export interface Revision {
+  revision: number;
+  content: string;
+  submittedAt: string;
+}
+
+export type SessionStatus = "pending" | "resolved";
+
+export interface ReviewSession {
+  schemaVersion: string;
+  id: string;
+  workspace: WorkspaceKey;
+  artifact: Artifact;
+  /** Revision history; artifact.content always equals the latest revision. */
+  revisions: Revision[];
+  annotations: Annotation[];
+  /**
+   * The reviewer's working copy of the artifact source (plan edits).
+   * Serializes as ONE unified diff against the submitted revision.
+   * Undefined = no direct edits.
+   */
+  workingCopy?: string;
+  verdict: Verdict | null;
+  status: SessionStatus;
+  createdAt: string;
+}
+
+/** comment and request_changes both map to deny in agent-native contracts. */
+export function verdictAllows(kind: VerdictKind): boolean {
+  return kind === "approve";
+}