@company-semantics/contracts 51.0.0 → 51.2.0

package/src/comments/receipt.ts

@@ -0,0 +1,146 @@
+/**
+ * The application receipt — the durable proof that an accepted suggestion's
+ * edit ALREADY LANDED IN THE BODY (ADR-CONTRACTS-116, ADR-CONTRACTS-122,
+ * ADR-CONTRACTS-127).
+ *
+ * WHY THERE IS A RECEIPT AT ALL. Acceptance is apply-then-record: the edit is
+ * written into the CRDT first and the server is told afterwards, which is what
+ * makes `accepted` mean `applied` — and which opens exactly one window, between
+ * the transaction and the acknowledgement, in which the document has already
+ * changed and the thread still says `open`. A closed tab, a POST that never came
+ * back and a lost network all land in that window. The receipt closes it: it
+ * travels in the SAME transaction as the edit, so either both survived or
+ * neither did, and every client that syncs the body syncs the proof beside it.
+ * `./verify`'s no-op refusal is the other half of this same argument — a
+ * "mutation" that changes not one character would still write a receipt, and the
+ * thread would read `accepted` over a document that never received the proposal.
+ *
+ * THE KEY IS THE CONTRACT, exactly as `COMPANY_MD_COLLAB_TEXT_KEY` is for the
+ * body text (`../org/company-md-collab`). A receipt written under any other name
+ * lands in a map nobody reads while the reader observes a map nobody writes: the
+ * accept control stays live over an edit that already happened, a second apply
+ * is offered for an edit already in the body, and NOTHING ANYWHERE THROWS. One
+ * implementation can get away with spelling the name inline. Two cannot — that
+ * is the same two-independent-implementations-with-no-arbiter hazard the anchor
+ * schema is published for (ADR-CONTRACTS-116), and the receipt now has a second
+ * writer coming, so the name is spelled once, here.
+ *
+ * IT LIVES BESIDE THE BODY, NEVER INSIDE IT. This is a ROOT map on the same
+ * document as the text, not a span within the text: a receipt must never appear
+ * in the markdown source, in an export, or in the content hash. A materializer
+ * that reads the text root and nothing else is what keeps that true, and nothing
+ * here may tempt a writer into the body.
+ *
+ * ABSENCE IS NOT PROOF. A reader holding no replica holds no receipts, so an
+ * empty map means "no receipt is KNOWN HERE" and never "no receipt exists".
+ * Every consumer must therefore act on PRESENCE only; a consumer that concluded
+ * anything from silence would turn a reader that merely has no session into one
+ * that does the wrong thing rather than nothing.
+ *
+ * NO YJS HERE, DELIBERATELY — the same seam `./resolve` and `./create` hold.
+ * This module names the key and states one row's shape. Getting the map,
+ * iterating it and observing it are the consumer's, because `yjs` is an import
+ * the vocabulary-guard forbids this package from making.
+ *
+ * A LEAF, like `./suggestion`: this module imports nothing but `zod`. It has no
+ * reason to reach for the anchor or the resolution ladder, and staying a leaf
+ * means anything in this directory can import it later without a cycle.
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00941, must_log).
+ * Nothing semantic, on three counts. (1) The reference writes
+ * `z.object({...}).strict()`; what ships is `z.strictObject`, zod v4's idiom for
+ * exactly that and this directory's existing spelling (see `./anchor`'s
+ * PRD-00922 note). (2) The reference single-quotes its strings; `.prettierrc`
+ * sets `singleQuote: false`, so `pnpm format:check` rewrites them. (3) The
+ * reference writes `readSuggestionReceipt`'s signature on one line, which is 81
+ * columns against `printWidth: 80`, so Prettier reflows it onto three. A
+ * different spelling of the same schema and the same function; nothing about
+ * what is accepted or refused changed.
+ */
+import { z } from "zod";
+
+/**
+ * The root map key every application receipt is written under, keyed within
+ * that map by thread id.
+ *
+ * THIS IS THE NAME OF THE MAP, NOT A MAP. It is a single string, and the reason
+ * it is a published constant rather than an inline literal is that a typo is
+ * silent on BOTH ends — the writer's receipt lands somewhere nobody reads, and
+ * the reader watches somewhere nobody writes.
+ */
+export const SUGGESTION_RECEIPTS_MAP = "suggestionReceipts";
+
+/**
+ * What one applied suggestion left behind.
+ *
+ * STRICT, AND WITHOUT A `v` HATCH — unlike `CommentAnchorSchema` and
+ * `SuggestionSchema`, and that difference is deliberate rather than an
+ * oversight. Those two are negotiated payloads whose shapes must be able to grow
+ * while old readers keep parsing, so they version. This row is not negotiated:
+ * it is three fields that already exist, written by the shipped applier exactly
+ * as spelled here, and this module PROMOTES that convention rather than
+ * redesigning it. Adding a required `v` now would make the published parser
+ * reject every receipt currently in existence — the failure this module was
+ * written to prevent, committed by the module itself.
+ *
+ * So the three fields are closed, and a fourth fact does not arrive by widening
+ * this row. It arrives as a new key, or as a versioned successor schema that
+ * readers adopt before any writer emits it. The drop direction is why that is
+ * safe: an unrecognised row parses to `null`, which every consumer must already
+ * handle correctly, because absence is not proof and a reader with no replica
+ * sees exactly the same thing. Accepting the extras instead would surface a row
+ * this package half-understands to a decision surface, where one reader acts on
+ * the unknown field and another does not.
+ */
+export const SuggestionReceiptSchema = z.strictObject({
+  /**
+   * The claim token whose holder applied the edit, and the dedupe key for the
+   * apply itself.
+   *
+   * `min(1)` and nothing more. The backend's request boundary constrains this
+   * token to a 64-char hex string, and that constraint is already published
+   * through the generated API surface; restating it here would make a THIRD
+   * description of one token that no parity guard compares — the same call
+   * `./schemas` makes in leaving `userId` a bare `z.string()`. What this schema
+   * has to reject is a row that is not a token at all.
+   */
+  claimToken: z.string().min(1),
+  /**
+   * Wall clock at the moment the edit landed. DISPLAY ONLY — never an ordering
+   * key, never an expiry input. The lease is the monotonic one.
+   *
+   * A bare `z.number()`, which in zod v4 already refuses `NaN` and the
+   * infinities. That matters more here than for a JSON response: a CRDT map
+   * replicates raw JavaScript values, so a peer can put a literal `NaN` in this
+   * field and it will arrive as one.
+   */
+  appliedAt: z.number(),
+  /**
+   * Who applied it. A bare non-empty string rather than `.uuid()`, mirroring
+   * `./schemas`' `userId` for the same reason: the shapes in this package
+   * mirror the backend's looseness rather than tightening past it.
+   */
+  byUserId: z.string().min(1),
+});
+
+export type SuggestionReceipt = z.infer<typeof SuggestionReceiptSchema>;
+
+/**
+ * A receipt is parsed, not trusted.
+ *
+ * These values arrive over the wire from a peer and the CRDT replicates
+ * whatever was put there, with no schema of its own and no boundary in between.
+ * A row that is not three well-typed fields is therefore DROPPED rather than
+ * surfaced: a malformed receipt reaching a decision surface would withdraw a
+ * live suggestion's controls with no way back, or post a garbage claim token on
+ * every render. Returning the row's recognisable fields as a partial receipt
+ * would be the same mistake wearing a type.
+ *
+ * Total: any input, no throw, `null` for everything that is not a receipt.
+ */
+export function readSuggestionReceipt(
+  value: unknown,
+): SuggestionReceipt | null {
+  const parsed = SuggestionReceiptSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}

