@company-semantics/contracts 51.1.0 → 51.2.0

package/src/comments/__tests__/resolve.test.ts

@@ -0,0 +1,391 @@
+/**
+ * The published resolver, held to the corpus it must agree with.
+ *
+ * WHAT THIS SUITE EXISTS TO KILL. The plausible-looking wrong resolver returns
+ * the FIRST match. It passes every "the quote is still there" test, it never
+ * throws, and it is wrong precisely when the document is repetitive — which is
+ * when comments matter most. Its symptom is not a broken highlight but a
+ * confident one, on a paragraph the comment's author never saw. Every
+ * `orphaned` expectation below is a case where that resolver returns a
+ * well-formed range, so a suite that only asserted the happy path would sit
+ * green over it.
+ *
+ * The second wrong resolver collapses `document` into `orphaned` — a thread on
+ * the subject AS A WHOLE draws no highlight either way, so the bug is invisible
+ * until the rail files it behind "this text is gone".
+ *
+ * THE TEXT-INSERTION BLOCK IS DRIVEN BY THE PINNED CORPUS, not by hand-copied
+ * cases. `./fixtures/comment-anchors.json` carries a `document` and an
+ * `expectedResolution` on each text-insertion accept row: ground truth for
+ * exactly this module, recorded contracts-first in PRD-00933. `anchor-corpus`
+ * re-derives those outcomes with its own seam scan; this suite drives the
+ * SHIPPED resolver over the same rows, which is what turns that hand-rolled
+ * cross-check into a check of the implementation rather than of itself. The
+ * corpus is read, never edited — its digest is pinned beside it.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { ANCHOR_CONTEXT_CHARS } from "../anchor-constants.js";
+import { CommentAnchorSchema } from "../anchor.js";
+import {
+  contextAfter,
+  contextBefore,
+  contextsMatchAt,
+  findSoleOccurrence,
+  resolveAnchorFromText,
+} from "../resolve.js";
+
+/** One named case from the corpus. */
+interface AnchorCase {
+  name: string;
+  anchor: unknown;
+}
+
+/** The additive fields the text-insertion rows carry beside `anchor`. */
+interface InsertionFixture extends AnchorCase {
+  anchor: { type: "text-insertion" };
+  document: string;
+  expectedResolution:
+    { outcome: "resolved"; offset: number } | { outcome: "orphaned" };
+}
+
+const isInsertionFixture = (c: AnchorCase): c is InsertionFixture => {
+  const anchor = c.anchor as { type?: unknown } | null;
+  return anchor !== null && anchor?.type === "text-insertion";
+};
+
+/**
+ * Read from disk rather than imported: `src/tsconfig.json` sets no
+ * `resolveJsonModule`, so a JSON import would fail the build the moment
+ * anything the typechecker reaches loaded it.
+ */
+const CORPUS_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "fixtures",
+  "comment-anchors.json",
+);
+const corpus = JSON.parse(readFileSync(CORPUS_PATH, "utf8")) as {
+  accept: AnchorCase[];
+  reject: AnchorCase[];
+};
+
+/** Parse through the published schema, so no fixture reaches the resolver
+ * having skipped the boundary a real anchor cannot skip. */
+const parsed = (anchor: unknown) => CommentAnchorSchema.parse(anchor);
+
+const textAnchor = (fields: {
+  quote: string;
+  prefix: string;
+  suffix: string;
+}) => parsed({ type: "text", v: 1, ...fields });
+
+const insertionAnchor = (fields: {
+  leftContext: string;
+  rightContext: string;
+}) => parsed({ type: "text-insertion", v: 1, ...fields });
+
+describe("resolveAnchorFromText against the pinned insertion corpus", () => {
+  const insertionCases = corpus.accept.filter(isInsertionFixture);
+
+  it("has the four recorded insertion fixtures, so the loop cannot pass vacuously", () => {
+    // An empty array iterates cleanly and reports as a passing suite. Position
+    // 0, document end, ambiguous repeated seam, surrogate-pair flanked.
+    expect(insertionCases.length).toBeGreaterThanOrEqual(4);
+  });
+
+  for (const { name, anchor, document, expectedResolution } of insertionCases) {
+    it(`resolves ${name} exactly as the corpus records`, () => {
+      const resolution = resolveAnchorFromText(parsed(anchor), document);
+
+      if (expectedResolution.outcome === "resolved") {
+        // Whole-object, including the rung: a rung-2 answer reported as rung 1
+        // is the bug, and an insertion resolution is always zero-width.
+        expect(resolution).toEqual({
+          status: "resolved",
+          start: expectedResolution.offset,
+          end: expectedResolution.offset,
+          rung: 2,
+        });
+      } else {
+        expect(resolution).toEqual({ status: "orphaned" });
+      }
+    });
+  }
+
+  it("resolves the surrogate-flanked seam between the pairs, not inside one", () => {
+    // The corpus row carries a `relPos` encoded against another document. This
+    // module has no Y.Text in reach and correctly ignores it, so the seam has
+    // to carry the anchor on its own — and 11 is a UTF-16 code-unit offset
+    // BETWEEN two astral pairs, where a code-point walk would land on 9.
+    const document = "Q3 goals 🎯🚀 shipped early";
+    const anchor = parsed({
+      type: "text-insertion",
+      v: 1,
+      relPos: "AQLmzsvNAgA=",
+      leftContext: "goals 🎯",
+      rightContext: "🚀 shipped",
+    });
+
+    expect(resolveAnchorFromText(anchor, document)).toEqual({
+      status: "resolved",
+      start: 11,
+      end: 11,
+      rung: 2,
+    });
+    expect(document.slice(0, 11)).toBe("Q3 goals 🎯");
+  });
+});
+
+describe("resolveAnchorFromText — ambiguity resolves orphaned, never the first match", () => {
+  it("orphans an anchor whose quote occurs ambiguously", () => {
+    // No context to disambiguate with, and the quote repeats. A first-match
+    // implementation returns index 3 here and is silently wrong half the time.
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+    const text = "Is the plan agreed? We ship the plan on Friday.";
+
+    expect(resolveAnchorFromText(anchor, text)).toEqual({ status: "orphaned" });
+  });
+
+  it("orphans when even the context-qualified match is ambiguous", () => {
+    const anchor = textAnchor({
+      quote: "beta",
+      prefix: "alpha ",
+      suffix: " gamma",
+    });
+    const text = "alpha beta gamma / alpha beta gamma";
+
+    // Two context matches mean the CONTEXT failed to identify a candidate.
+    // Binding to the first occurrence — or quietly retrying the bare quote,
+    // which is equally ambiguous — is the shortcut this ladder forbids.
+    expect(resolveAnchorFromText(anchor, text)).toEqual({ status: "orphaned" });
+  });
+
+  it("resolves via context when the bare quote alone would be ambiguous", () => {
+    const anchor = textAnchor({ quote: "beta", prefix: "alpha ", suffix: "" });
+    const text = "zeta beta gamma / alpha beta gamma";
+
+    // The SECOND "beta" — the one the context identifies. This is the positive
+    // twin of the rule above: context DISAMBIGUATES, it does not merely veto.
+    expect(resolveAnchorFromText(anchor, text)).toEqual({
+      status: "resolved",
+      start: text.lastIndexOf("beta"),
+      end: text.lastIndexOf("beta") + "beta".length,
+      rung: 2,
+    });
+  });
+
+  it("falls back to the bare quote when the surrounding sentence was rewritten", () => {
+    const anchor = textAnchor({
+      quote: "materially understated",
+      prefix: "Q3 revenue was ",
+      suffix: " in the board pack.",
+    });
+    const text = "The figure was materially understated, we now believe.";
+
+    // Context ABSENT is not context AMBIGUOUS: the sentence moved, the quote
+    // survived, and a unique bare quote is still evidence enough.
+    expect(resolveAnchorFromText(anchor, text)).toEqual({
+      status: "resolved",
+      start: text.indexOf("materially understated"),
+      end:
+        text.indexOf("materially understated") +
+        "materially understated".length,
+      rung: 2,
+    });
+  });
+
+  it("counts overlapping occurrences as ambiguous", () => {
+    // "aa" occurs at 0 AND at 1. Resuming the second search at
+    // `first + needle.length` would miss the overlap and call this unique.
+    const anchor = textAnchor({ quote: "aa", prefix: "", suffix: "" });
+
+    expect(resolveAnchorFromText(anchor, "aaa")).toEqual({
+      status: "orphaned",
+    });
+  });
+
+  it("orphans when the quote is gone entirely", () => {
+    const anchor = textAnchor({
+      quote: "the original wording",
+      prefix: "before ",
+      suffix: " after",
+    });
+
+    expect(
+      resolveAnchorFromText(anchor, "Nothing of the sort remains."),
+    ).toEqual({ status: "orphaned" });
+  });
+});
+
+describe("resolveAnchorFromText — the insertion seam refuses ambiguity", () => {
+  it("orphans a repeated seam rather than taking the first row", () => {
+    const document = "item done, item done, item done";
+    const anchor = insertionAnchor({
+      leftContext: "item ",
+      rightContext: "done",
+    });
+
+    // A first-match resolver returns a perfectly well-formed caret at 5 here,
+    // two rows away from where the suggestion was written.
+    expect(document.indexOf("item done")).toBe(0);
+    expect(resolveAnchorFromText(anchor, document)).toEqual({
+      status: "orphaned",
+    });
+  });
+
+  it("orphans when the seam is gone entirely", () => {
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan.",
+    });
+
+    expect(
+      resolveAnchorFromText(anchor, "Nothing here resembles that sentence."),
+    ).toEqual({ status: "orphaned" });
+  });
+
+  it("resolves the empty seam on an empty document and orphans it once there is text", () => {
+    const anchor = insertionAnchor({ leftContext: "", rightContext: "" });
+
+    // On the empty document the anchor is complete and 0 is the only answer —
+    // the one case an empty seam is authorable at all.
+    expect(resolveAnchorFromText(anchor, "")).toEqual({
+      status: "resolved",
+      start: 0,
+      end: 0,
+      rung: 2,
+    });
+    // Once there is text it says nothing about WHERE among it the caret goes.
+    expect(
+      resolveAnchorFromText(anchor, "The board approved the plan."),
+    ).toEqual({ status: "orphaned" });
+  });
+
+  it("always resolves zero-width", () => {
+    const document = "We agreed to ship the quarterly goals.";
+    const anchor = insertionAnchor({
+      leftContext: "ship ",
+      rightContext: "the quarterly",
+    });
+
+    const resolution = resolveAnchorFromText(anchor, document);
+    expect(resolution.status).toBe("resolved");
+    if (resolution.status !== "resolved") return;
+    // A zero-width point that resolved to a RANGE would paint a highlight over
+    // text the suggestion never claimed.
+    expect(resolution.start).toBe(resolution.end);
+  });
+});
+
+describe("resolveAnchorFromText — the document anchor", () => {
+  it("reports a document anchor as document, never orphaned", () => {
+    const anchor = parsed({ type: "document", v: 1 });
+
+    // A thread on the subject AS A WHOLE draws no highlight, but it is
+    // correctly anchored — calling it orphaned would put it behind the rail's
+    // "this text is gone" affordance.
+    expect(resolveAnchorFromText(anchor, "any text at all")).toEqual({
+      status: "document",
+    });
+    expect(resolveAnchorFromText(anchor, "")).toEqual({ status: "document" });
+  });
+});
+
+describe("findSoleOccurrence", () => {
+  it("reports a lone occurrence with its index", () => {
+    expect(findSoleOccurrence("the plan is agreed", "plan")).toEqual({
+      kind: "unique",
+      index: 4,
+    });
+  });
+
+  it("reports an absent needle as absent, distinctly from ambiguous", () => {
+    // The resolver treats these two differently at the context level: absent
+    // falls through to the bare quote, ambiguous orphans immediately.
+    expect(findSoleOccurrence("the plan", "budget")).toEqual({
+      kind: "absent",
+    });
+  });
+
+  it("treats an empty needle as ambiguous, never as a match at 0", () => {
+    // `indexOf("")` is 0 on every string, so an implementation without this
+    // guard reports a confident unique match at the start of the document.
+    expect(findSoleOccurrence("the plan", "")).toEqual({ kind: "ambiguous" });
+    expect(findSoleOccurrence("", "")).toEqual({ kind: "ambiguous" });
+  });
+});
+
+describe("contextsMatchAt", () => {
+  const text = "The board approved the plan.";
+
+  it("confirms the contexts that actually surround the point", () => {
+    expect(contextsMatchAt(text, 19, "approved ", "the plan.")).toBe(true);
+  });
+
+  it("refuses a context that cannot FIT before the point", () => {
+    // THE LOAD-BEARING GUARD. `slice` reads a negative start from the END of
+    // the string, so without it "approved " would be compared against a
+    // substring taken from the far end and could answer true.
+    expect(contextsMatchAt(text, 2, "approved ", "e board")).toBe(false);
+  });
+
+  it("refuses a context that cannot FIT after the point", () => {
+    // The mirror case: `slice` CLAMPS a long end rather than failing.
+    expect(contextsMatchAt(text, text.length - 2, "n.", "the plan.")).toBe(
+      false,
+    );
+  });
+
+  it("refuses an out-of-bounds point outright", () => {
+    expect(contextsMatchAt(text, -1, "", "")).toBe(false);
+    expect(contextsMatchAt(text, text.length + 1, "", "")).toBe(false);
+  });
+
+  it("answers true at every in-bounds point for two empty contexts", () => {
+    // Not a bug — a fact about the question. It is why a consumer's
+    // relative-position rung must refuse an anchor with no contexts BEFORE it
+    // decodes anything, rather than treating this check as evidence.
+    expect(contextsMatchAt(text, 0, "", "")).toBe(true);
+    expect(contextsMatchAt(text, 7, "", "")).toBe(true);
+  });
+});
+
+describe("contextBefore / contextAfter", () => {
+  it("captures at most ANCHOR_CONTEXT_CHARS, the capture width", () => {
+    const text = "x".repeat(200);
+
+    // The CAPTURE width, deliberately narrower than what the schema ACCEPTS —
+    // capturing to the accept bound would leave a constructor no headroom.
+    expect(contextBefore(text, 150)).toHaveLength(ANCHOR_CONTEXT_CHARS);
+    expect(contextAfter(text, 50)).toHaveLength(ANCHOR_CONTEXT_CHARS);
+  });
+
+  it("clamps at the document edges instead of running off them", () => {
+    expect(contextBefore("short", 3)).toBe("sho");
+    expect(contextAfter("short", 3)).toBe("rt");
+    expect(contextBefore("short", 0)).toBe("");
+    expect(contextAfter("short", 5)).toBe("");
+  });
+
+  it("never opens on half a character", () => {
+    // The fixed-width slice would start exactly between the pair's two code
+    // units; the lone low surrogate that results is ill-formed on the wire.
+    const text = "🎯" + "a".repeat(ANCHOR_CONTEXT_CHARS - 1);
+    const before = contextBefore(text, text.length);
+
+    expect(before).toBe("a".repeat(ANCHOR_CONTEXT_CHARS - 1));
+    expect(before.charCodeAt(0)).toBeLessThan(0xd800);
+  });
+
+  it("never closes on half a character", () => {
+    const text = "a".repeat(ANCHOR_CONTEXT_CHARS - 1) + "🎯tail";
+    const after = contextAfter(text, 0);
+
+    // Trimming costs one code unit of context and changes nothing about
+    // matching — the document holds the same code units either way.
+    expect(after).toBe("a".repeat(ANCHOR_CONTEXT_CHARS - 1));
+  });
+});

