@cueloop/daemon 0.1.0-alpha.83 → 0.1.0-alpha.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.83",
+  "version": "0.1.0-alpha.85",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.83",
+    "@cueloop/schema": "0.1.0-alpha.85",
     "@pierre/diffs": "^1.4.1",
     "effect": "^4.0.0-rc.115",
     "smol-toml": "^1.8.0",

package/src/api.test.ts

@@ -169,6 +169,71 @@ describe("session lifecycle", () => {
     ).toThrow("already resolved");
   });
 
+  test("Comment delivers only changed annotations and keeps the Thread pending", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    core.sessionAnnotate(session.id, {
+      id: "first",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "first note",
+    });
+
+    const commented = core.sessionSendMessage(session.id, "comment", "Interim feedback");
+
+    expect(commented.status).toBe("pending");
+    expect(commented.message!.annotations?.map((annotation) => annotation.id)).toEqual(["first"]);
+    expect(commented.message!.body).toContain("first note");
+
+    core.sessionAnnotate(session.id, {
+      id: "second",
+      kind: "comment",
+      anchor: { quote: "Context", prefix: "Plan", suffix: "Do" },
+      body: "second note",
+    });
+
+    const secondComment = core.sessionSendMessage(session.id, "comment", "Another note");
+
+    expect(secondComment.status).toBe("pending");
+    expect(secondComment.message!.annotations?.map((annotation) => annotation.id)).toEqual([
+      "second",
+    ]);
+    expect(secondComment.message!.body).not.toContain("first note");
+    expect(secondComment.message!.body).toContain("second note");
+
+    core.sessionAnnotate(session.id, {
+      id: "first",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "edited first note",
+    });
+
+    const resolved = core.sessionSendMessage(session.id, "approved", "Ready");
+
+    expect(resolved.status).toBe("resolved");
+    expect(resolved.message!.annotations?.map((annotation) => annotation.id)).toEqual(["first"]);
+    expect(resolved.message!.body).toContain("edited first note");
+    expect(resolved.message!.body).not.toContain("second note");
+  });
+
+  test("agent-side resolution does not redeliver a sent annotation", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    core.sessionAnnotate(session.id, {
+      id: "sent",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "sent note",
+    });
+    core.sessionSendMessage(session.id, "comment", "Interim feedback");
+    core.sessionSubmitRevision(session.id, PLAN.content, ["sent"]);
+
+    const resolved = core.sessionSendMessage(session.id, "approved", "Ready");
+
+    expect(resolved.message!.annotations).toEqual([]);
+    expect(resolved.message!.body).not.toContain("sent note");
+  });
+
   test("working copy stores edits and clears on revert or no-op", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
@@ -186,6 +251,55 @@ describe("session lifecycle", () => {
     expect(core.sessionGet(session.id).workingCopy).toBeUndefined();
   });
 
+  test("character Cut provenance survives persistence and clears on an arbitrary edit", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const start = PLAN.content.indexOf("carefully");
+    const end = start + "carefully".length;
+    const workingCopy = PLAN.content.slice(0, start) + PLAN.content.slice(end);
+    const cut = { start, end, quote: "carefully" };
+
+    core.sessionSetWorkingCopy(session.id, workingCopy, [cut]);
+
+    expect(core.sessionGet(session.id).textCuts).toEqual([cut]);
+    expect(new DaemonCore(home).sessionGet(session.id).textCuts).toEqual([cut]);
+    const cutTip = core.sessionGet(session.id).history!.tips.main!;
+    const root = core.sessionGet(session.id).history!.entries[0]!.id;
+
+    core.sessionBranch(session.id, "with-cut");
+    core.sessionNavigate(session.id, root, undefined, "main");
+    expect(core.sessionGet(session.id).textCuts).toBeUndefined();
+    core.sessionSwitch(session.id, "with-cut");
+    expect(core.sessionGet(session.id).history!.tips["with-cut"]).toBe(cutTip);
+    expect(core.sessionGet(session.id).textCuts).toEqual([cut]);
+    core.sessionSetWorkingCopy(session.id, PLAN.content.replace("carefully", "safely"));
+    expect(core.sessionGet(session.id).textCuts).toBeUndefined();
+  });
+
+  test("rejects character Cut provenance that does not match the artifact", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    for (const textCuts of [
+      [{ start: 0, end: 5, quote: "stale" }],
+      [{ start: PLAN.content.length - 1, end: PLAN.content.length + 1, quote: "xx" }],
+    ]) {
+      expect(() => core.sessionSetWorkingCopy(session.id, "remaining", textCuts)).toThrow(
+        "text Cuts do not match the submitted artifact and working copy",
+      );
+    }
+    expect(core.sessionGet(session.id).workingCopy).toBeUndefined();
+    expect(core.sessionGet(session.id).textCuts).toBeUndefined();
+  });
+
+  test("rejects character Cut provenance whose result differs from the working copy", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const start = PLAN.content.indexOf("carefully");
+    const textCuts = [{ start, end: start + "carefully".length, quote: "carefully" }];
+
+    expect(() => core.sessionSetWorkingCopy(session.id, "different", textCuts)).toThrow(
+      "text Cuts do not match the submitted artifact and working copy",
+    );
+  });
+
   test("a thread rename sets the title, clears back to the default on empty, and survives a restart", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
@@ -235,8 +349,13 @@ describe("session lifecycle", () => {
   test("revision reopens the session and resets working copy + message", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const start = PLAN.content.indexOf("carefully");
+    const end = start + "carefully".length;
+    const cut = { start, end, quote: "carefully" };
 
-    core.sessionSetWorkingCopy(session.id, PLAN.content + "\nedit");
+    core.sessionSetWorkingCopy(session.id, PLAN.content.slice(0, start) + PLAN.content.slice(end), [
+      cut,
+    ]);
     core.sessionSendMessage(session.id, "changes_requested", "redo");
 
     // Act
@@ -246,6 +365,7 @@ describe("session lifecycle", () => {
     expect(revised.status).toBe("pending");
     expect(revised.message).toBeNull();
     expect(revised.workingCopy).toBeUndefined();
+    expect(revised.textCuts).toBeUndefined();
     expect(revised.revisions.length).toBe(2);
     expect(revised.artifact.content).toBe("# Plan v2\n");
   });

package/src/api.ts

@@ -8,6 +8,7 @@
 import {
   SCHEMA_VERSION,
   appendEntry,
+  applyTextCuts,
   applyPathView,
   createBranch,
   cutBlock,
@@ -44,6 +45,7 @@ import {
   type Delivery,
   type PendingDelivery,
   type Thread,
+  type TextCut,
   type SessionHistory,
   type Message,
   type MessageOutcome,
@@ -69,6 +71,29 @@ import { listProjectFiles, readProjectFile } from "./project-files";
 import { resolveWorkspace } from "./thread-review";
 import { DaemonError } from "./errors";
 
+/** Reviewer-controlled fields that make an annotation new or edited for delivery. */
+function annotationDeliveryFingerprint(annotation: Annotation | undefined): string {
+  if (!annotation) return "";
+
+  return JSON.stringify({
+    kind: annotation.kind,
+    anchor: {
+      quote: annotation.anchor.quote,
+      prefix: annotation.anchor.prefix,
+      suffix: annotation.anchor.suffix,
+      blockIndex: annotation.anchor.blockIndex,
+      endBlockIndex: annotation.anchor.endBlockIndex,
+      start: annotation.anchor.start,
+      end: annotation.anchor.end,
+      selector: annotation.anchor.selector,
+    },
+    target: annotation.target,
+    body: annotation.body,
+    author: annotation.author,
+    replyTo: annotation.replyTo,
+  });
+}
+
 /** What a share hands back: the notes and names it collected, and the removals it recorded. */
 export interface SharedMerge {
   annotations: Annotation[];
@@ -445,9 +470,11 @@ export class DaemonCore {
   }
 
   /** The reviewer's working copy; undefined clears it (revert all edits). */
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Thread {
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined, textCuts?: TextCut[]): Thread {
     const session = this.mutable(id);
-    const entryId = this.applyWorkingCopy(session, workingCopy);
+
+    if (textCuts?.length) this.assertTextCuts(session.artifact.content, workingCopy, textCuts);
+    const entryId = this.applyWorkingCopy(session, workingCopy, textCuts);
 
     this.store.upsert(session);
     this.emit("session.updated", id, entryId);
@@ -455,6 +482,32 @@ export class DaemonCore {
     return session;
   }
 
+  private assertTextCuts(
+    source: string,
+    workingCopy: string | undefined,
+    textCuts: readonly TextCut[],
+  ): void {
+    let previousEnd = 0;
+    const valid = textCuts.every((cut) => {
+      const matches =
+        cut.start >= previousEnd &&
+        cut.end > cut.start &&
+        cut.end <= source.length &&
+        source.slice(cut.start, cut.end) === cut.quote;
+
+      previousEnd = cut.end;
+
+      return matches;
+    });
+
+    if (!valid || workingCopy === undefined || applyTextCuts(source, textCuts) !== workingCopy) {
+      throw new DaemonError(
+        "invalid_params",
+        "text Cuts do not match the submitted artifact and working copy",
+      );
+    }
+  }
+
   /**
    * The guided walk's viewed marks. Merge-additive: walking only ever adds
    * marks, so concurrent or stale clients converge instead of overwriting
@@ -755,16 +808,29 @@ export class DaemonCore {
   ): Thread {
     const session = this.mutable(id);
     const sentAt = new Date().toISOString();
+    const sentAnnotations = new Map(
+      (session.history?.entries ?? [])
+        .filter((entry) => entry.type === "message")
+        .flatMap((entry) => (entry.type === "message" ? (entry.message.annotations ?? []) : []))
+        .map((annotation) => [annotation.id, annotation]),
+    );
+    const annotations = session.annotations.filter(
+      (annotation) =>
+        !isAddressed(annotation) &&
+        annotationDeliveryFingerprint(sentAnnotations.get(annotation.id)) !==
+          annotationDeliveryFingerprint(annotation),
+    );
     const message: Message = {
       id: newMessageId(),
       outcome,
       summary,
-      body: feedbackForSession(session, outcome, summary, actionBodies),
+      body: feedbackForSession(session, outcome, summary, actionBodies, annotations),
+      annotations,
       sentAt,
     };
 
     session.message = message;
-    session.status = "resolved";
+    session.status = outcome === "comment" ? "pending" : "resolved";
     const entryId = this.record(session, {
       type: "message",
       message,
@@ -772,13 +838,18 @@ export class DaemonCore {
     });
     this.store.upsert(session);
     this.reconcileDeliveries(session);
+    this.emit("message.sent", id, entryId);
+    if (outcome === "comment") {
+      this.emit("session.updated", id, entryId);
+
+      return session;
+    }
     // a resolved diff review is frozen; stop hot-reloading its working tree
     this.untrackLiveDiffSession(session);
     const parked = this.waiters.get(id) ?? [];
 
     this.waiters.delete(id);
     for (const parkedWaiter of parked) parkedWaiter(session);
-    this.emit("message.sent", id, entryId);
     this.emit("inbox.changed", id);
 
     return session;
@@ -815,6 +886,7 @@ export class DaemonCore {
       createdAt: now,
     });
     delete session.workingCopy;
+    delete session.textCuts;
     session.message = null;
     session.status = "pending";
 
@@ -1063,25 +1135,35 @@ export class DaemonCore {
    * Set or clear the working copy and, when the reviewer's text changed, record
    * it as a reviewer revision on the current branch. Returns that entry's id.
    */
-  private applyWorkingCopy(session: Thread, workingCopy: string | undefined): string | undefined {
+  private applyWorkingCopy(
+    session: Thread,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): string | undefined {
     const before = session.workingCopy ?? session.artifact.content;
     const next =
       workingCopy === undefined || workingCopy === session.artifact.content
         ? undefined
         : workingCopy;
 
+    if (textCuts?.length) session.textCuts = textCuts;
+    else delete session.textCuts;
     if (next === undefined) delete session.workingCopy;
     else session.workingCopy = next;
     const after = next ?? session.artifact.content;
 
     if (after === before) return undefined;
 
-    return this.record(session, {
+    const revision: Extract<NewEntry, { type: "revision" }> = {
       type: "revision",
       by: "reviewer",
       content: after,
       createdAt: new Date().toISOString(),
-    });
+    };
+
+    if (textCuts?.length) revision.textCuts = textCuts;
+
+    return this.record(session, revision);
   }
 
   /** The session's history; a record without a revision has none and cannot be moved through. */

package/src/client.ts

@@ -31,6 +31,7 @@ import type {
   PendingDelivery,
   MessageOutcome,
   WorkspaceKey,
+  TextCut,
 } from "@cueloop/schema";
 import {
   BackpressureWriter,
@@ -113,7 +114,11 @@ export interface ThreadClient {
   ): Promise<Thread>;
   /** Remove a comment; a non-owner connection removes only the comments of the author it is bound to. */
   sessionRemoveAnnotation(id: string, annotationId: string): Promise<Thread>;
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<Thread>;
+  sessionSetWorkingCopy(
+    id: string,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): Promise<Thread>;
   /** Cut the `blockIndex`-th block of the working copy. */
   sessionCutBlock(id: string, blockIndex: number): Promise<Thread>;
   /** Re-insert the `baseBlockIndex`-th block of the submitted revision before `line` (default: the end). */
@@ -495,8 +500,16 @@ export class DaemonClient implements ThreadClient {
   sessionSetParticipantName(id: string, author: string, name: string): Promise<Thread> {
     return this.request("session.setParticipantName", { id, author, name }, ThreadRecordSchema);
   }
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<Thread> {
-    return this.request("session.setWorkingCopy", { id, workingCopy }, ThreadRecordSchema);
+  sessionSetWorkingCopy(
+    id: string,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): Promise<Thread> {
+    return this.request(
+      "session.setWorkingCopy",
+      { id, workingCopy, textCuts },
+      ThreadRecordSchema,
+    );
   }
   sessionCutBlock(id: string, blockIndex: number): Promise<Thread> {
     return this.request("session.cutBlock", { id, blockIndex }, ThreadRecordSchema);

package/src/harness-delivery.test.ts

@@ -34,6 +34,23 @@ function createPlan(instance: DaemonCore) {
 }
 
 describe("durable harness delivery", () => {
+  test("delivers Comment without resolving the Thread", () => {
+    const instance = core();
+    const thread = createPlan(instance);
+    const binding = instance.harnessBind({
+      threadId: thread.id,
+      harness: "fake",
+      harnessSessionId: "fake_1",
+    });
+
+    const sent = instance.sessionSendMessage(thread.id, "comment", "Interim note.");
+    const pending = instance.deliveryPending(binding.id);
+
+    expect(sent.status).toBe("pending");
+    expect(pending).toHaveLength(1);
+    expect(pending[0]!.message.outcome).toBe("comment");
+  });
+
   test("reload finds only bindings for the active harness conversation", () => {
     const first = core();
     const thread = createPlan(first);

package/src/server.ts

@@ -377,7 +377,7 @@ export class DaemonServer {
     "session.setWorkingCopy": (_connection, request) => {
       const params = parseParams("session.setWorkingCopy", request.params);
 
-      return this.core.sessionSetWorkingCopy(params.id, params.workingCopy);
+      return this.core.sessionSetWorkingCopy(params.id, params.workingCopy, params.textCuts);
     },
     "session.cutBlock": (_connection, request) => {
       const params = parseParams("session.cutBlock", request.params);

package/src/validate.test.ts

@@ -76,6 +76,30 @@ describe("parseParams", () => {
     }
   });
 
+  test.each([
+    [
+      [
+        { start: 2, end: 4, quote: "ab" },
+        { start: 1, end: 2, quote: "c" },
+      ],
+    ],
+    [
+      [
+        { start: 1, end: 4, quote: "abc" },
+        { start: 3, end: 5, quote: "de" },
+      ],
+    ],
+    [[{ start: 1, end: 4, quote: "ab" }]],
+  ])("rejects malformed text Cut provenance", (textCuts) => {
+    expect(() =>
+      parseParams("session.setWorkingCopy", {
+        id: "ses_1",
+        workingCopy: "remaining",
+        textCuts,
+      }),
+    ).toThrow("text Cuts must be ordered, non-overlapping, and match their quote lengths");
+  });
+
   test("rejects an unknown artifact type", () => {
     expect(() =>
       parseParams("session.create", {
@@ -224,6 +248,7 @@ describe("wire pins", () => {
     outcome: "approved",
     summary: "",
     body: "",
+    annotations: [fullAnnotation],
     sentAt: "now",
   };
   const fullRevision: Required<Revision> = { revision: 1, content: "# P", submittedAt: "now" };
@@ -276,7 +301,8 @@ describe("wire pins", () => {
     shelvedAnnotations: [fullAnnotation],
     parentSessionId: "ses_0",
     shareBranch: "main",
-    workingCopy: "# P edited",
+    workingCopy: "# ",
+    textCuts: [{ start: 2, end: 3, quote: "P" }],
     viewedPaths: ["src/a.ts"],
     message: fullMessage,
     status: "pending",
@@ -320,6 +346,20 @@ describe("wire pins", () => {
     if (!parsed.ok) expect(parsed.error).toContain("history:");
   });
 
+  test("a persisted Thread with stale text Cut provenance is refused", () => {
+    const result = validateThreadRecord({
+      ...fullSession,
+      workingCopy: "# P",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain(
+        "text Cuts do not match the submitted artifact and working copy",
+      );
+    }
+  });
+
   test("schema key sets match the schema types", () => {
     expect(entryKeys(WorkspaceSchema)).toEqual(keys(fullWorkspace));
     expect(entryKeys(ArtifactMetaSchema)).toEqual(keys(fullMeta));

package/src/validate.ts

@@ -12,6 +12,7 @@
 import * as v from "valibot";
 import {
   ARTIFACT_TYPES,
+  MESSAGE_OUTCOMES,
   WORKFLOW_KINDS,
   SCHEMA_VERSION,
   type Anchor,
@@ -22,6 +23,7 @@ import {
   type DiffFileContents,
   type Identity,
   type Thread,
+  type TextCut,
   type HunkRejection,
   type HarnessBinding,
   type Delivery,
@@ -33,6 +35,7 @@ import {
   validateHistory,
   type Message,
   type WorkspaceKey,
+  applyTextCuts,
 } from "@cueloop/schema";
 import { DaemonError } from "./errors";
 import type { Request } from "./protocol";
@@ -48,6 +51,25 @@ type EntriesOf<T> = { [K in keyof T]-?: v.GenericSchema<any, any> };
 
 const NonEmpty = v.pipe(v.string(), v.minLength(1));
 
+const TextCutSchema = v.object({
+  start: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  end: v.pipe(v.number(), v.integer(), v.minValue(1)),
+  quote: NonEmpty,
+} satisfies EntriesOf<TextCut>);
+
+const TextCutsSchema = v.pipe(
+  v.array(TextCutSchema),
+  v.check(
+    (cuts) =>
+      cuts.every(
+        (cut, index) =>
+          cut.end - cut.start === cut.quote.length &&
+          (index === 0 || cuts[index - 1]!.end <= cut.start),
+      ),
+    "text Cuts must be ordered, non-overlapping, and match their quote lengths",
+  ),
+);
+
 export const WorkspaceSchema = v.object({
   repoRoot: NonEmpty,
   branch: NonEmpty,
@@ -196,7 +218,11 @@ export const Params = {
   }),
   "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.setWorkingCopy": v.object({
+    id: SessionId,
+    workingCopy: v.optional(v.string()),
+    textCuts: v.optional(TextCutsSchema),
+  }),
   "session.cutBlock": v.object({
     id: SessionId,
     blockIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
@@ -252,7 +278,7 @@ export const Params = {
   }),
   "session.sendMessage": v.object({
     id: SessionId,
-    outcome: v.picklist(["approved", "changes_requested"]),
+    outcome: v.picklist(MESSAGE_OUTCOMES),
     summary: v.optional(v.string(), ""),
     actionBodies: v.optional(v.record(v.string(), v.string())),
   }),
@@ -336,9 +362,10 @@ export const RevisionSchema = v.object({
 
 export const MessageSchema = v.object({
   id: NonEmpty,
-  outcome: v.picklist(["approved", "changes_requested"]),
+  outcome: v.picklist(MESSAGE_OUTCOMES),
   summary: v.string(),
   body: v.string(),
+  annotations: v.optional(v.array(FullAnnotationSchema)),
   sentAt: v.string(),
 } satisfies EntriesOf<Message>);
 
@@ -360,6 +387,7 @@ export const SessionEntrySchema = v.variant("type", [
     type: v.literal("revision"),
     by: v.picklist(["agent", "reviewer"]),
     content: v.string(),
+    textCuts: v.optional(TextCutsSchema),
   }),
   v.object({ ...EntryBaseEntries, type: v.literal("comment"), annotationId: NonEmpty }),
   v.object({ ...EntryBaseEntries, type: v.literal("comment-removed"), annotationId: NonEmpty }),
@@ -389,39 +417,53 @@ export const SessionHistorySchema = v.pipe(
 );
 
 /** Persisted records are validated on recovery: a bad file is skipped, not fatal. */
-export const ThreadRecordSchema = v.object({
-  schemaVersion: v.literal(SCHEMA_VERSION),
-  id: NonEmpty,
-  workspace: WorkspaceSchema,
-  artifact: ArtifactSchema,
-  revisions: v.array(RevisionSchema),
-  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>),
+export const ThreadRecordSchema = v.pipe(
+  v.object({
+    schemaVersion: v.literal(SCHEMA_VERSION),
+    id: NonEmpty,
+    workspace: WorkspaceSchema,
+    artifact: ArtifactSchema,
+    revisions: v.array(RevisionSchema),
+    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())),
-  message: v.nullable(MessageSchema),
-  status: v.picklist(["pending", "resolved"]),
-  createdAt: v.string(),
-  shelvedAnnotations: v.optional(v.array(FullAnnotationSchema)),
-  parentSessionId: v.optional(v.string()),
-  shares: v.optional(v.array(ShareLinkSchema)),
-  shareId: v.optional(v.string()),
-  shareBranch: v.optional(v.string()),
-  owner: v.optional(v.string()),
-  access: v.optional(
-    v.object({ githubLogins: v.array(NonEmpty) } satisfies EntriesOf<ShareAccess>),
-  ),
-  participants: v.optional(v.array(IdentitySchema)),
-} satisfies EntriesOf<Thread>);
+    workingCopy: v.optional(v.string()),
+    textCuts: v.optional(TextCutsSchema),
+    viewedPaths: v.optional(v.array(v.string())),
+    message: v.nullable(MessageSchema),
+    status: v.picklist(["pending", "resolved"]),
+    createdAt: v.string(),
+    shelvedAnnotations: v.optional(v.array(FullAnnotationSchema)),
+    parentSessionId: v.optional(v.string()),
+    shares: v.optional(v.array(ShareLinkSchema)),
+    shareId: v.optional(v.string()),
+    shareBranch: v.optional(v.string()),
+    owner: v.optional(v.string()),
+    access: v.optional(
+      v.object({ githubLogins: v.array(NonEmpty) } satisfies EntriesOf<ShareAccess>),
+    ),
+    participants: v.optional(v.array(IdentitySchema)),
+  } satisfies EntriesOf<Thread>),
+  v.rawCheck(({ dataset, addIssue }) => {
+    if (!dataset.typed || !dataset.value.textCuts?.length) return;
+    const { artifact, textCuts, workingCopy } = dataset.value;
+    const matchesSource = textCuts.every(
+      (cut) => artifact.content.slice(cut.start, cut.end) === cut.quote,
+    );
+
+    if (!matchesSource || workingCopy !== applyTextCuts(artifact.content, textCuts)) {
+      addIssue({ message: "text Cuts do not match the submitted artifact and working copy" });
+    }
+  }),
+);
 
 export function validateThreadRecord(
   raw: Parameters<typeof v.safeParse>[1],