package/src/comments/resolve.ts

@@ -0,0 +1,261 @@
+/**
+ * Walking the ladder — the READ half of the contract the anchor writes
+ * (ADR-CONTRACTS-116, ADR-CONTRACTS-127).
+ *
+ * WHY THE INTERPRETATION IS PUBLISHED AND NOT ONLY THE SHAPE. The backend
+ * validates an anchor's shape once, at the route boundary, then stores opaque
+ * jsonb it never interprets. So the client that WROTE the anchor and the client
+ * that later RESOLVES it must agree about what these fields MEAN with no
+ * server-side arbiter between them — and a disagreement produces no error at
+ * all. The write succeeds, the read succeeds, and the highlight lands on the
+ * wrong sentence. Publishing the schema bounded that risk; publishing the
+ * resolver closes it, because a second implementation can now be an IMPORT
+ * rather than a second description.
+ *
+ * EACH RUNG EITHER ANSWERS OR DECLINES, AND A RUNG THAT CANNOT VOUCH FOR ITS
+ * ANSWER MUST DECLINE. The whole design turns on refusing rather than guessing,
+ * because the wrong answer looks exactly like the right one. Under-anchoring is
+ * the deliberate error direction: a comment shown as unanchored is legible and
+ * recoverable, while a comment shown against the wrong sentence reads as a
+ * considered objection to a paragraph its author never saw.
+ *
+ * NO YJS HERE, DELIBERATELY. Everything below is a pure function of strings and
+ * indices. Rung 1 — decoding a `Y.RelativePosition` — needs `yjs`, which the
+ * vocabulary-guard forbids this package from importing, and it is the ONE rung
+ * that needs a live replica anyway. A consumer that holds a `Y.Text` composes
+ * it on top: it tries its own rung 1 and falls through to
+ * {@link resolveAnchorFromText}, which is total and never throws. That is also
+ * what lets a comment resolve on a card with no session, no stream and no CRDT
+ * replica — and what lets the server resolve one at all.
+ *
+ * All arithmetic is in UTF-16 code units (plain JavaScript string coordinates),
+ * like every other offset on the comment path. No Unicode normalization happens
+ * anywhere here: normalising before measuring changes the length and
+ * desynchronises every offset after the first composed character.
+ */
+import { ANCHOR_CONTEXT_CHARS } from "./anchor-constants";
+import type { CommentAnchor } from "./anchor";
+
+/**
+ * Where an anchor landed.
+ *
+ * `document` is not a degraded `resolved` and `orphaned` is not an error — they
+ * are three distinct outcomes, and collapsing any pair of them loses the
+ * distinction the comment rail draws on.
+ *
+ * `rung` stays `1 | 2` even though this module can only ever emit `2`: the
+ * consumer that composes the Yjs rung on top returns `rung: 1` into this same
+ * type, and narrowing it here would force that consumer to declare a second,
+ * divergent result type — which is the two-independent-descriptions problem
+ * this domain exists to prevent.
+ */
+export type AnchorResolution =
+  | { status: "resolved"; start: number; end: number; rung: 1 | 2 }
+  | { status: "document" }
+  | { status: "orphaned" };
+
+/** Whether a needle occurs in a haystack exactly once, and where. */
+export type Occurrence =
+  | { kind: "absent" }
+  | { kind: "unique"; index: number }
+  | { kind: "ambiguous" };
+
+/**
+ * Whether `text` still reads `leftContext` immediately before `point` and
+ * `rightContext` immediately after it.
+ *
+ * The two length guards are the whole reason this is a function rather than two
+ * inline slices: `slice` reads a negative start from the END of the string and
+ * clamps a long end, so a context that CANNOT fit around `point` would be
+ * compared against an unrelated substring instead of failing. NOT FITTING IS A
+ * MISMATCH.
+ *
+ * EXPORTED because the acceptance path re-asks this question as a second,
+ * independent assertion before it writes the body (see `./verify`). A private
+ * copy there would be two descriptions of "are the contexts still there" — and
+ * the copy that forgot a length guard would compare against an unrelated
+ * substring and answer `true`, which is the one wrong answer that mutates the
+ * document.
+ */
+export function contextsMatchAt(
+  text: string,
+  point: number,
+  leftContext: string,
+  rightContext: string,
+): boolean {
+  if (point < 0 || point > text.length) return false;
+  if (point < leftContext.length) return false;
+  if (point + rightContext.length > text.length) return false;
+  return (
+    text.slice(point - leftContext.length, point) === leftContext &&
+    text.slice(point, point + rightContext.length) === rightContext
+  );
+}
+
+/**
+ * Whether `needle` occurs in `haystack` exactly once, and where.
+ *
+ * Overlapping occurrences COUNT — the second search resumes at `first + 1`, not
+ * at `first + needle.length`. A quote that overlaps itself (`"aa"` in `"aaa"`)
+ * is no less ambiguous for the overlap, and the conservative count is the one
+ * that errs toward orphaning.
+ *
+ * An EMPTY needle is `ambiguous`, never `unique`: it matches at every position,
+ * which is a fact about the search and not evidence about the point.
+ */
+export function findSoleOccurrence(
+  haystack: string,
+  needle: string,
+): Occurrence {
+  if (needle.length === 0) return { kind: "ambiguous" };
+  const first = haystack.indexOf(needle);
+  if (first === -1) return { kind: "absent" };
+  if (haystack.indexOf(needle, first + 1) !== -1) return { kind: "ambiguous" };
+  return { kind: "unique", index: first };
+}
+
+const HIGH_SURROGATE_MIN = 0xd800;
+const HIGH_SURROGATE_MAX = 0xdbff;
+const LOW_SURROGATE_MIN = 0xdc00;
+const LOW_SURROGATE_MAX = 0xdfff;
+
+/**
+ * The context preceding `index`, never opening on half a character.
+ *
+ * A fixed-width slice can land between a surrogate pair, and the lone surrogate
+ * that results is ill-formed once the anchor is encoded for the wire. Trimming
+ * costs one code unit of context and changes nothing about matching — the
+ * document contains the same code units either way.
+ *
+ * Slices {@link ANCHOR_CONTEXT_CHARS}, the CAPTURE width, which is deliberately
+ * narrower than what the schema ACCEPTS. This is a constructor helper: nothing
+ * in the ladder below calls it, and it is published here so the construction
+ * half (`./create`) and the resolution half agree about the same string work.
+ */
+export function contextBefore(text: string, index: number): string {
+  let from = Math.max(0, index - ANCHOR_CONTEXT_CHARS);
+  const code = text.charCodeAt(from);
+  if (from > 0 && code >= LOW_SURROGATE_MIN && code <= LOW_SURROGATE_MAX) {
+    from += 1;
+  }
+  return text.slice(from, index);
+}
+
+/** The context following `index`, never closing on half a character. */
+export function contextAfter(text: string, index: number): string {
+  let to = Math.min(text.length, index + ANCHOR_CONTEXT_CHARS);
+  if (to > index && to < text.length) {
+    const code = text.charCodeAt(to - 1);
+    if (code >= HIGH_SURROGATE_MIN && code <= HIGH_SURROGATE_MAX) to -= 1;
+  }
+  return text.slice(index, to);
+}
+
+/**
+ * Rung 2 for the text anchor — the context-qualified search, then the bare
+ * quote. Both refuse ambiguity; neither ever settles for a first match.
+ */
+function resolveByQuote(
+  anchor: Extract<CommentAnchor, { type: "text" }>,
+  text: string,
+): AnchorResolution {
+  const context = anchor.prefix + anchor.quote + anchor.suffix;
+  if (context !== anchor.quote) {
+    const qualified = findSoleOccurrence(text, context);
+    // Two context-qualified matches mean the context FAILED to identify a
+    // candidate. Binding to the first would be the guess this ladder exists to
+    // forbid, and falling back to the bare quote here would only re-ask a
+    // question already known to be ambiguous.
+    if (qualified.kind === "ambiguous") return { status: "orphaned" };
+    if (qualified.kind === "unique") {
+      const start = qualified.index + anchor.prefix.length;
+      return {
+        status: "resolved",
+        start,
+        end: start + anchor.quote.length,
+        rung: 2,
+      };
+    }
+    // Absent: the surrounding sentence was edited but the quote itself may have
+    // survived. Fall through.
+  }
+
+  const bare = findSoleOccurrence(text, anchor.quote);
+  if (bare.kind !== "unique") return { status: "orphaned" };
+  return {
+    status: "resolved",
+    start: bare.index,
+    end: bare.index + anchor.quote.length,
+    rung: 2,
+  };
+}
+
+/**
+ * Rung 2 for the zero-width variant — find the seam the two contexts spell out
+ * when the caret between them is closed up, and resolve ONLY if it is unique.
+ *
+ * A repeated seam is the insertion anchor's version of a repeated quote, and it
+ * gets the same answer: `orphaned`. "Insert at the first `item done`" is the
+ * shortcut this rung exists to forbid — in a list of identical rows it is wrong
+ * two times out of three, and it never looks wrong.
+ */
+function resolveInsertionBySeam(
+  anchor: Extract<CommentAnchor, { type: "text-insertion" }>,
+  text: string,
+): AnchorResolution {
+  const { leftContext, rightContext } = anchor;
+  const seam = leftContext + rightContext;
+
+  if (seam === "") {
+    // Only authorable on an EMPTY document, where 0 is the one point there is.
+    // Once the document has text that anchor says nothing about WHERE among it
+    // the caret belongs — and an empty needle matches everywhere, which is a
+    // fact about the search and not evidence about the point.
+    //
+    // Not redundant with `findSoleOccurrence`'s empty-needle refusal below:
+    // this branch is reached first, and it is the one that makes "the only
+    // point an empty document has" resolvable at all.
+    return text.length === 0
+      ? { status: "resolved", start: 0, end: 0, rung: 2 }
+      : { status: "orphaned" };
+  }
+
+  const seen = findSoleOccurrence(text, seam);
+  if (seen.kind !== "unique") return { status: "orphaned" };
+  const point = seen.index + leftContext.length;
+  return { status: "resolved", start: point, end: point, rung: 2 };
+}
+
+/**
+ * Resolve `anchor` against the current `text`, using nothing but the text.
+ *
+ * TOTAL AND NEVER THROWS: every input produces one of the three outcomes, which
+ * is what lets a consumer use it as the floor of its own ladder without a
+ * try/catch or a null check.
+ *
+ * `text` is the coordinate space the caller will paint into — the live
+ * `Y.Text`'s contents where a session is attached, the materialized document
+ * body where it is not. A consumer that holds a `Y.Text` tries its own
+ * relative-position rung FIRST and calls this when that rung declines; the
+ * geometry both paths produce must be identical, or two people looking at the
+ * same document disagree about where a comment sits.
+ *
+ * The three outcomes, by variant:
+ *   - `document` — the thread hangs off the subject AS A WHOLE. It draws no
+ *     highlight, but it is correctly anchored; reporting it as `orphaned` would
+ *     put it behind the rail's "this text is gone" affordance.
+ *   - `text` — {@link resolveByQuote}: the context-qualified string first, the
+ *     bare quote as the fallback, ambiguity orphaned at BOTH levels.
+ *   - `text-insertion` — {@link resolveInsertionBySeam}: the unique
+ *     `leftContext`+`rightContext` seam, and nothing else. Always zero-width.
+ */
+export function resolveAnchorFromText(
+  anchor: CommentAnchor,
+  text: string,
+): AnchorResolution {
+  if (anchor.type === "document") return { status: "document" };
+  if (anchor.type === "text-insertion") {
+    return resolveInsertionBySeam(anchor, text);
+  }
+  return resolveByQuote(anchor, text);
+}

