@cueloop/schema 0.1.0-alpha.9 → 0.1.0-alpha.90

package/src/types.ts

@@ -1,38 +1,140 @@
 /**
- * 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;
 }
 
-export type ArtifactType = "plan" | "diff";
+/**
+ * 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);
+}
+
+/**
+ * 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;
+  /** Diff source selected when the Thread was created; an older Thread without this field uses Git. */
+  vcs?: string;
+  /** Logical change identity when the VCS keeps one through rewrites. */
+  vcsChangeId?: string;
+  /** Exact source revision captured for this diff. */
+  vcsRevisionId?: 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;
+  /** Markdown shown in the Thread pane beside a pull request diff. */
+  prBrief?: string;
+  /** Exact pull request commits captured by this review. */
+  prBaseSha?: string;
+  prHeadSha?: string;
+  /** Newer remote commits detected by the poller; the reviewer chooses when to refresh. */
+  prRefreshBaseSha?: string;
+  prRefreshHeadSha?: string;
+  /** Canonical GitHub pull request URL. */
+  prUrl?: 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;
+}
+
+/** VCS provenance for a submitted diff revision. */
+export interface DiffSource {
+  vcs: string;
+  changeId?: string;
+  revisionId?: string;
+  baseRevisionId?: 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";
+
+/**
+ * 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,46 +146,212 @@ 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 (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 & {});
+
+/**
+ * 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" };
+}
+
+/**
+ * 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;
+  /** GitHub line anchor and presentation fields for an agent-authored PR review comment. */
+  reviewComment?: ReviewComment;
+  /**
+   * 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 const REVIEW_SEVERITIES = ["p0", "p1", "p2"] as const;
+export type ReviewSeverity = (typeof REVIEW_SEVERITIES)[number];
+
+/** Data needed to render and publish one agent-authored pull request comment. */
+export interface ReviewComment {
+  severity: ReviewSeverity;
+  title: string;
+  path: string;
+  line: number;
+  startLine?: number;
+  /** Quote-primary anchor for the first line of a multiline finding. */
+  startAnchor?: Anchor;
+  side: "LEFT" | "RIGHT";
+  suggestion?: string;
+  prompt?: string;
+}
+
+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 const MESSAGE_OUTCOMES = ["comment", "approved", "changes_requested"] as const;
+export type MessageOutcome = (typeof MESSAGE_OUTCOMES)[number];
+
+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;
+  /** Annotation snapshots included in this delivery, for incremental sends. */
+  annotations?: Annotation[];
+  sentAt: string;
 }
 
 export interface Revision {
   revision: number;
   content: string;
   submittedAt: string;
+  /** Exact VCS source for this reviewed text, when one was captured. */
+  source?: DiffSource;
+  /** File contents captured with this diff revision, retained across refreshes. */
+  files?: DiffFileContents[];
 }
 
 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;
+}
+
+/** One exact character range removed from the submitted artifact source. */
+export interface TextCut {
+  start: number;
+  end: number;
+  quote: string;
+}
+
+export interface Thread {
   schemaVersion: string;
   id: string;
   workspace: WorkspaceKey;
@@ -91,20 +359,68 @@ 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;
+  /** Exact source ranges behind character Cuts in the current working copy. */
+  textCuts?: TextCut[];
+  /**
+   * 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 +429,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)}`;
 }