package/src/comments/__tests__/verify.test.ts

@@ -0,0 +1,262 @@
+/**
+ * The two total functions the acceptance path runs before it writes.
+ *
+ * WHAT THIS SUITE EXISTS TO KILL. The plausible-looking wrong `plannedEdit`
+ * returns a well-formed edit for the no-op cases — `{ at, deleteLength: 0,
+ * insert: "" }` is a perfectly valid mutation, it applies without error, and it
+ * changes not one character. Its symptom is not a crash but a thread reported
+ * as `accepted` over a document that never received the proposal: the receipt
+ * says the edit landed, the body says it did not, and nothing anywhere throws.
+ * Every `toBeNull()` below is a case where that implementation returns an
+ * object, so a suite asserting only the three happy ops would sit green over it.
+ *
+ * The second wrong implementation is an `anchorStillReads` that answers `true`
+ * for a `document` anchor — "there is nothing to check, so nothing is wrong".
+ * That turns the whole-document thread, the one variant that names no
+ * characters at all, into a licence to rewrite whichever range the caller
+ * happened to pass.
+ *
+ * The third is an `anchorStillReads` that trusts the resolution instead of
+ * re-reading the text. It is invisible while the ladder is right and catastrophic
+ * exactly when it is not — which is the case this second assertion exists for.
+ */
+import { describe, expect, it } from "vitest";
+
+import { CommentAnchorSchema } from "../anchor.js";
+import { resolveAnchorFromText } from "../resolve.js";
+import { SuggestionSchema } from "../suggestion.js";
+import { anchorStillReads, plannedEdit } from "../verify.js";
+
+/** Parse through the published schemas, so no fixture reaches these functions
+ * having skipped a boundary a real payload cannot skip. */
+const parsedAnchor = (anchor: unknown) => CommentAnchorSchema.parse(anchor);
+
+const textAnchor = (fields: {
+  quote: string;
+  prefix: string;
+  suffix: string;
+}) => parsedAnchor({ type: "text", v: 1, ...fields });
+
+const insertionAnchor = (fields: {
+  leftContext: string;
+  rightContext: string;
+}) => parsedAnchor({ type: "text-insertion", v: 1, ...fields });
+
+const suggestion = (fields: { op: string; insertedText?: string }) =>
+  SuggestionSchema.parse({ v: 1, status: "open", ...fields });
+
+/** A resolution over `quote` in `text`, obtained from the SHIPPED resolver so
+ * the geometry under test is the geometry the ladder actually produces. */
+const resolveText = (text: string, quote: string) => {
+  const resolution = resolveAnchorFromText(
+    textAnchor({ quote, prefix: "", suffix: "" }),
+    text,
+  );
+  if (resolution.status !== "resolved") throw new Error("fixture unresolved");
+  return resolution;
+};
+
+describe("anchorStillReads — the second assertion, not the ladder's word", () => {
+  const text = "The board approved the plan on Friday.";
+
+  it("confirms a text anchor whose slice is still exactly the quote", () => {
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+
+    expect(anchorStillReads(anchor, text, resolveText(text, "the plan"))).toBe(
+      true,
+    );
+  });
+
+  it("refuses a resolution whose slice no longer equals the quote", () => {
+    // The one-field mutation: the same well-formed resolution, shifted by one.
+    // An implementation that trusted the finder answers true here and rewrites
+    // a range off by a character from the one the author selected.
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+    const resolution = resolveText(text, "the plan");
+
+    expect(
+      anchorStillReads(anchor, text, {
+        ...resolution,
+        start: resolution.start + 1,
+        end: resolution.end + 1,
+      }),
+    ).toBe(false);
+  });
+
+  it("refuses a slice that merely CONTAINS the quote", () => {
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+    const resolution = resolveText(text, "the plan");
+
+    expect(
+      anchorStillReads(anchor, text, {
+        ...resolution,
+        end: resolution.end + 3,
+      }),
+    ).toBe(false);
+  });
+
+  it("confirms an insertion point whose two contexts still meet there", () => {
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan",
+    });
+    const resolution = resolveAnchorFromText(anchor, text);
+    expect(resolution.status).toBe("resolved");
+    if (resolution.status !== "resolved") return;
+
+    expect(anchorStillReads(anchor, text, resolution)).toBe(true);
+  });
+
+  it("refuses an insertion resolution that is not zero-width", () => {
+    // A zero-width anchor handed a RANGE means whoever produced it lost the
+    // distinction between a caret and a selection — and the edit that follows
+    // would delete text no suggestion claimed.
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan",
+    });
+    const resolution = resolveAnchorFromText(anchor, text);
+    if (resolution.status !== "resolved") throw new Error("fixture unresolved");
+
+    expect(
+      anchorStillReads(anchor, text, {
+        ...resolution,
+        end: resolution.end + 4,
+      }),
+    ).toBe(false);
+  });
+
+  it("refuses an insertion point whose contexts no longer surround it", () => {
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan",
+    });
+
+    expect(
+      anchorStillReads(anchor, text, {
+        status: "resolved",
+        start: 4,
+        end: 4,
+        rung: 2,
+      }),
+    ).toBe(false);
+  });
+
+  it("refuses a document anchor, which vouches for no range at all", () => {
+    // Unreachable through the shipped ladder — it answers { status: "document" }
+    // for this variant — so the resolution is built by hand, exactly as a
+    // consumer's own rung could hand one in. The refusal is what makes that
+    // harmless rather than a licence to rewrite an arbitrary range.
+    const anchor = parsedAnchor({ type: "document", v: 1 });
+
+    expect(
+      anchorStillReads(anchor, text, {
+        status: "resolved",
+        start: 0,
+        end: text.length,
+        rung: 2,
+      }),
+    ).toBe(false);
+    expect(resolveAnchorFromText(anchor, text)).toEqual({ status: "document" });
+  });
+});
+
+describe("plannedEdit — the mutation each op makes of the resolved range", () => {
+  const text = "The board approved the plan on Friday.";
+  const resolution = resolveText(text, "the plan");
+
+  it("inserts at END, where the redline draws the proposed text", () => {
+    // At `start` the inserted text would land BEFORE the quote, on the other
+    // side of the seam from the one the accepting user was shown.
+    expect(
+      plannedEdit(
+        suggestion({ op: "insert", insertedText: " urgently" }),
+        resolution,
+      ),
+    ).toEqual({ at: resolution.end, deleteLength: 0, insert: " urgently" });
+  });
+
+  it("deletes exactly the resolved span and inserts nothing", () => {
+    expect(plannedEdit(suggestion({ op: "delete" }), resolution)).toEqual({
+      at: resolution.start,
+      deleteLength: resolution.end - resolution.start,
+      insert: "",
+    });
+  });
+
+  it("replaces the resolved span with the payload's text", () => {
+    expect(
+      plannedEdit(
+        suggestion({ op: "replace", insertedText: "the revised plan" }),
+        resolution,
+      ),
+    ).toEqual({
+      at: resolution.start,
+      deleteLength: resolution.end - resolution.start,
+      insert: "the revised plan",
+    });
+  });
+
+  it("derives the span from the resolution, never from the quote's length", () => {
+    // A zero-width insertion resolution: `end - start` is 0, and the arithmetic
+    // must come from the position it was actually given.
+    const point = { status: "resolved", end: 9, start: 9, rung: 2 } as const;
+
+    expect(
+      plannedEdit(suggestion({ op: "insert", insertedText: "duly " }), point),
+    ).toEqual({ at: 9, deleteLength: 0, insert: "duly " });
+  });
+});
+
+describe("plannedEdit — a no-op is a refusal, not a cheap success", () => {
+  const text = "The board approved the plan on Friday.";
+  const span = resolveText(text, "the plan");
+  const collapsed = {
+    status: "resolved",
+    start: 19,
+    end: 19,
+    rung: 2,
+  } as const;
+
+  it("refuses an insert whose payload carries no text", () => {
+    // The READ schema keeps `insertedText` optional so a delete payload parses
+    // without it, which means an insert payload missing it arrives intact and
+    // reaches here. It proposes nothing; accepting it would mark the thread
+    // applied over a body that never changed.
+    expect(plannedEdit(suggestion({ op: "insert" }), span)).toBeNull();
+  });
+
+  it("refuses an insert whose payload carries an empty string", () => {
+    // One field of a well-formed payload, emptied. The schema refuses this at
+    // the boundary (min(1)); this function refuses it again, because the
+    // boundary is not the only door into an applier.
+    const emptied = {
+      ...suggestion({ op: "insert", insertedText: "x" }),
+      insertedText: "",
+    };
+
+    expect(plannedEdit(emptied, span)).toBeNull();
+  });
+
+  it("refuses a delete over a collapsed range", () => {
+    // The wrong implementation returns { at: 19, deleteLength: 0, insert: "" }
+    // here — a valid mutation that removes nothing.
+    expect(plannedEdit(suggestion({ op: "delete" }), collapsed)).toBeNull();
+  });
+
+  it("refuses a replace over a collapsed range", () => {
+    expect(
+      plannedEdit(
+        suggestion({ op: "replace", insertedText: "something" }),
+        collapsed,
+      ),
+    ).toBeNull();
+  });
+
+  it("refuses a replace whose payload carries no text", () => {
+    // Not a delete in disguise: the payload and the anchor disagree about what
+    // kind of edit this is, and settling that disagreement is not this
+    // function's job.
+    expect(plannedEdit(suggestion({ op: "replace" }), span)).toBeNull();
+  });
+});