package/src/comments/schemas.ts

@@ -110,11 +110,14 @@ export type CommentMention = z.infer<typeof CommentMentionSchema>;
  * One comment as the app renders it.
  *
  * THE REDACTION INVARIANT: `body` is null EXACTLY WHEN `deletedAt` is set, and a
- * soft-deleted comment also arrives with `mentions` empty. A deleted comment is
- * a REDACTED PROJECTION, not a removed row — the tombstone keeps its position in
- * the (createdAt ASC, id ASC) sequence, so replies above and below it still read
- * in order, and a thread whose comments were all deleted stays distinguishable
- * from a thread that never had any.
+ * soft-deleted comment also arrives with `mentions` empty.
+ *
+ * WHERE A REDACTED COMMENT ACTUALLY APPEARS is narrower than it once was, and
+ * this docblock used to overstate it. The redacted projection is the DELETE
+ * acknowledgement — the response to the caller who performed the delete, telling
+ * them what they destroyed. It is NOT a row in a thread listing: ADR-BE-545 has
+ * the read omit deleted comments outright, and drop a comment-kind thread once
+ * nothing live is left on it. A reader never sees a tombstone in a conversation.
  *
  * The invariant is DOCUMENTED here and enforced by the writer, not by a Zod
  * refinement. A refinement would make this package refuse a response the server
