@cueloop/schema 0.1.0-alpha.5 → 0.1.0-alpha.50

package/src/markdown.ts

@@ -1,6 +1,6 @@
 /**
- * Markdown block model (map #22): parse source into addressable blocks that
- * record their source line ranges. Rendered→source mapping is block+line
+ * 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
  * subset cueloop plans use; unknown constructs fall back to paragraph blocks
  * so no content is ever lost.
@@ -19,113 +19,153 @@ export interface Block {
   lineEnd: number;
 }
 
-function isMarkerLine(l: string): boolean {
+/**
+ * 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
+ * anchor resolver strips exactly the same set and the two never drift.
+ */
+export const LEADING_BLOCK_MARKER = /^(?:#{1,3} |- |\d+\. |> )/;
+
+/** Remove one leading markdown block marker, or return the line unchanged. */
+export function stripLeadingBlockMarker(line: string): string {
+  return line.replace(LEADING_BLOCK_MARKER, "");
+}
+
+function isMarkerLine(line: string): boolean {
   return (
-    l.startsWith("```") ||
-    l.startsWith("# ") ||
-    l.startsWith("## ") ||
-    l.startsWith("### ") ||
-    l.startsWith("> ") ||
-    /^- /.test(l) ||
-    /^\d+\. /.test(l) ||
-    /^(---|\*\*\*|___)\s*$/.test(l)
+    line.startsWith("```") || LEADING_BLOCK_MARKER.test(line) || /^(---|\*\*\*|___)\s*$/.test(line)
   );
 }
 
-export function parseBlocks(md: string): Block[] {
-  const lines = md.split("\n");
+export function parseBlocks(markdown: string): Block[] {
+  const lines = markdown.split("\n");
   const blocks: Block[] = [];
-  let i = 0;
-  while (i < lines.length) {
-    const l = lines[i]!;
-    if (l.trim() === "") {
-      i++;
+  let lineIndex = 0;
+  while (lineIndex < lines.length) {
+    const line = lines[lineIndex]!;
+    if (line.trim() === "") {
+      lineIndex++;
       continue;
     }
-    if (l.startsWith("```")) {
-      const start = i;
-      const lang = l.slice(3).trim() || undefined;
-      i++;
+    if (line.startsWith("```")) {
+      const start = lineIndex;
+      const lang = line.slice(3).trim() || undefined;
+      lineIndex++;
       const body: string[] = [];
-      while (i < lines.length && !lines[i]!.startsWith("```")) {
-        body.push(lines[i]!);
-        i++;
+      while (lineIndex < lines.length && !lines[lineIndex]!.startsWith("```")) {
+        body.push(lines[lineIndex]!);
+        lineIndex++;
       }
-      const end = Math.min(i, lines.length - 1);
-      i++;
+      const end = Math.min(lineIndex, lines.length - 1);
+      lineIndex++;
       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;
+    } else if (line.startsWith("### ")) {
+      blocks.push({
+        kind: "h3",
+        text: stripLeadingBlockMarker(line),
+        lineStart: lineIndex,
+        lineEnd: lineIndex,
+      });
+      lineIndex++;
+    } else if (line.startsWith("## ")) {
+      blocks.push({
+        kind: "h2",
+        text: stripLeadingBlockMarker(line),
+        lineStart: lineIndex,
+        lineEnd: lineIndex,
+      });
+      lineIndex++;
+    } else if (line.startsWith("# ")) {
+      blocks.push({
+        kind: "h1",
+        text: stripLeadingBlockMarker(line),
+        lineStart: lineIndex,
+        lineEnd: lineIndex,
+      });
+      lineIndex++;
+    } else if (/^(---|\*\*\*|___)\s*$/.test(line)) {
+      blocks.push({ kind: "hr", text: "", lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("> ")) {
+      const start = lineIndex;
       const body: string[] = [];
-      while (i < lines.length && lines[i]!.startsWith("> ")) {
-        body.push(lines[i]!.slice(2));
-        i++;
+      while (lineIndex < lines.length && lines[lineIndex]!.startsWith("> ")) {
+        body.push(stripLeadingBlockMarker(lines[lineIndex]!));
+        lineIndex++;
       }
-      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++;
+      blocks.push({
+        kind: "quote",
+        text: body.join("\n"),
+        lineStart: start,
+        lineEnd: lineIndex - 1,
+      });
+    } else if (line.startsWith("- ")) {
+      blocks.push({
+        kind: "li",
+        text: stripLeadingBlockMarker(line),
+        lineStart: lineIndex,
+        lineEnd: lineIndex,
+      });
+      lineIndex++;
+    } else if (/^\d+\. /.test(line)) {
+      blocks.push({
+        kind: "oli",
+        text: stripLeadingBlockMarker(line),
+        lineStart: lineIndex,
+        lineEnd: lineIndex,
+      });
+      lineIndex++;
     } else {
-      const start = i;
+      const start = lineIndex;
       const body: string[] = [];
-      while (i < lines.length && lines[i]!.trim() !== "" && !isMarkerLine(lines[i]!)) {
-        body.push(lines[i]!);
-        i++;
+      while (
+        lineIndex < lines.length &&
+        lines[lineIndex]!.trim() !== "" &&
+        !isMarkerLine(lines[lineIndex]!)
+      ) {
+        body.push(lines[lineIndex]!);
+        lineIndex++;
       }
-      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: i - 1 });
+      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
     }
   }
   return blocks;
 }
 
 /** Serialize one block back to its markdown chunk. */
-export function blockToMd(b: Block, ordinal = 1): string {
-  switch (b.kind) {
+export function blockToMd(block: Block, ordinal = 1): string {
+  switch (block.kind) {
     case "h1":
-      return "# " + b.text;
+      return "# " + block.text;
     case "h2":
-      return "## " + b.text;
+      return "## " + block.text;
     case "h3":
-      return "### " + b.text;
+      return "### " + block.text;
     case "li":
-      return "- " + b.text;
+      return "- " + block.text;
     case "oli":
-      return `${ordinal}. ` + b.text;
+      return `${ordinal}. ` + block.text;
     case "quote":
-      return b.text
+      return block.text
         .split("\n")
-        .map((l) => "> " + l)
+        .map((line) => "> " + line)
         .join("\n");
     case "code":
-      return "```" + (b.lang ?? "") + "\n" + b.text + "\n```";
+      return "```" + (block.lang ?? "") + "\n" + block.text + "\n```";
     case "hr":
       return "---";
     default:
-      return b.text;
+      return block.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;
+  let sectionTitle = "";
+  for (let blockIndex = 0; blockIndex <= index && blockIndex < blocks.length; blockIndex++) {
+    const block = blocks[blockIndex]!;
+    if (block.kind === "h1" || block.kind === "h2" || block.kind === "h3")
+      sectionTitle = block.text;
   }
-  return sec;
+  return sectionTitle;
 }

package/src/participants.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { registerParticipant } from "./participants";
+import { SCHEMA_VERSION, type ReviewSession } from "./types";
+
+function emptySession(): ReviewSession {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+describe("registerParticipant", () => {
+  test("adds a new author with a display name", () => {
+    // Act
+    const next = registerParticipant(emptySession(), "SHA256:ana", "Ana");
+
+    // Assert
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
+  });
+
+  test("records presence without a name (renders anonymous)", () => {
+    // Act
+    const next = registerParticipant(emptySession(), "SHA256:ana");
+
+    // Assert
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh" }]);
+  });
+
+  test("a nameless revisit never erases a name a past visit set", () => {
+    // Arrange
+    const named = registerParticipant(emptySession(), "SHA256:ana", "Ana");
+
+    // Act
+    const next = registerParticipant(named, "SHA256:ana");
+
+    // Assert
+    expect(next).toBe(named);
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
+  });
+
+  test("a later name updates the existing identity in place", () => {
+    // Arrange
+    const present = registerParticipant(emptySession(), "SHA256:ana");
+
+    // Act
+    const next = registerParticipant(present, "SHA256:ana", "Ana");
+
+    // Assert
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
+  });
+});

package/src/participants.ts

@@ -0,0 +1,36 @@
+/**
+ * The participant registry: every annotation carries an `author` id, and the
+ * rail resolves that id to a display name through `session.participants`. This
+ * registers an author in that registry so a name search on "participant" or
+ * "author name" lands here.
+ */
+
+import type { Identity, ReviewSession } from "./types";
+
+/**
+ * Return the session with `author` present in the participant registry, setting
+ * the display name when one is given. A nameless call only records presence (the
+ * rail renders anonymous) and never erases a name a past visit set. Immutable:
+ * the input session is not mutated.
+ */
+export function registerParticipant(
+  session: ReviewSession,
+  author: string,
+  name?: string,
+): ReviewSession {
+  const participants = session.participants ?? [];
+  const existing = participants.find((participant) => participant.id === author);
+  const trimmed = name?.trim();
+  if (existing && !trimmed) return session;
+  const next: Identity = {
+    id: author,
+    provider: "ssh",
+    ...(trimmed ? { name: trimmed } : existing?.name ? { name: existing.name } : {}),
+  };
+  return {
+    ...session,
+    participants: existing
+      ? participants.map((participant) => (participant.id === author ? next : participant))
+      : [...participants, next],
+  };
+}

package/src/types.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { newAnnotationId, verdictAllows } from "./types";
+
+describe("verdictAllows", () => {
+  test("only approve maps to allow", () => {
+    expect(verdictAllows("approve")).toBe(true);
+    expect(verdictAllows("comment")).toBe(false);
+    expect(verdictAllows("request_changes")).toBe(false);
+  });
+});
+
+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

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * The ReviewSession primitive. 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";
@@ -12,7 +12,7 @@ export interface WorkspaceKey {
   branch: string;
 }
 
-export type ArtifactType = "plan" | "diff";
+export type ArtifactType = "plan" | "diff" | "prototype";
 
 export interface ArtifactMeta {
   cwd?: string;
@@ -21,16 +21,38 @@ export interface ArtifactMeta {
   agentSessionId?: string;
   /** Path to the plan file on disk, so feedback can reference it. */
   planPath?: string;
+  /** Path to the prototype's entry HTML file on disk. */
+  prototypePath?: string;
   /** Pull request reference the diff came from, so the verdict can be posted back. */
   pr?: string;
+  /** herdr pane the submitting agent runs in - the review returns focus there. */
+  herdrPane?: string;
   title?: string;
 }
 
+/** Full old/new contents of one changed file, keyed by its repo-relative path. */
+/** How a file changed, so curation emits the right create/delete headers. */
+export type DiffFileStatus = "added" | "modified" | "deleted";
+
+export interface DiffFileContents {
+  path: string;
+  oldContents: string;
+  newContents: string;
+  /** git's own classification - not inferred from empty contents, so an
+   *  existing-empty-file edit is a modify, not a create/delete. */
+  status: DiffFileStatus;
+}
+
 export interface Artifact {
   type: ArtifactType;
   /** Markdown source for plans; unified-diff text for diffs. */
   content: string;
   meta: ArtifactMeta;
+  /**
+   * Full file contents for a diff artifact, so hunk curation produces an
+   * exactly applyable patch; absent for legacy or partial (PR) diffs.
+   */
+  files?: DiffFileContents[];
 }
 
 /**
@@ -47,22 +69,58 @@ export interface Anchor {
   /** Character offsets within that block's text (hint). */
   start?: number;
   end?: number;
+  /** Prototype anchors: the CSS selector of the annotated element (authority). */
+  selector?: string;
 }
 
-/** The annotation kind set is open (map #2); these are the built-ins. */
-export type AnnotationKind = "comment" | "suggestion" | (string & {});
+/** The annotation kind set is open; these are the built-ins. */
+export type AnnotationKind = "comment" | (string & {});
+
+/**
+ * Agent-authored context, not reviewer feedback: the guided walk's per-file
+ * notes (kind "note", anchored by the file path). Excluded from the feedback
+ * document and the reviewer's pending counts - an agent must never receive
+ * its own notes back as items to address.
+ */
+export function isAgentNote(annotation: Pick<Annotation, "kind">): boolean {
+  return annotation.kind === "note";
+}
 
 export interface Annotation {
   id: string;
   kind: AnnotationKind;
   anchor: Anchor;
-  /** Comment body, or the replacement text for suggestions. */
+  /** Comment body. */
   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 {
@@ -81,6 +139,22 @@ export interface Revision {
 
 export type SessionStatus = "pending" | "resolved";
 
+/**
+ * A person who authored annotations on a session. `id` is the stable key an
+ * annotation's `author` points at - the SSH fingerprint today, an OAuth id
+ * ("github:…") later. Provider-agnostic so those identities slot in unchanged.
+ */
+export interface Identity {
+  /** Stable identity key; equals an annotation's `author`. */
+  id: string;
+  /** Identity source. One value today; widen the union when OAuth lands. */
+  provider: "ssh";
+  /** Display name; absent = the collaborator stayed anonymous. */
+  name?: string;
+  /** Provider handle: a github login, an email, or a short fingerprint. */
+  handle?: string;
+}
+
 export interface ReviewSession {
   schemaVersion: string;
   id: string;
@@ -95,12 +169,38 @@ export interface ReviewSession {
    * Undefined = no direct edits.
    */
   workingCopy?: string;
+  /**
+   * File paths the reviewer marked viewed during the guided walk (diff
+   * sessions). Persisting with the session means a resumed review keeps its
+   * progress. Undefined = the walk never started.
+   */
+  viewedPaths?: string[];
   verdict: Verdict | null;
   status: SessionStatus;
   createdAt: string;
+  /** Share id once published; lets the planner pull collaborator notes back. */
+  shareId?: string;
+  /** SSH fingerprint that created the share; the gateway stamps it to gate pulls. */
+  owner?: string;
+  /**
+   * Identities that authored annotations here, keyed by id (union-by-id, like
+   * annotations). The gateway records a collaborator's identity and chosen name;
+   * the rail resolves an annotation's `author` against this registry.
+   */
+  participants?: Identity[];
 }
 
 /** comment and request_changes both map to deny in agent-native contracts. */
 export function verdictAllows(kind: VerdictKind): boolean {
   return kind === "approve";
 }
+
+/**
+ * Annotation ids are minted client-side. The counter makes ids unique within
+ * a process by construction; the random suffix separates concurrent
+ * annotators in different processes on the same millisecond.
+ */
+let annotationSeq = 0;
+export function newAnnotationId(): string {
+  return `a_${Date.now().toString(36)}${(annotationSeq++).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}

package/src/working-copy.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test } from "bun:test";
+import { cutBlock, restoreBlock, restoreLine, sourceChunk } from "./working-copy";
+import { parseBlocks, type Block } from "./markdown";
+
+const BASE = `# Plan
+
+## Context
+
+A paragraph that
+spans two lines.
+
+- first item
+- second item
+
+\`\`\`ts
+const x = 1;
+const y = 2;
+\`\`\`
+`;
+
+function block(markdown: string, text: string): Block {
+  return parseBlocks(markdown).find((block) => block.text.includes(text))!;
+}
+
+describe("sourceChunk", () => {
+  test("returns the exact source lines a block occupies", () => {
+    expect(sourceChunk(BASE, block(BASE, "first item"))).toBe("- first item");
+    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe(
+      "A paragraph that\nspans two lines.",
+    );
+  });
+
+  test("code block chunk includes both fence lines", () => {
+    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe(
+      "```ts\nconst x = 1;\nconst y = 2;\n```",
+    );
+  });
+});
+
+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");
+  });
+});
+
+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
+    const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
+    expect(changed).toContain("1st item");
+  });
+});
+
+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);
+  });
+});