@cueloop/schema 0.1.0-alpha.8 → 0.1.0-alpha.81

package/src/types.ts

@@ -1,38 +1,116 @@
 /**
- * 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 Thread primitive. Everything in cueloop renders, annotates, or
+ * extends this one noun. This module is pure data shapes - no IO, no
+ * dependencies beyond the history shapes.
  */
 
+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;
+  /** Earliest root commit SHA; the project key that survives moving or re-cloning the repo. Absent for a standalone thread. */
+  rootCommit?: string;
+  /** Origin remote URL when present; for display and repair only, never the project key. */
+  remote?: string;
+}
+
+/**
+ * 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 /
+ * Composition / Callstack) in markdown, with an opt-in experimental pixel mode.
+ *
+ * One runtime union: every consumer that names the supported set - daemon
+ * wire validation, CLI flag parsing, adapter tool schemas - derives from this
+ * constant, so a new primitive extends them all without another hardcoded list.
+ */
+export const ARTIFACT_TYPES = ["plan", "diff", "prototype", "reply"] as const;
+
+export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+
+/** Harness workflows; review and refine are compositions, never artifact types. */
+export const WORKFLOW_KINDS = ["plan", "reply", "prototype", "diff", "review", "refine"] as const;
+
+export type WorkflowKind = (typeof WORKFLOW_KINDS)[number];
+
+/** Trust-boundary guard: is this string one of the artifact primitives? */
+export function isArtifactType(value: string): value is ArtifactType {
+  return ARTIFACT_TYPES.some((candidate) => candidate === value);
 }
 
-export type ArtifactType = "plan" | "diff";
+/**
+ * Markdown artifacts (plan, reply, prototype) are block-parsed and quote-anchored,
+ * so they share the plan render path, first-heading title derivation, and revision
+ * drift-assist. A prototype is a component design doc (API / Composition / Callstack)
+ * by default; its opt-in experimental pixel mode is a client render override, not a
+ * different artifact. A diff (a patch) does not - keep this the one place that names
+ * the set, so a new markdown primitive joins here once.
+ */
+export function isMarkdownArtifact(type: ArtifactType): boolean {
+  return type === "plan" || type === "reply" || type === "prototype";
+}
 
 export interface ArtifactMeta {
+  /** The workflow that submitted this artifact, distinct from its artifact type. */
+  workflow?: WorkflowKind;
   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. */
+  /** Path to the plan or reply markdown file on disk, so feedback can reference it. */
   planPath?: string;
-  /** Pull request reference the diff came from, so the verdict can be posted back. */
+  /** Path to the prototype's entry HTML file on disk. */
+  prototypePath?: string;
+  /** Pull request reference the diff came from, so the message can be posted back. */
   pr?: string;
   /** herdr pane the submitting agent runs in - the review returns focus there. */
   herdrPane?: string;
   title?: string;
+  /** A self-initiated per-repo workbench thread (a bare launch's first comment), not an agent submission. */
+  workbench?: boolean;
+  /** A frozen point-in-time capture of a workbench thread's diff, for a remote reviewer who has no working tree. */
+  snapshot?: boolean;
+}
+
+/** 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";
+
+/**
+ * One reject decision of a diff review: a whole hunk, or one change block of
+ * it when `changeIndex` is set. The daemon curates the working copy from the
+ * full set, so every client sees the same patch.
+ */
+export interface HunkRejection {
+  path: string;
+  hunkIndex: number;
+  changeIndex?: number;
+}
+
+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. */
+  /** Markdown source for plans and replies; 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[];
 }
 
 /**
@@ -44,35 +122,126 @@ export interface Anchor {
   quote: string;
   prefix: string;
   suffix: string;
-  /** Index of the block the anchor was made in (hint). */
+  /** Index of the block the anchor starts in (hint). */
   blockIndex?: number;
-  /** Character offsets within that block's text (hint). */
+  /** Last block of a quote that spans blocks (hint); absent for one block. */
+  endBlockIndex?: number;
+  /** Character offsets: `start` within the first block, `end` within the last (hint). */
   start?: number;
   end?: number;
+  /** Prototype anchors: the CSS selector of the annotated element (authority). */
+  selector?: string;
+}
+
+/** The annotation kind set is open; these are the built-ins. */
+export type AnnotationKind = "comment" | (string & {});
+
+/**
+ * The surface an annotation was made on. Name-only: the ref names the surface and the
+ * client loads that surface's text to resolve the quote anchor. Absent means the session's
+ * reviewed artifact, so every existing annotation keeps its meaning with no data change.
+ * A `file` target's `rev` doubles as the diff side: worktree for an added or context row,
+ * head for a deletion.
+ */
+export type AnnotationTarget =
+  | { kind: "artifact" }
+  | { kind: "file"; path: string; rev: "worktree" | "head" }
+  | { kind: "welcome" };
+
+/** The target an annotation resolves against; absent records mean the reviewed artifact. */
+export function annotationTarget(annotation: Pick<Annotation, "target">): AnnotationTarget {
+  return annotation.target ?? { kind: "artifact" };
 }
 