@@ -166,6 +169,18 @@ export type CommentProjection = z.infer<typeof CommentSchema>;
  * would make this package refuse a response the server is willing to emit and
  * would be a third wire description no parity guard can check.
  *
+ * `lastAnchoredOffset` IS NOT AN ANCHOR. It is a source offset recording where
+ * this thread's passage USED TO BE, reported by the client that watched the
+ * passage disappear (ADR-BE-548). It exists so a client can keep an ORPHANED
+ * thread in the reader's list where the conversation happened, instead of piling
+ * every one of them at the top — and it may be used for NOTHING ELSE. It must
+ * never yield a range, and nothing may place a highlight, a decoration or a
+ * leader line from it: a comment shown against the wrong sentence is strictly
+ * worse than one shown as unanchored (ADR-APP-120), and that ordering is what
+ * bounds this field. `null` is ordinary — it means no client has watched this
+ * thread's passage go — and the value is WRITE-ONCE on the server, so it records
+ * the first sighting and never a correction.
+ *
  * THE TWO-LEVEL STATUS MODEL: `status` stays exactly `open | resolved`
  * (`COMMENT_THREAD_STATUSES` is NOT widened — widening a closed published enum
  * is a parse outage for every deployed client). A decided suggestion arrives as
@@ -185,6 +200,7 @@ export const CommentThreadSummarySchema = z.object({
   createdByUserId: z.string().nullable(),
   resolvedByUserId: z.string().nullable(),
   resolvedAt: z.string().nullable(),
+  lastAnchoredOffset: z.number().int().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -193,9 +209,12 @@ export type CommentThreadSummary = z.infer<typeof CommentThreadSummarySchema>;
 /**
  * A thread with ALL its comments, oldest-first by (createdAt ASC, id ASC).
  *
- * Soft-deleted comments appear REDACTED, never filtered out — filtering them
- * would renumber the conversation under the reader and make "…replying to the
- * comment above" false.
+ * DELETED COMMENTS ARE OMITTED, NOT REDACTED. This once said the opposite, and
+ * the prose outlived the rule: ADR-BE-545 made the read drop deleted comments
+ * entirely, and drop a comment-kind thread once nothing live is left on it —
+ * deleting the comment that IS a thread deletes the thread with it, so the reply
+ * order a redacted row used to hold open no longer has anything to hold. The
+ * wire SHAPE is unchanged either way; what changed is which rows arrive.
  */
 export const CommentThreadSchema = CommentThreadSummarySchema.extend({
   comments: z.array(CommentSchema),

package/src/comments/verify.ts

@@ -0,0 +1,128 @@
+/**
+ * The two questions asked BEFORE the body is written — is the passage still
+ * what the anchor says it is, and what edit does this op make of that range?
+ * (ADR-CONTRACTS-122, ADR-CONTRACTS-127.)
+ *
+ * WHY THESE ARE PUBLISHED AT ALL. Both are total functions of their arguments —
+ * no `Y.Text`, no clock, no lease, nothing touching a sanctioned-mutation
+ * window. The app's own applier records that as the property that makes them
+ * "the only part of the applier that can be lifted out of it": the depth
+ * counter and the lease have to stay in one module, because an exported pair
+ * that opened and closed that window would be a generic bypass. What is left
+ * once they are removed is exactly this file — and once it is an import rather
+ * than a second description, a NON-BROWSER applier (the server, a comment pass)
+ * becomes possible without a second answer to "did this suggestion still apply".
+ *
+ * THE APPLIER MUST NOT TRUST THE FINDER. {@link anchorStillReads} is a SECOND
+ * assertion, independent of {@link resolveAnchorFromText} by construction: it
+ * reads the anchor's own stored evidence against the live text and takes the
+ * resolution only as a position. That a rung already checked something like it
+ * does not make it redundant — the rung answers "where does this land", this
+ * answers "is what lands there still the thing", and a consumer that composes
+ * its own Yjs rung on top supplies a position this module never saw.
+ *
+ * All arithmetic is in UTF-16 code units, like every other offset on the
+ * comment path, and no Unicode normalization happens here.
+ */
+import type { CommentAnchor } from "./anchor";
+import { contextsMatchAt, type AnchorResolution } from "./resolve";
+import type { Suggestion } from "./suggestion";
+
+/**
+ * A resolution that actually named a range.
+ *
+ * Narrowed from {@link AnchorResolution} rather than restated, so a consumer
+ * composing the Yjs rung on top hands its own `rung: 1` answer straight in.
+ */
+type Resolved = Extract<AnchorResolution, { status: "resolved" }>;
+
+/** One text mutation: delete `deleteLength` at `at`, then insert `insert`. */
+export interface PlannedEdit {
+  readonly at: number;
+  readonly deleteLength: number;
+  readonly insert: string;
+}
+
+/**
+ * Does the resolved place still hold what the anchor says it holds?
+ *
+ * By variant:
+ *   - `text` — the live slice must still be the stored `quote`, exactly. Not a
+ *     prefix of it, not a normalized form of it.
+ *   - `text-insertion` — the resolution must still be ZERO-WIDTH, and both
+ *     contexts must still meet at that point ({@link contextsMatchAt}, imported
+ *     rather than re-derived: a private copy that forgot a length guard would
+ *     compare against an unrelated substring and answer `true`, which is the
+ *     one wrong answer that mutates the document).
+ *   - `document` — `false`. A whole-document anchor makes no claim about a
+ *     range, so it can never vouch for one. Unreachable through the shipped
+ *     ladder, which answers `{ status: "document" }` for that variant and never
+ *     a `resolved` — but a consumer's own rung can hand one in, and the refusal
+ *     is what makes that harmless.
+ */
+export function anchorStillReads(
+  anchor: CommentAnchor,
+  text: string,
+  resolution: Resolved,
+): boolean {
+  if (anchor.type === "text") {
+    return text.slice(resolution.start, resolution.end) === anchor.quote;
+  }
+  if (anchor.type === "text-insertion") {
+    return (
+      resolution.start === resolution.end &&
+      contextsMatchAt(
+        text,
+        resolution.start,
+        anchor.leftContext,
+        anchor.rightContext,
+      )
+    );
+  }
+  return false;
+}
+
+/**
+ * What this op does to that range — or `null` when it would do nothing.
+ *
+ * Derived from the CANONICAL suggestion payload, never from a caller's
+ * restatement of it: that seam is where "accept this suggestion" would quietly
+ * become "apply something like it".
+ *
+ * A NO-OP IS A REFUSAL, NOT A CHEAP SUCCESS. An `insert` carrying no text, or a
+ * `delete` over a collapsed range, would run a transaction that writes a
+ * receipt and changes not one character — the thread would go to `accepted`
+ * over a document that never received the proposal, which is the invariant pair
+ * read backwards. Both shapes mean the payload and the anchor disagree about
+ * what kind of edit this is, and that disagreement is not this module's to
+ * settle.
+ *
+ * `insert` lands at `end`, matching where the redline draws the proposed text,
+ * so the diff the user accepted and the edit they get agree about the seam.
+ *
+ * The switch is exhaustive over {@link Suggestion}'s `op` with NO default arm:
+ * a fourth op must arrive as a type error here rather than be absorbed as a
+ * silent `undefined` return.
+ */
+export function plannedEdit(
+  suggestion: Suggestion,
+  resolution: Resolved,
+): PlannedEdit | null {
+  const insert = suggestion.insertedText ?? "";
+  const span = resolution.end - resolution.start;
+
+  switch (suggestion.op) {
+    case "insert":
+      return insert === ""
+        ? null
+        : { at: resolution.end, deleteLength: 0, insert };
+    case "delete":
+      return span === 0
+        ? null
+        : { at: resolution.start, deleteLength: span, insert: "" };
+    case "replace":
+      return span === 0 || insert === ""
+        ? null
+        : { at: resolution.start, deleteLength: span, insert };
+  }
+}