@cueloop/schema 0.1.0-alpha.77 → 0.1.0-alpha.79

package/package.json

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

package/src/anchor.test.ts

@@ -320,3 +320,75 @@ so a crash can never leave a torn file on disk.
     expect(resolved?.endBlockIndex).toBe(secondBullet - 1);
   });
 });
+
+describe("fuzzy work budget", () => {
+  function largePlan(paragraphs: number): string {
+    const lines = ["# Plan", ""];
+
+    for (let index = 0; index < paragraphs; index++) {
+      lines.push(
+        `This is paragraph number ${index} describing the migration of the session store and its atomic write path in enough prose to be a realistic block a reviewer might quote.`,
+        "",
+      );
+    }
+
+    return lines.join("\n");
+  }
+
+  test("a stale anchor over a large plan stays bounded across all its blocks", () => {
+    // Arrange - a 160-block plan whose quoted paragraph was edited so the exact text is gone,
+    // forcing the fuzzy tier over every block; a per-block budget would freeze for many seconds
+    const blocks = parseBlocks(largePlan(160));
+    const quoted = Math.floor(blocks.length / 2);
+    const anchor = makeAnchor(blocks, quoted, 0, Math.min(blocks[quoted]!.text.length, 140));
+    const edited = blocks.map((block) => ({
+      ...block,
+      text: block.text.replaceAll("migration", "rollout").replaceAll("session", "record"),
+    }));
+
+    // Act
+    const started = Date.now();
+    const resolved = resolveAnchor(anchor, edited);
+    const elapsed = Date.now() - started;
+
+    // Assert - it rebinds via the fuzzy tier, and one shared budget keeps it far under a freeze
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  test("still binds when a distinctive quote moved down a few blocks and was edited", () => {
+    // Arrange - a distinctive quote among unrelated blocks; the agent inserts paragraphs above it
+    // (shifting it down) and edits one word, so exact/normalized miss and the outward scan must
+    // reach the shifted block before the shared budget runs out
+    const original =
+      "The canonical migration store commits every session write atomically along one path.";
+    const plan = (target: string): string => {
+      const lines = ["# Plan", ""];
+
+      for (let index = 0; index < 40; index++) {
+        lines.push(
+          index === 20
+            ? target
+            : `Filler paragraph ${index} covers an unrelated topic in its own words.`,
+          "",
+        );
+      }
+
+      return lines.join("\n");
+    };
+    const before = parseBlocks(plan(original));
+    const quoted = before.findIndex((block) => block.text === original);
+    const anchor = makeAnchor(before, quoted, 0, original.length);
+    const edited = original.replace("atomically", "carefully");
+    const shifted = parseBlocks(
+      plan(edited).replace("# Plan\n", "# Plan\n\nInserted A.\n\nInserted B.\n\nInserted C.\n"),
+    );
+
+    // Act
+    const resolved = resolveAnchor(anchor, shifted);
+
+    // Assert - rebinds via fuzzy onto the shifted block, not orphaned or bound to a neighbour
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(shifted[resolved!.blockIndex]!.text).toBe(edited);
+  });
+});

package/src/anchor.ts

@@ -18,7 +18,7 @@
 
 import type { Anchor } from "./types";
 import { type Block, stripLeadingBlockMarker } from "./markdown";
-import { fuzzyFindBestMatch } from "./fuzzy";
+import { fuzzyFindBestMatch, newFuzzyBudget } from "./fuzzy";
 
 /** Characters of surrounding text captured as prefix/suffix selectors. */
 const ANCHOR_CONTEXT_CHARS = 24;
@@ -139,7 +139,26 @@ function findExactCandidates(anchor: Anchor, blocks: Block[], quote: string): Ca
  */
 const FUZZY_CONTEXT_TIE_BREAK = 0.01;
 
-/** The best fuzzy window per block, ranked by similarity with context as a tiebreak. */
+/** Block indices to scan, spiralling out from the anchor's hinted block: hint, hint+1, hint-1, ... */
+function blockScanOrder(hint: number | undefined, count: number): number[] {
+  if (count <= 0) return [];
+  const first = Number.isInteger(hint) ? Math.min(Math.max(hint!, 0), count - 1) : 0;
+  const order = [first];
+
+  for (const step of Array.from({ length: count - 1 }, (_unused, index) => index + 1)) {
+    if (first + step < count) order.push(first + step);
+    if (first - step >= 0) order.push(first - step);
+  }
+
+  return order;
+}
+
+/**
+ * The best fuzzy window per block, ranked by similarity with context as a tiebreak. One work budget
+ * is shared across every block scan, so a stale anchor costs a single budget total, not one per
+ * block. Blocks are scanned outward from the anchor's hint, so a quote nudged a few blocks by an
+ * edit is reached before the budget runs out; a passage that moved far or is truly gone orphans.
+ */
 function findFuzzyCandidates(
   anchor: Anchor,
   blocks: Block[],
@@ -147,17 +166,21 @@ function findFuzzyCandidates(
   minimumSimilarity: number,
 ): Candidate[] {
   const candidates: Candidate[] = [];
+  const budget = newFuzzyBudget();
 
-  blocks.forEach((block, blockIndex) => {
-    const match = fuzzyFindBestMatch(needle, block.text, minimumSimilarity);
+  for (const blockIndex of blockScanOrder(anchor.blockIndex, blocks.length)) {
+    const block = blocks[blockIndex]!;
+    const match = fuzzyFindBestMatch(needle, block.text, minimumSimilarity, budget);
 
-    if (match === null) return;
-    const score =
-      match.similarity +
-      contextScore(anchor, blockIndex, block, match.start, match.end) * FUZZY_CONTEXT_TIE_BREAK;
+    if (match !== null) {
+      const score =
+        match.similarity +
+        contextScore(anchor, blockIndex, block, match.start, match.end) * FUZZY_CONTEXT_TIE_BREAK;
 
-    candidates.push({ blockIndex, start: match.start, end: match.end, score });
-  });
+      candidates.push({ blockIndex, start: match.start, end: match.end, score });
+    }
+    if (budget.remaining <= 0) break;
+  }
 
   return candidates;
 }

package/src/fuzzy.ts

@@ -63,25 +63,43 @@ export function similarityRatio(left: string, right: string): number {
 }
 
 /**
- * Character comparisons this scan may spend before it gives up and returns the
- * best window found so far (or null). The scan is O(haystack * needle^3) - a
+ * Character comparisons a fuzzy search may spend before it gives up and returns
+ * the best window found so far (or null). The scan is O(haystack * needle^3) - a
  * long quote fuzzed over a long document (a stale multi-block anchor whose text
  * is gone) would otherwise pin the CPU for a minute; a passage that is truly gone
  * is better left orphaned than fuzzed. Small everyday quotes never approach it.
  */
 const FUZZY_WORK_BUDGET = 150_000_000;
 
+/**
+ * A mutable work allowance shared across a group of fuzzy searches. Resolving one
+ * anchor scans every block, so a per-call cap would still let a stale multi-block
+ * anchor spend budget x blocks; sharing one budget across those scans bounds the
+ * whole anchor to a single budget, not one per block.
+ */
+export interface FuzzyBudget {
+  remaining: number;
+}
+
+/** A fresh work allowance for one anchor's fuzzy search across its blocks. */
+export function newFuzzyBudget(): FuzzyBudget {
+  return { remaining: FUZZY_WORK_BUDGET };
+}
+
 /**
  * Find the haystack window most similar to the needle, or null when nothing
  * clears `minimumSimilarity`. Windows range around the needle length so the
  * match tolerates a few inserted or deleted characters, not only substitutions.
  * Ties keep the earliest window. Offsets index the haystack directly. The scan
- * stops once it has spent `FUZZY_WORK_BUDGET`, returning the best window so far.
+ * spends from `budget` (its own single-budget allowance by default) and stops
+ * once the budget is exhausted, returning the best window so far - so a caller
+ * scanning many blocks can pass one budget to bound them together.
  */
 export function fuzzyFindBestMatch(
   needle: string,
   haystack: string,
   minimumSimilarity: number,
+  budget: FuzzyBudget = newFuzzyBudget(),
 ): FuzzyMatch | null {
   if (needle === "" || haystack === "") return null;
 
@@ -90,7 +108,6 @@ export function fuzzyFindBestMatch(
   const maximumWindowLength = needle.length + lengthTolerance;
 
   let bestMatch: FuzzyMatch | null = null;
-  let remainingWork = FUZZY_WORK_BUDGET;
 
   for (let start = 0; start < haystack.length; start++) {
     for (
@@ -98,9 +115,9 @@ export function fuzzyFindBestMatch(
       windowLength <= maximumWindowLength && start + windowLength <= haystack.length;
       windowLength++
     ) {
-      // each window costs a needle x window edit-distance pass; spend that from the budget
-      remainingWork -= needle.length * windowLength;
-      if (remainingWork <= 0) return bestMatch;
+      // each window costs a needle x window edit-distance pass; spend that from the shared budget
+      budget.remaining -= needle.length * windowLength;
+      if (budget.remaining <= 0) return bestMatch;
       const window = haystack.slice(start, start + windowLength);
       const similarity = similarityRatio(needle, window);
 

package/src/history.ts

@@ -1,5 +1,5 @@
 /**
- * A review session's history as an append-only tree of entries. Each entry
+ * A thread's history as an append-only tree of entries. Each entry
  * points at its parent; a branch is a named tip; the active path is the chain
  * from the current branch's tip back to the root. Nothing is ever deleted:
  * navigating moves a tip, a comment removal is its own entry, a fork copies a

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./types";
 export * from "./participants";
 export * from "./share-access";
+export * from "./share-links";
 export * from "./markdown";
 export * from "./inline";
 export * from "./working-copy";

package/src/markdown.test.ts

@@ -102,13 +102,74 @@ describe("parseBlocks", () => {
 
   test("unknown constructs degrade to paragraphs, no content lost", () => {
     // Arrange
-    const md = "| a | b |\n|---|---|\n| 1 | 2 |";
+    const md = "<div>raw html</div>";
 
     // Act
     const blocks = parseBlocks(md);
 
     // Assert
-    expect(blocks.map((block) => block.text).join("\n")).toContain("| a | b |");
+    expect(blocks.map((block) => block.kind)).toEqual(["p"]);
+    expect(blocks[0]!.text).toBe("<div>raw html</div>");
+  });
+
+  test("a GFM table parses to one table block that keeps its source verbatim", () => {
+    // Arrange
+    const md = "before\n\n| a | b |\n|---|---|\n| 1 | 2 |\n| 3 | 4 |\n\nafter";
+
+    // Act
+    const blocks = parseBlocks(md);
+
+    // Assert
+    expect(blocks.map((block) => block.kind)).toEqual(["p", "table", "p"]);
+    const table = blocks.find((block) => block.kind === "table")!;
+
+    expect(table.text).toBe("| a | b |\n|---|---|\n| 1 | 2 |\n| 3 | 4 |");
+  });
+
+  test("a single-column table and an aligned delimiter still parse as a table", () => {
+    // Assert
+    expect(parseBlocks("| only |\n| --- |\n| one |")[0]!.kind).toBe("table");
+    expect(parseBlocks("| l | r |\n| :--- | ---: |\n| a | b |")[0]!.kind).toBe("table");
+  });
+
+  test("a plain rule line is an hr, never a table", () => {
+    // Assert
+    expect(parseBlocks("above\n\n---\n\nbelow").map((block) => block.kind)).toEqual([
+      "p",
+      "hr",
+      "p",
+    ]);
+  });
+
+  test("leading frontmatter parses to a frontmatter block, closed by its fence", () => {
+    // Arrange
+    const md = "---\ntitle: Plan\nowner: me\n---\n\n# Heading\n";
+
+    // Act
+    const blocks = parseBlocks(md);
+
+    // Assert
+    expect(blocks.map((block) => block.kind)).toEqual(["frontmatter", "h1"]);
+    expect(blocks[0]!.text).toBe("title: Plan\nowner: me");
+  });
+
+  test("a leading fence with no closing fence stays an hr, not frontmatter", () => {
+    // Assert
+    expect(parseBlocks("---\njust a paragraph\n").map((block) => block.kind)).toEqual(["hr", "p"]);
+  });
+
+  test("table and frontmatter round-trip through blockToMd", () => {
+    // Arrange
+    const md = "---\ntitle: Plan\n---\n\n| a | b |\n|---|---|\n| 1 | 2 |";
+    const blocks = parseBlocks(md);
+
+    // Act
+    const rebuilt = blocks.map((block) => blockToMd(block)).join("\n\n");
+
+    // Assert
+    expect(parseBlocks(rebuilt).map((block) => [block.kind, block.text])).toEqual(
+      blocks.map((block) => [block.kind, block.text]),
+    );
   });
 });
 

package/src/markdown.ts

@@ -6,11 +6,22 @@
  * so no content is ever lost.
  */
 
-export type BlockKind = "h1" | "h2" | "h3" | "p" | "li" | "oli" | "quote" | "code" | "hr";
+export type BlockKind =
+  | "h1"
+  | "h2"
+  | "h3"
+  | "p"
+  | "li"
+  | "oli"
+  | "quote"
+  | "code"
+  | "hr"
+  | "table"
+  | "frontmatter";
 
 export interface Block {
   kind: BlockKind;
-  /** Content with markers stripped; code blocks keep inner lines verbatim. */
+  /** Content with markers stripped; code, table, and frontmatter blocks keep inner lines verbatim. */
   text: string;
   /** For code blocks: the fence info string ("ts", "diff", ...). */
   lang?: string;
@@ -31,110 +42,193 @@ export function stripLeadingBlockMarker(line: string): string {
   return line.replace(LEADING_BLOCK_MARKER, "");
 }
 
+/** A GFM table delimiter row: one or more dash cells split by pipes, each optionally `:`-aligned. */
+function isTableDelimiterRow(line: string): boolean {
+  if (!line.includes("|")) return false;
+  const cells = line
+    .trim()
+    .replace(/^\||\|$/g, "")
+    .split("|");
+
+  return cells.length >= 1 && cells.every((cell) => /^\s*:?-+:?\s*$/.test(cell));
+}
+
+/** A GFM table opens on a header row of pipe cells whose next line is a delimiter row. */
+function isTableStart(lines: string[], index: number): boolean {
+  const header = lines[index];
+  const delimiter = lines[index + 1];
+
+  return (
+    header !== undefined &&
+    header.includes("|") &&
+    delimiter !== undefined &&
+    isTableDelimiterRow(delimiter)
+  );
+}
+
 function isMarkerLine(line: string): boolean {
   return (
     line.startsWith("```") || LEADING_BLOCK_MARKER.test(line) || /^(---|\*\*\*|___)\s*$/.test(line)
   );
 }
 
+/**
+ * Leading YAML frontmatter: a --- fence on the very first line, closed by a
+ * second --- fence. Null when there is no leading fence or no closing fence -
+ * a lone leading --- then falls through to an hr.
+ */
+function frontmatterBlock(lines: string[]): Block | null {
+  if (lines[0]?.trim() !== "---") return null;
+  let close = 1;
+
+  while (close < lines.length && lines[close]!.trim() !== "---") close++;
+  if (close >= lines.length) return null;
+
+  return {
+    kind: "frontmatter",
+    text: lines.slice(1, close).join("\n"),
+    lineStart: 0,
+    lineEnd: close,
+  };
+}
+
+/** A block consumed from a line span, with the next line to resume parsing at. */
+interface BlockScan {
+  block: Block;
+  next: number;
+}
+
+/** A one-line block - a heading, a rule, a bullet, or an ordered item - at `lineIndex`, or null. */
+function singleLineBlock(line: string, lineIndex: number): Block | null {
+  const marked = (kind: BlockKind): Block => ({
+    kind,
+    text: stripLeadingBlockMarker(line),
+    lineStart: lineIndex,
+    lineEnd: lineIndex,
+  });
+
+  if (line.startsWith("### ")) return marked("h3");
+  if (line.startsWith("## ")) return marked("h2");
+  if (line.startsWith("# ")) return marked("h1");
+  if (/^(---|\*\*\*|___)\s*$/.test(line)) {
+    return { kind: "hr", text: "", lineStart: lineIndex, lineEnd: lineIndex };
+  }
+  if (line.startsWith("- ")) return marked("li");
+  if (/^\d+\. /.test(line)) return marked("oli");
+
+  return null;
+}
+
+/** Consume a fenced code block from its opening ``` at `start`. */
+function codeBlock(lines: string[], start: number): BlockScan {
+  const lang = lines[start]!.slice(3).trim() || undefined;
+  let index = start + 1;
+  const body: string[] = [];
+
+  while (index < lines.length && !lines[index]!.startsWith("```")) {
+    body.push(lines[index]!);
+    index++;
+  }
+  const end = Math.min(index, lines.length - 1);
+
+  return {
+    block: { kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end },
+    next: index + 1,
+  };
+}
+
+/** Consume a blockquote's consecutive `> ` lines from `start`. */
+function quoteBlock(lines: string[], start: number): BlockScan {
+  let index = start;
+  const body: string[] = [];
+
+  while (index < lines.length && lines[index]!.startsWith("> ")) {
+    body.push(stripLeadingBlockMarker(lines[index]!));
+    index++;
+  }
+
+  return {
+    block: { kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: index - 1 },
+    next: index,
+  };
+}
+
+/** Consume a GFM table (header, delimiter, then pipe rows) from `start`. */
+function tableBlock(lines: string[], start: number): BlockScan {
+  const body: string[] = [lines[start]!, lines[start + 1]!];
+  let index = start + 2;
+
+  // body rows run until a blank line, a fence, or a line without a pipe
+  while (
+    index < lines.length &&
+    lines[index]!.trim() !== "" &&
+    lines[index]!.includes("|") &&
+    !lines[index]!.startsWith("```")
+  ) {
+    body.push(lines[index]!);
+    index++;
+  }
+
+  return {
+    block: { kind: "table", text: body.join("\n"), lineStart: start, lineEnd: index - 1 },
+    next: index,
+  };
+}
+
+/** Consume a paragraph: consecutive prose lines until a blank line, a marker, or a table. */
+function paragraphBlock(lines: string[], start: number): BlockScan {
+  let index = start;
+  const body: string[] = [];
+
+  while (
+    index < lines.length &&
+    lines[index]!.trim() !== "" &&
+    !isMarkerLine(lines[index]!) &&
+    !isTableStart(lines, index)
+  ) {
+    body.push(lines[index]!);
+    index++;
+  }
+
+  return {
+    block: { kind: "p", text: body.join("\n"), lineStart: start, lineEnd: index - 1 },
+    next: index,
+  };
+}
+
+/** The next block starting at `lineIndex` (never a blank line, never frontmatter). */
+function nextBlock(lines: string[], lineIndex: number): BlockScan {
+  const line = lines[lineIndex]!;
+
+  if (line.startsWith("```")) return codeBlock(lines, lineIndex);
+  const single = singleLineBlock(line, lineIndex);
+
+  if (single) return { block: single, next: lineIndex + 1 };
+  if (line.startsWith("> ")) return quoteBlock(lines, lineIndex);
+  if (isTableStart(lines, lineIndex)) return tableBlock(lines, lineIndex);
+
+  return paragraphBlock(lines, lineIndex);
+}
+
 export function parseBlocks(markdown: string): Block[] {
   const lines = markdown.split("\n");
   const blocks: Block[] = [];
   let lineIndex = 0;
+  const frontmatter = frontmatterBlock(lines);
 
+  if (frontmatter) {
+    blocks.push(frontmatter);
+    lineIndex = frontmatter.lineEnd + 1;
+  }
   while (lineIndex < lines.length) {
-    const line = lines[lineIndex]!;
-
-    if (line.trim() === "") {
+    if (lines[lineIndex]!.trim() === "") {
       lineIndex++;
       continue;
     }
-    if (line.startsWith("```")) {
-      const start = lineIndex;
-      const lang = line.slice(3).trim() || undefined;
-
-      lineIndex++;
-      const body: string[] = [];
-
-      while (lineIndex < lines.length && !lines[lineIndex]!.startsWith("```")) {
-        body.push(lines[lineIndex]!);
-        lineIndex++;
-      }
-      const end = Math.min(lineIndex, lines.length - 1);
+    const scan = nextBlock(lines, lineIndex);
 
-      lineIndex++;
-      blocks.push({ kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end });
-    } 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 (lineIndex < lines.length && lines[lineIndex]!.startsWith("> ")) {
-        body.push(stripLeadingBlockMarker(lines[lineIndex]!));
-        lineIndex++;
-      }
-      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 = lineIndex;
-      const body: string[] = [];
-
-      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: lineIndex - 1 });
-    }
+    blocks.push(scan.block);
+    lineIndex = scan.next;
   }
 
   return blocks;
@@ -162,6 +256,10 @@ export function blockToMd(block: Block, ordinal = 1): string {
       return "```" + (block.lang ?? "") + "\n" + block.text + "\n```";
     case "hr":
       return "---";
+    case "frontmatter":
+      return "---\n" + block.text + "\n---";
+    case "table":
+      return block.text;
     default:
       return block.text;
   }

package/src/participants.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { registerParticipant } from "./participants";
+import { registerParticipant, registeredGithubLogin } from "./participants";
 import { SCHEMA_VERSION, type Thread } from "./types";
 
 function emptySession(): Thread {
@@ -85,3 +85,21 @@ describe("registerParticipant", () => {
     ]);
   });
 });
+
+describe("registeredGithubLogin", () => {
+  test("returns the handle a fingerprint verified on a past visit", () => {
+    const session = registerParticipant(emptySession(), "SHA256:ana", "Ana", {
+      provider: "github",
+      handle: "ana-gh",
+    });
+
+    expect(registeredGithubLogin(session, "SHA256:ana")).toBe("ana-gh");
+  });
+
+  test("returns undefined for an ssh-only or unknown participant", () => {
+    const session = registerParticipant(emptySession(), "SHA256:ana", "Ana");
+
+    expect(registeredGithubLogin(session, "SHA256:ana")).toBeUndefined();
+    expect(registeredGithubLogin(session, "SHA256:unknown")).toBeUndefined();
+  });
+});

package/src/participants.ts

@@ -18,6 +18,12 @@ export interface ParticipantSource {
   handle?: string;
 }
 
+export function registeredGithubLogin(session: Thread, author: string): string | undefined {
+  const existing = (session.participants ?? []).find((participant) => participant.id === author);
+
+  return existing?.provider === "github" ? existing.handle : undefined;
+}
+
 export function registerParticipant(
   session: Thread,
   author: string,

package/src/share-links.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { SCHEMA_VERSION, type Thread } from "./types";
+import { threadShareLinks, withShareLinks } from "./share-links";
+
+function thread(overrides: Partial<Thread> = {}): Thread {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00.000Z" }],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("share-link migration", () => {
+  test("a never-shared thread has no links", () => {
+    expect(threadShareLinks(thread())).toBeUndefined();
+    expect(withShareLinks(thread()).shares).toBeUndefined();
+  });
+
+  test("a legacy private share migrates into a one-element list", () => {
+    const legacy = thread({
+      shareId: "p_abc123xy",
+      access: { githubLogins: ["octocat"] },
+      owner: "SHA256:owner",
+      shareBranch: "feature",
+    });
+
+    expect(withShareLinks(legacy).shares).toEqual([
+      {
+        id: "p_abc123xy",
+        requireAuth: true,
+        allowlist: ["octocat"],
+        owner: "SHA256:owner",
+        shareBranch: "feature",
+      },
+    ]);
+  });
+
+  test("a legacy public share migrates as requireAuth false with an empty allowlist", () => {
+    const legacy = thread({ shareId: "p_public00", owner: "SHA256:owner" });
+    const [link] = withShareLinks(legacy).shares!;
+
+    expect(link).toMatchObject({ id: "p_public00", requireAuth: false, allowlist: [] });
+  });
+
+  test("a thread that already has shares is returned untouched", () => {
+    const modern = thread({
+      shares: [{ id: "p_modern00", name: "team", requireAuth: false, allowlist: [] }],
+      // stale legacy fields must not override the explicit shares
+      shareId: "p_legacy00",
+    });
+
+    expect(withShareLinks(modern).shares).toEqual([
+      { id: "p_modern00", name: "team", requireAuth: false, allowlist: [] },
+    ]);
+  });
+});

package/src/share-links.ts

@@ -0,0 +1,29 @@
+import type { ShareLink, Thread } from "./types";
+
+/**
+ * A thread's share links, migrating a legacy single share (scalar shareId +
+ * access + owner + shareBranch) into a one-element list. Undefined when the
+ * thread was never shared. Records already carrying `shares` are returned as-is.
+ */
+export function threadShareLinks(session: Thread): ShareLink[] | undefined {
+  if (session.shares !== undefined) return session.shares;
+  if (session.shareId === undefined) return undefined;
+
+  return [
+    {
+      id: session.shareId,
+      requireAuth: session.access !== undefined,
+      allowlist: session.access?.githubLogins ?? [],
+      owner: session.owner,
+      shareBranch: session.shareBranch,
+    },
+  ];
+}
+
+/** The thread with `shares` populated from the legacy fields when absent; a never-shared thread is unchanged. */
+export function withShareLinks(session: Thread): Thread {
+  if (session.shares !== undefined) return session;
+  const shares = threadShareLinks(session);
+
+  return shares ? { ...session, shares } : session;
+}

package/src/types.ts

@@ -8,7 +8,7 @@ import type { SessionHistory } from "./history";
 
 export const SCHEMA_VERSION = "1";
 
-/** A workspace is a repo/branch context holding review sessions. */
+/** A workspace is a repo/branch context holding threads. */
 export interface WorkspaceKey {
   repoRoot: string;
   branch: string;
@@ -19,7 +19,7 @@ export interface WorkspaceKey {
 }
 
 /**
- * What kind of artifact a review session holds. `plan` and `reply` are both
+ * What kind of artifact a thread holds. `plan` and `reply` are both
  * markdown documents (see isMarkdownArtifact) - a plan is a proposal written
  * forward, a reply is the agent's previous message pulled back for review.
  * `diff` is a unified-diff patch; `prototype` is a component design doc (API /
@@ -237,6 +237,27 @@ export interface ShareAccess {
   githubLogins: string[];
 }
 
+/**
+ * One published share link for a thread. A thread can have several, each an
+ * independent gateway blob keyed by its own `id`. `name` is a local-only label
+ * to tell links apart; `requireAuth` gates the link behind the `allowlist` of
+ * GitHub logins (empty + requireAuth is a private link with no one added yet).
+ */
+export interface ShareLink {
+  /** The share id (`p_…`), the link's address and gateway blob key. */
+  id: string;
+  /** A local, cosmetic label for the list; never leaves the planner's machine. */
+  name?: string;
+  /** True = private (only `allowlist` may open it); false = public. */
+  requireAuth: boolean;
+  /** GitHub logins allowed when `requireAuth`; ignored when public. */
+  allowlist: string[];
+  /** SSH fingerprint that created the link; the gateway stamps it to gate pulls/pushes/revokes. */
+  owner?: string;
+  /** The branch this link follows and shows collaborators; `main` when absent. */
+  shareBranch?: string;
+}
+
 export interface Thread {
   schemaVersion: string;
   id: string;
@@ -277,13 +298,15 @@ export interface Thread {
   shelvedAnnotations?: Annotation[];
   /** The session this one was forked from. */
   parentSessionId?: string;
-  /** Share id once published; lets the planner pull collaborator notes back. */
+  /** Published share links for this thread; each is an independent gateway blob. Migrated from the legacy scalar fields on read. */
+  shares?: ShareLink[];
+  /** @deprecated Legacy single-share id; migrated into `shares` on read. */
   shareId?: string;
-  /** The branch the share follows and shows collaborators; `main` when absent. */
+  /** @deprecated Legacy single-share branch; migrated into `shares` on read. */
   shareBranch?: string;
-  /** SSH fingerprint that created the share; the gateway stamps it to gate pulls. */
+  /** @deprecated Legacy single-share owner fingerprint; migrated into `shares` on read. */
   owner?: string;
-  /** Owner-set allowlist of GitHub logins for a private share; absent = public. */
+  /** @deprecated Legacy single-share allowlist; migrated into `shares` on read. */
   access?: ShareAccess;
   /**
    * Identities that authored annotations here, keyed by id (union-by-id, like
@@ -293,9 +316,6 @@ export interface Thread {
   participants?: Identity[];
 }
 
-/** @deprecated use Thread */
-export type ReviewSession = Thread;
-
 /** comment and request_changes both map to deny in agent-native contracts. */
 export function verdictAllows(kind: VerdictKind): boolean {
   return kind === "approve";