@cueloop/daemon 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/validate.test.ts

@@ -9,21 +9,24 @@ import {
   AnnotationSchema,
   ArtifactMetaSchema,
   ArtifactSchema,
+  IdentitySchema,
   RevisionSchema,
-  SessionRecordSchema,
+  ThreadRecordSchema,
   VerdictSchema,
   WorkspaceSchema,
   isKnownMethod,
   parseParams,
-  validateSessionRecord,
+  validateThreadRecord,
 } from "./validate";
 import {
+  ARTIFACT_TYPES,
   SCHEMA_VERSION,
   type Anchor,
   type Annotation,
   type Artifact,
   type ArtifactMeta,
-  type ReviewSession,
+  type Identity,
+  type Thread,
   type Revision,
   type Verdict,
   type WorkspaceKey,
@@ -38,11 +41,14 @@ describe("method allowlist", () => {
 
 describe("parseParams", () => {
   test("accepts a well-formed create and defaults meta", () => {
-    const p = parseParams("session.create", {
+    // Act
+    const params = parseParams("session.create", {
       workspace: { repoRoot: "/repo", branch: "main" },
       artifact: { type: "plan", content: "# P" },
     });
-    expect(p.artifact.meta).toEqual({});
+
+    // Assert
+    expect(params.artifact.meta).toEqual({});
   });
 
   test("rejects a missing workspace with a pathed message", () => {
@@ -51,8 +57,21 @@ describe("parseParams", () => {
       throw new Error("should have thrown");
     } catch (err) {
       expect(err).toBeInstanceOf(DaemonError);
-      expect((err as DaemonError).code).toBe("invalid_params");
-      expect((err as DaemonError).message).toContain("session.create: workspace");
+      if (err instanceof DaemonError) {
+        expect(err.code).toBe("invalid_params");
+        expect(err.message).toContain("session.create: workspace");
+      }
+    }
+  });
+
+  test("accepts every artifact type in the schema union", () => {
+    for (const type of ARTIFACT_TYPES) {
+      const params = parseParams("session.create", {
+        workspace: { repoRoot: "/repo", branch: "main" },
+        artifact: { type, content: "body" },
+      });
+
+      expect(params.artifact.type).toBe(type);
     }
   });
 
@@ -72,21 +91,40 @@ describe("parseParams", () => {
   test("defaults and clamps the wait timeout", () => {
     expect(parseParams("session.wait", { id: "ses_1" }).timeoutMs).toBe(60_000);
     expect(() => parseParams("session.wait", { id: "ses_1", timeoutMs: -5 })).toThrow();
-    expect(() => parseParams("session.wait", { id: "ses_1", timeoutMs: 99 * 60 * 60 * 1000 })).toThrow();
+    expect(() =>
+      parseParams("session.wait", { id: "ses_1", timeoutMs: 99 * 60 * 60 * 1000 }),
+    ).toThrow();
   });
 
   test("verdict kinds are closed", () => {
     expect(parseParams("session.resolve", { id: "s", verdictKind: "approve" }).summary).toBe("");
-    expect(() => parseParams("session.resolve", { id: "s", verdictKind: "lgtm" })).toThrow(/verdictKind/);
+    expect(() => parseParams("session.resolve", { id: "s", verdictKind: "lgtm" })).toThrow(
+      /verdictKind/,
+    );
   });
 
   test("annotation kinds stay open (extension kinds are allowed)", () => {
-    const p = parseParams("session.annotate", {
+    // Act
+    const params = parseParams("session.annotate", {
       id: "s",
       annotation: { id: "a1", kind: "praise", anchor: { quote: "x" }, body: "nice" },
     });
-    expect(p.annotation.kind).toBe("praise");
-    expect(p.annotation.anchor.prefix).toBe("");
+
+    // Assert
+    expect(params.annotation.kind).toBe("praise");
+    expect(params.annotation.anchor.prefix).toBe("");
+  });
+
+  test("setViewed takes a full path list and rejects non-string entries", () => {
+    expect(
+      parseParams("session.setViewed", { id: "s", viewedPaths: ["src/a.ts", "src/b.ts"] })
+        .viewedPaths,
+    ).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(parseParams("session.setViewed", { id: "s", viewedPaths: [] }).viewedPaths).toEqual([]);
+    expect(() => parseParams("session.setViewed", { id: "s", viewedPaths: [1] })).toThrow(
+      /viewedPaths/,
+    );
+    expect(() => parseParams("session.setViewed", { id: "s" })).toThrow(/viewedPaths/);
   });
 
   test("null params are treated as empty", () => {
@@ -94,7 +132,7 @@ describe("parseParams", () => {
   });
 });
 
-describe("validateSessionRecord", () => {
+describe("validateThreadRecord", () => {
   const record = {
     schemaVersion: SCHEMA_VERSION,
     id: "ses_1",
@@ -108,29 +146,35 @@ describe("validateSessionRecord", () => {
   };
 
   test("accepts a valid record", () => {
-    expect(validateSessionRecord(record).ok).toBe(true);
+    expect(validateThreadRecord(record).ok).toBe(true);
   });
 
   test("rejects a foreign schema version with a readable reason", () => {
-    const r = validateSessionRecord({ ...record, schemaVersion: "99" });
-    expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.error).toContain("schemaVersion");
+    // Act
+    const result = validateThreadRecord({ ...record, schemaVersion: "99" });
+
+    // Assert
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("schemaVersion");
   });
 
   test("rejects a structurally broken record", () => {
-    const r = validateSessionRecord({ ...record, revisions: "nope" });
-    expect(r.ok).toBe(false);
+    // Act
+    const result = validateThreadRecord({ ...record, revisions: "nope" });
+
+    // Assert
+    expect(result.ok).toBe(false);
   });
 });
 
 /**
- * Wire pins (#70): every schema's entries must cover exactly the keys of the
+ * Wire pins: every schema's entries must cover exactly the keys of the
  * schema type it mirrors. Runtime complement to the compile-time EntriesOf
  * check - the samples are fully populated and typed, so a new field in
  * @cueloop/schema shows up here too.
  */
 describe("wire pins", () => {
-  const keys = (o: object) => Object.keys(o).sort();
+  const keys = <Subject extends object>(subject: Subject) => Object.keys(subject).sort();
   const entryKeys = (schema: { entries: object }) => Object.keys(schema.entries).sort();
 
   const fullMeta: Required<ArtifactMeta> = {
@@ -138,36 +182,129 @@ describe("wire pins", () => {
     agent: "claude-code",
     agentSessionId: "sess-1",
     planPath: "/repo/plan.md",
+    prototypePath: "/repo/proto.html",
     pr: "org/repo#1",
     herdrPane: "%7",
     title: "Plan",
+    workbench: false,
+  };
+  const fullAnchor: Required<Anchor> = {
+    quote: "q",
+    prefix: "p",
+    suffix: "s",
+    blockIndex: 0,
+    endBlockIndex: 0,
+    start: 0,
+    end: 1,
+    selector: "div.card",
   };
-  const fullAnchor: Required<Anchor> = { quote: "q", prefix: "p", suffix: "s", blockIndex: 0, start: 0, end: 1 };
   const fullAnnotation: Required<Annotation> = {
     id: "a1",
     kind: "comment",
     anchor: fullAnchor,
+    target: { kind: "file", path: "src/x.ts", rev: "worktree" },
     body: "b",
     orphan: false,
+    author: "SHA256:abc",
+    replyTo: "a0",
+    resolution: { revision: 2, source: "agent" },
     createdAt: "now",
   };
-  const fullArtifact: Required<Artifact> = { type: "plan", content: "# P", meta: fullMeta };
-  const fullVerdict: Required<Verdict> = { kind: "approve", summary: "", feedback: "", resolvedAt: "now" };
+  const fullArtifact: Required<Artifact> = {
+    type: "plan",
+    content: "# P",
+    meta: fullMeta,
+    files: [{ path: "src/a.ts", oldContents: "old\n", newContents: "new\n", status: "modified" }],
+  };
+  const fullVerdict: Required<Verdict> = {
+    kind: "approve",
+    summary: "",
+    feedback: "",
+    resolvedAt: "now",
+  };
   const fullRevision: Required<Revision> = { revision: 1, content: "# P", submittedAt: "now" };
-  const fullWorkspace: Required<WorkspaceKey> = { repoRoot: "/repo", branch: "main" };
-  const fullSession: Required<ReviewSession> = {
+  const fullWorkspace: Required<WorkspaceKey> = {
+    repoRoot: "/repo",
+    branch: "main",
+    rootCommit: "11e7abbcf507a13ae5e4e7559c4b42dbb52237fe",
+    remote: "git@github.com:acme/repo.git",
+  };
+  const fullIdentity: Required<Identity> = {
+    id: "SHA256:abc",
+    provider: "ssh",
+    name: "Al",
+    handle: "abc",
+  };
+  const fullSession: Required<Thread> = {
     schemaVersion: SCHEMA_VERSION,
     id: "ses_1",
     workspace: fullWorkspace,
     artifact: fullArtifact,
     revisions: [fullRevision],
     annotations: [fullAnnotation],
+    history: {
+      entries: [
+        {
+          id: "e1",
+          parentId: null,
+          type: "revision",
+          by: "agent",
+          content: "# P",
+          createdAt: "now",
+        },
+        { id: "e2", parentId: "e1", type: "comment", annotationId: "a1", createdAt: "now" },
+        { id: "e3", parentId: "e2", type: "comment-removed", annotationId: "a1", createdAt: "now" },
+        { id: "e4", parentId: "e3", type: "verdict", verdict: fullVerdict, createdAt: "now" },
+        {
+          id: "e5",
+          parentId: "e4",
+          type: "branch-summary",
+          text: "tried a thing",
+          abandoned: ["e3"],
+          createdAt: "now",
+        },
+      ],
+      tips: { main: "e5" },
+      branch: "main",
+      labels: { e1: "start" },
+    },
+    curation: [{ path: "src/a.ts", hunkIndex: 0, changeIndex: 1 }],
+    shelvedAnnotations: [fullAnnotation],
+    parentSessionId: "ses_0",
+    shareBranch: "main",
     workingCopy: "# P edited",
+    viewedPaths: ["src/a.ts"],
     verdict: fullVerdict,
     status: "pending",
     createdAt: "now",
+    shareId: "p_abc123xy",
+    owner: "SHA256:owner",
+    participants: [fullIdentity],
   };
 
+  test("a history whose tree is broken is refused even when every entry is well-formed", () => {
+    // Arrange: a parent cycle
+    const record = {
+      ...fullSession,
+      history: {
+        entries: [
+          { id: "a", parentId: "b", type: "revision", by: "agent", content: "x", createdAt: "now" },
+          { id: "b", parentId: "a", type: "comment", annotationId: "a1", createdAt: "now" },
+        ],
+        tips: { main: "b" },
+        branch: "main",
+        labels: {},
+      },
+    };
+
+    // Act
+    const parsed = validateThreadRecord(record);
+
+    // Assert
+    expect(parsed.ok).toBe(false);
+    if (!parsed.ok) expect(parsed.error).toContain("history:");
+  });
+
   test("schema key sets match the schema types", () => {
     expect(entryKeys(WorkspaceSchema)).toEqual(keys(fullWorkspace));
     expect(entryKeys(ArtifactMetaSchema)).toEqual(keys(fullMeta));
@@ -175,24 +312,33 @@ describe("wire pins", () => {
     expect(entryKeys(AnchorSchema)).toEqual(keys(fullAnchor));
     // wire annotations arrive without createdAt; the daemon stamps it
     const { createdAt: _stamped, ...wireAnnotation } = fullAnnotation;
+
     expect(entryKeys(AnnotationSchema)).toEqual(keys(wireAnnotation));
     expect(entryKeys(RevisionSchema)).toEqual(keys(fullRevision));
     expect(entryKeys(VerdictSchema)).toEqual(keys(fullVerdict));
-    expect(entryKeys(SessionRecordSchema)).toEqual(keys(fullSession));
+    expect(entryKeys(IdentitySchema)).toEqual(keys(fullIdentity));
+    expect(entryKeys(ThreadRecordSchema)).toEqual(keys(fullSession));
     // persisted annotations carry the stamped createdAt
-    const stored = SessionRecordSchema.entries.annotations.item;
+    const stored = ThreadRecordSchema.entries.annotations.item;
+
     expect(entryKeys(stored)).toEqual(keys(fullAnnotation));
   });
 
   test("a fully-populated meta survives validation and DaemonCore unchanged", () => {
     const home = mkdtempSync(join(tmpdir(), "cueloop-val-"));
+
     try {
+      // Arrange
       const params = parseParams("session.create", {
         workspace: fullWorkspace,
         artifact: { type: "plan", content: "# P", meta: fullMeta },
       });
       const core = new DaemonCore(home);
+
+      // Act
       const created = core.sessionCreate(params);
+
+      // Assert
       expect(core.sessionGet(created.id).artifact.meta).toEqual(fullMeta);
     } finally {
       rmSync(home, { recursive: true, force: true });

package/src/validate.ts

@@ -1,5 +1,5 @@
 /**
- * Runtime validation of the wire boundary (#14). Everything arriving over the
+ * Runtime validation of the wire boundary. Everything arriving over the
  * socket is untrusted JSON: adapters, the CLI, extensions, and any script a
  * user writes all speak this protocol. Validating here means DaemonCore only
  * ever sees well-formed input, and a malformed request gets a precise error
@@ -11,17 +11,25 @@
 
 import * as v from "valibot";
 import {
+  ARTIFACT_TYPES,
   SCHEMA_VERSION,
   type Anchor,
   type Annotation,
+  type AnnotationTarget,
   type Artifact,
   type ArtifactMeta,
-  type ReviewSession,
+  type DiffFileContents,
+  type Identity,
+  type Thread,
+  type HunkRejection,
   type Revision,
+  type SessionHistory,
+  validateHistory,
   type Verdict,
   type WorkspaceKey,
 } from "@cueloop/schema";
 import { DaemonError } from "./errors";
+import type { Request } from "./protocol";
 
 /**
  * Drift guard for every hand-mirrored shape below. v.object strips keys it
@@ -37,6 +45,8 @@ const NonEmpty = v.pipe(v.string(), v.minLength(1));
 export const WorkspaceSchema = v.object({
   repoRoot: NonEmpty,
   branch: NonEmpty,
+  rootCommit: v.optional(NonEmpty),
+  remote: v.optional(NonEmpty),
 } satisfies EntriesOf<WorkspaceKey>);
 
 export const ArtifactMetaSchema = v.object({
@@ -44,15 +54,27 @@ export const ArtifactMetaSchema = v.object({
   agent: v.optional(v.string()),
   agentSessionId: v.optional(v.string()),
   planPath: v.optional(v.string()),
+  prototypePath: v.optional(v.string()),
   pr: v.optional(v.string()),
   herdrPane: v.optional(v.string()),
   title: v.optional(v.string()),
+  workbench: v.optional(v.boolean()),
 } satisfies EntriesOf<ArtifactMeta>);
 
+export const DiffFileContentsSchema = v.object({
+  path: NonEmpty,
+  oldContents: v.string(),
+  newContents: v.string(),
+  status: v.picklist(["added", "modified", "deleted"]),
+} satisfies EntriesOf<DiffFileContents>);
+
 export const ArtifactSchema = v.object({
-  type: v.picklist(["plan", "diff"]),
+  // Derived from the schema's runtime union: a new primitive extends the wire
+  // contract without touching this file.
+  type: v.picklist(ARTIFACT_TYPES),
   content: v.string(),
   meta: v.optional(ArtifactMetaSchema, {}),
+  files: v.optional(v.array(DiffFileContentsSchema)),
 } satisfies EntriesOf<Artifact>);
 
 export const AnchorSchema = v.object({
@@ -60,22 +82,53 @@ export const AnchorSchema = v.object({
   prefix: v.optional(v.string(), ""),
   suffix: v.optional(v.string(), ""),
   blockIndex: v.optional(v.number()),
+  endBlockIndex: v.optional(v.number()),
   start: v.optional(v.number()),
   end: v.optional(v.number()),
+  selector: v.optional(v.string()),
 } satisfies EntriesOf<Anchor>);
 
+/** The surface a note was made on; absent means the reviewed artifact. */
+export const AnnotationTargetSchema: v.GenericSchema<AnnotationTarget> = v.variant("kind", [
+  v.object({ kind: v.literal("artifact") }),
+  v.object({ kind: v.literal("file"), path: NonEmpty, rev: v.picklist(["worktree", "head"]) }),
+  v.object({ kind: v.literal("welcome") }),
+]);
+
 /** Wire annotations arrive without createdAt - the daemon stamps it. */
 export const AnnotationSchema = v.object({
   id: NonEmpty,
-  /** Open kind set (#2): built-ins are comment and suggestion. */
+  /** Open kind set: the built-in is comment. */
   kind: NonEmpty,
   anchor: AnchorSchema,
+  target: v.optional(AnnotationTargetSchema),
   body: v.string(),
   orphan: v.optional(v.boolean()),
+  author: v.optional(v.string()),
+  replyTo: v.optional(NonEmpty),
+  resolution: v.optional(
+    v.object({
+      revision: v.number(),
+      source: v.picklist(["agent", "drift"]),
+    }),
+  ),
 } satisfies EntriesOf<Omit<Annotation, "createdAt">>);
 
 const SessionId = NonEmpty;
 
+/** A stored annotation: the wire shape plus the daemon-stamped createdAt. */
+export const FullAnnotationSchema = v.object({
+  ...AnnotationSchema.entries,
+  createdAt: v.string(),
+} satisfies EntriesOf<Annotation>);
+
+export const IdentitySchema = v.object({
+  id: NonEmpty,
+  provider: v.literal("ssh"),
+  name: v.optional(v.string()),
+  handle: v.optional(v.string()),
+} satisfies EntriesOf<Identity>);
+
 export const Params = {
   "session.create": v.object({ workspace: WorkspaceSchema, artifact: ArtifactSchema }),
   "session.get": v.object({ id: SessionId }),
@@ -90,20 +143,101 @@ export const Params = {
   "session.wait": v.object({
     id: SessionId,
     // clamped: a negative or absurd timeout is a client bug, not a daemon one
-    timeoutMs: v.optional(v.pipe(v.number(), v.minValue(0), v.maxValue(24 * 60 * 60 * 1000)), 60_000),
+    timeoutMs: v.optional(
+      v.pipe(v.number(), v.minValue(0), v.maxValue(24 * 60 * 60 * 1000)),
+      60_000,
+    ),
+  }),
+  "session.annotate": v.object({
+    id: SessionId,
+    annotation: AnnotationSchema,
+    authorName: v.optional(v.string()),
+  }),
+  // "session.comment" is the primary annotate method; "session.annotate" stays an accepted alias
+  "session.comment": v.object({
+    id: SessionId,
+    annotation: AnnotationSchema,
+    authorName: v.optional(v.string()),
   }),
-  "session.annotate": v.object({ id: SessionId, annotation: AnnotationSchema }),
   "session.removeAnnotation": v.object({ id: SessionId, annotationId: NonEmpty }),
+  "session.setParticipantName": v.object({ id: SessionId, author: NonEmpty, name: NonEmpty }),
   "session.setWorkingCopy": v.object({ id: SessionId, workingCopy: v.optional(v.string()) }),
+  "session.cutBlock": v.object({
+    id: SessionId,
+    blockIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  }),
+  "session.restoreBlock": v.object({
+    id: SessionId,
+    baseBlockIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    line: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+  }),
+  "session.curate": v.object({
+    id: SessionId,
+    rejections: v.array(
+      v.object({
+        path: NonEmpty,
+        hunkIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
+        changeIndex: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+      } satisfies EntriesOf<HunkRejection>),
+    ),
+  }),
+  "session.setViewed": v.object({ id: SessionId, viewedPaths: v.array(v.string()) }),
+  "session.setTitle": v.object({ id: SessionId, title: v.string() }),
+  "session.projectFiles": v.object({ id: SessionId }),
+  "session.fileContents": v.object({ id: SessionId, path: NonEmpty }),
+  "repo.files": v.object({ cwd: NonEmpty }),
+  "repo.fileContents": v.object({ cwd: NonEmpty, path: NonEmpty }),
+  "repo.changes": v.object({ cwd: NonEmpty }),
+  "repo.diff": v.object({ cwd: NonEmpty }),
+  "session.workbench": v.object({ cwd: NonEmpty }),
+  "session.navigate": v.object({
+    id: SessionId,
+    entryId: NonEmpty,
+    summary: v.optional(v.string()),
+    // stand on this branch first, so a move on another branch is one request
+    branch: v.optional(NonEmpty),
+  }),
+  "session.branch": v.object({ id: SessionId, name: NonEmpty }),
+  "session.switch": v.object({ id: SessionId, branch: NonEmpty }),
+  "session.label": v.object({ id: SessionId, label: NonEmpty }),
+  "session.fork": v.object({ id: SessionId }),
+  "session.refreshDiff": v.object({ id: SessionId }),
+  "session.setShareId": v.object({ id: SessionId, shareId: NonEmpty }),
+  "session.delete": v.object({ id: SessionId }),
+  "session.mergeShared": v.object({
+    id: SessionId,
+    annotations: v.array(FullAnnotationSchema),
+    participants: v.optional(v.array(IdentitySchema)),
+    // the removal entries a share recorded, carried by id so a merge applies each once
+    removals: v.optional(
+      v.array(v.object({ id: NonEmpty, annotationId: NonEmpty, createdAt: v.string() })),
+    ),
+  }),
   "session.resolve": v.object({
     id: SessionId,
     verdictKind: v.picklist(["comment", "approve", "request_changes"]),
     summary: v.optional(v.string(), ""),
+    actionBodies: v.optional(v.record(v.string(), v.string())),
+  }),
+  "session.submitRevision": v.object({
+    id: SessionId,
+    content: v.string(),
+    /** Annotation ids the agent acted on; each is marked addressed. */
+    addressedAnnotationIds: v.optional(v.array(NonEmpty), []),
   }),
-  "session.submitRevision": v.object({ id: SessionId, content: v.string() }),
   "events.subscribe": v.object({}),
   "daemon.ping": v.object({}),
+  // the owner token proves ownership; without it a request for owner stays a collaborator
+  "daemon.hello": v.object({
+    role: v.picklist(["owner", "collaborator", "agent"]),
+    token: v.optional(v.string()),
+    // the author a non-owner acts as, bound once for the connection
+    author: v.optional(NonEmpty),
+  }),
   "daemon.shutdown": v.object({}),
+  // herdr adapter scratch: the review's opened tab, kept off the session record.
+  "herdr.getTab": v.object({ id: SessionId }),
+  "herdr.setTab": v.object({ id: SessionId, tabId: NonEmpty, paneId: NonEmpty }),
 } as const;
 
 export type MethodName = keyof typeof Params;
@@ -113,13 +247,22 @@ export function isKnownMethod(method: string): method is MethodName {
 }
 
 /** Validate params for a method, or throw a DaemonError the client can read. */
-export function parseParams<M extends MethodName>(method: M, params: unknown): v.InferOutput<(typeof Params)[M]> {
+export function parseParams<M extends MethodName>(
+  method: M,
+  params: Request["params"],
+): v.InferOutput<(typeof Params)[M]> {
   const result = v.safeParse(Params[method], params ?? {});
+
   if (!result.success) {
     const issue = result.issues[0]!;
-    const path = issue.path?.map((p) => String(p.key)).join(".") ?? "";
-    throw new DaemonError("invalid_params", `${method}: ${path ? path + " - " : ""}${issue.message}`);
+    const path = issue.path?.map((pathSegment) => String(pathSegment.key)).join(".") ?? "";
+
+    throw new DaemonError(
+      "invalid_params",
+      `${method}: ${path ? path + " - " : ""}${issue.message}`,
+    );
   }
+
   return result.output;
 }
 
@@ -136,24 +279,91 @@ export const VerdictSchema = v.object({
   resolvedAt: v.string(),
 } satisfies EntriesOf<Verdict>);
 
+const EntryBaseEntries = {
+  id: NonEmpty,
+  parentId: v.nullable(NonEmpty),
+  createdAt: v.string(),
+};
+
+/** One record of a session's history; the tree pointers plus the entry's own fields. */
+export const SessionEntrySchema = v.variant("type", [
+  v.object({
+    ...EntryBaseEntries,
+    type: v.literal("revision"),
+    by: v.picklist(["agent", "reviewer"]),
+    content: v.string(),
+  }),
+  v.object({ ...EntryBaseEntries, type: v.literal("comment"), annotationId: NonEmpty }),
+  v.object({ ...EntryBaseEntries, type: v.literal("comment-removed"), annotationId: NonEmpty }),
+  v.object({ ...EntryBaseEntries, type: v.literal("verdict"), verdict: VerdictSchema }),
+  v.object({
+    ...EntryBaseEntries,
+    type: v.literal("branch-summary"),
+    text: v.string(),
+    abandoned: v.array(NonEmpty),
+  }),
+]);
+
+export const SessionHistorySchema = v.pipe(
+  v.object({
+    entries: v.array(SessionEntrySchema),
+    tips: v.record(v.string(), NonEmpty),
+    branch: NonEmpty,
+    labels: v.record(v.string(), v.string()),
+  } satisfies EntriesOf<SessionHistory>),
+  // the shape is not enough: the tree itself must hold, or a walk hangs or rewires the path
+  v.rawCheck(({ dataset, addIssue }) => {
+    if (!dataset.typed) return;
+    const problem = validateHistory(dataset.value);
+
+    if (problem !== null) addIssue({ message: `history: ${problem}` });
+  }),
+);
+
 /** Persisted records are validated on recovery: a bad file is skipped, not fatal. */
-export const SessionRecordSchema = v.object({
+export const ThreadRecordSchema = v.object({
   schemaVersion: v.literal(SCHEMA_VERSION),
   id: NonEmpty,
   workspace: WorkspaceSchema,
   artifact: ArtifactSchema,
   revisions: v.array(RevisionSchema),
-  annotations: v.array(v.object({ ...AnnotationSchema.entries, createdAt: v.string() } satisfies EntriesOf<Annotation>)),
+  annotations: v.array(FullAnnotationSchema),
+  history: v.optional(SessionHistorySchema),
+  curation: v.optional(
+    v.array(
+      v.object({
+        path: NonEmpty,
+        hunkIndex: v.number(),
+        changeIndex: v.optional(v.number()),
+      } satisfies EntriesOf<HunkRejection>),
+    ),
+  ),
   workingCopy: v.optional(v.string()),
+  viewedPaths: v.optional(v.array(v.string())),
   verdict: v.nullable(VerdictSchema),
   status: v.picklist(["pending", "resolved"]),
   createdAt: v.string(),
-} satisfies EntriesOf<ReviewSession>);
+  shelvedAnnotations: v.optional(v.array(FullAnnotationSchema)),
+  parentSessionId: v.optional(v.string()),
+  shareId: v.optional(v.string()),
+  shareBranch: v.optional(v.string()),
+  owner: v.optional(v.string()),
+  participants: v.optional(v.array(IdentitySchema)),
+} satisfies EntriesOf<Thread>);
+
+export function validateThreadRecord(
+  raw: Parameters<typeof v.safeParse>[1],
+): { ok: true; value: v.InferOutput<typeof ThreadRecordSchema> } | { ok: false; error: string } {
+  const result = v.safeParse(ThreadRecordSchema, raw);
 
-export function validateSessionRecord(raw: unknown): { ok: true; value: v.InferOutput<typeof SessionRecordSchema> } | { ok: false; error: string } {
-  const result = v.safeParse(SessionRecordSchema, raw);
   if (result.success) return { ok: true, value: result.output };
   const issue = result.issues[0]!;
-  const path = issue.path?.map((p) => String(p.key)).join(".") ?? "";
+  const path = issue.path?.map((pathSegment) => String(pathSegment.key)).join(".") ?? "";
+
   return { ok: false, error: `${path ? path + ": " : ""}${issue.message}` };
 }
+
+/** @deprecated use ThreadRecordSchema */
+export const SessionRecordSchema = ThreadRecordSchema;
+/** @deprecated use validateThreadRecord */
+export const validateSessionRecord = validateThreadRecord;