-/** The annotation kind set is open (map #2); these are the built-ins. */
-export type AnnotationKind = "comment" | "suggestion" | (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. */
+  /** The surface this note was made on; absent means the session's reviewed artifact. */
+  target?: AnnotationTarget;
+  /** 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;
+  /**
+   * The root comment this one replies to. Absent on a root. A reply shares its
+   * root's anchor, so a discussion stays one conversation when the text moves.
+   */
+  replyTo?: 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 type VerdictKind = "comment" | "approve" | "request_changes";
+export interface AnnotationResolution {
+  /** The revision number whose submission addressed this annotation. */
+  revision: number;
+  source: "agent" | "drift";
+}
 
-export interface Verdict {
-  kind: VerdictKind;
+/** An annotation a revision has addressed; it leaves the default views. */
+export function isAddressed(annotation: Annotation): boolean {
+  return annotation.resolution !== undefined;
+}
+
+/** A harness session bound to a Thread. Harness identity stays outside the Thread itself. */
+export interface HarnessBinding {
+  id: string;
+  threadId: string;
+  harness: string;
+  harnessSessionId: string;
+  createdAt: string;
+  /** Approval whose one unchanged plan resubmission this harness has consumed. */
+  approvedRetryMessageId?: string;
+}
+
+/** Durable routing state for one Message sent to one harness binding. */
+export interface Delivery {
+  id: string;
+  messageId: string;
+  bindingId: string;
+  status: "pending" | "acknowledged";
+  createdAt: string;
+  acknowledgedAt?: string;
+}
+
+/** What a harness adapter pulls: routing state plus its immutable Message payload. */
+export interface PendingDelivery {
+  delivery: Delivery;
+  message: Message;
+}
+
+export type MessageOutcome = "approved" | "changes_requested";
+
+export interface Message {
+  /** Stable identity used to deduplicate at-least-once harness delivery. */
+  id: string;
+  outcome: MessageOutcome;
   summary: string;
-  /** The one structured feedback document sent to the agent. */
-  feedback: string;
-  resolvedAt: string;
+  /** The structured review document sent to the harness. */
+  body: string;
+  sentAt: string;
 }
 
 export interface Revision {
@@ -83,7 +252,49 @@ export interface Revision {
 
 export type SessionStatus = "pending" | "resolved";
 
-export interface ReviewSession {
+/**
+ * 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: the SSH key that authored, or a verified GitHub login. */
+  provider: "ssh" | "github";
+  /** Display name; absent = the collaborator stayed anonymous. */
+  name?: string;
+  /** Provider handle: a github login, an email, or a short fingerprint. */
+  handle?: string;
+}
+
+/** Owner-set access control for a private share: only these GitHub logins may open it. Absent = a public share. */
+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;
   workspace: WorkspaceKey;
@@ -91,20 +302,66 @@ export interface ReviewSession {
   /** Revision history; artifact.content always equals the latest revision. */
   revisions: Revision[];
   annotations: Annotation[];
+  /**
+   * The session's history as a tree of entries with named branches; the
+   * artifact text and the open comments derive from the active path. Absent
+   * only on records written before histories existed; the store migrates
+   * those on read.
+   */
+  history?: SessionHistory;
+  /** A diff review's reject decisions; the working copy is the patch they leave. */
+  curation?: HunkRejection[];
   /**
    * 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;
+  /**
+   * 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[];
+  message: Message | null;
   status: SessionStatus;
   createdAt: string;
+  /**
+   * Comments off the active path - removed, or made on a segment a tip moved
+   * away from. Nothing is deleted: a navigate or switch that brings their
+   * entries back onto the path shows them again.
+   */
+  shelvedAnnotations?: Annotation[];
+  /** The session this one was forked from. */
+  parentSessionId?: string;
+  /** 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;
+  /** @deprecated Legacy single-share branch; migrated into `shares` on read. */
+  shareBranch?: string;
+  /** @deprecated Legacy single-share owner fingerprint; migrated into `shares` on read. */
+  owner?: string;
+  /** @deprecated Legacy single-share allowlist; migrated into `shares` on read. */
+  access?: ShareAccess;
+  /**
+   * 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";
+/** Whether a Message releases a harness gate. */
+export function messageAllows(outcome: MessageOutcome): boolean {
+  return outcome === "approved";
+}
+
+let messageSeq = 0;
+
+/** A process-unique, time-sortable Message id for delivery deduplication. */
+export function newMessageId(): string {
+  return `msg_${Date.now().toString(36)}${(messageSeq++).toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
 
 /**
@@ -113,6 +370,7 @@ export function verdictAllows(kind: VerdictKind): boolean {
  * 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

@@ -18,36 +18,49 @@ const y = 2;
 \`\`\`
 `;
 
-function block(md: string, text: string): Block {
-  return parseBlocks(md).find((b) => b.text.includes(text))!;
+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.");
+    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```");
+    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");
   });
@@ -55,55 +68,89 @@ describe("cutBlock", () => {
 
 describe("restoreBlock", () => {
   test("restoring the only cut returns undefined - back to pristine", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
+    // 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((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, cut, li, restoreLine(next, cut.split("\n").length));
+    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", () => {
-    const li = block(BASE, "second item");
-    const edited = cutBlock(BASE, li).replace("first item", "first item reworded");
-    const next = parseBlocks(edited).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, edited, li, restoreLine(next, edited.split("\n").length));
+    // 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", () => {
-    const p = block(BASE, "spans two lines");
-    const cut = cutBlock(BASE, p);
-    const next = parseBlocks(cut).find((b) => b.text === "first item");
-    const restored = restoreBlock(BASE, cut, p, restoreLine(next, cut.split("\n").length));
+    // 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", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
+    // 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"), li, line)).toBeUndefined();
+    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"), li, line);
+    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", () => {
-    const li = block(BASE, "first item");
-    expect(restoreLine(li, 99)).toBe(li.lineStart);
+    // Arrange
+    const listItem = block(BASE, "first item");
+
+    // Assert
+    expect(restoreLine(listItem, 99)).toBe(listItem.lineStart);
     expect(restoreLine(undefined, 99)).toBe(99);
   });
 });

package/src/working-copy.ts

@@ -10,6 +10,7 @@ import { parseBlocks, type Block } from "./markdown";
 /** Chunk of the base source a block occupies (for restore and display). */
 export function sourceChunk(base: string, block: Block): string {
   const lines = base.split("\n");
+
   return lines.slice(block.lineStart, block.lineEnd + 1).join("\n");
 }
 
@@ -18,7 +19,9 @@ export function cutBlock(working: string, block: Block): string {
   const lines = working.split("\n");
   const before = lines.slice(0, block.lineStart);
   const after = lines.slice(block.lineEnd + 1);
+
   while (before.length && before[before.length - 1]!.trim() === "") before.pop();
+
   return [...before, ...after].join("\n");
 }
 
@@ -34,10 +37,24 @@ export function restoreLine(next: Block | undefined, workingLineCount: number):
  */
 function signature(text: string): string {
   return parseBlocks(text)
-    .map((b) => b.kind + " " + b.text)
+    .map((block) => block.kind + " " + block.text)
     .join("\0");
 }
 
+/**
+ * Whether a base block is missing from the working source: the working copy
+ * holds fewer blocks with its kind and text than the base does. Only such a
+ * block can be restored without duplicating content.
+ */
+export function isBlockCut(base: string, working: string, block: Block): boolean {
+  const matches = (text: string) =>
+    parseBlocks(text).filter(
+      (candidate) => candidate.kind === block.kind && candidate.text === block.text,
+    ).length;
+
+  return matches(working) < matches(base);
+}
+
 /**
  * Re-insert a cut base block into the working source before `beforeLine`.
  * Returns undefined when the block structure round-trips to the base content
@@ -53,9 +70,11 @@ export function restoreBlock(
   const lines = working.split("\n");
   const before = lines.slice(0, beforeLine);
   const after = lines.slice(beforeLine);
-  const ins = sourceChunk(base, block).split("\n");
-  if (before.length && before[before.length - 1]!.trim() !== "") ins.unshift("");
-  if (after.length && after[0]!.trim() !== "") ins.push("");
-  const restored = [...before, ...ins, ...after].join("\n");
+  const insertedLines = sourceChunk(base, block).split("\n");
+
+  if (before.length && before[before.length - 1]!.trim() !== "") insertedLines.unshift("");
+  if (after.length && after[0]!.trim() !== "") insertedLines.push("");
+  const restored = [...before, ...insertedLines, ...after].join("\n");
+
   return signature(restored) === signature(base) ? undefined : restored;
 }