@company-semantics/contracts 48.0.0 → 49.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "48.0.0",
+  "version": "49.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/comments/README.md

@@ -36,6 +36,22 @@ arbitrate — see the first invariant.
   `relStart` is refused rather than accepted with the extras dropped: a client
   that sent them meant to anchor to text and got the discriminator wrong, and
   storing the mistake yields a thread that can never be placed.
+- **A `text-insertion` anchor is a REAL zero-width point, and resolution never
+  guesses.** An insert suggestion is not anchored to an adjacent quoted run of
+  existing text — a persisted suggestion outlives concurrent edits, and an
+  adjacency convention resolves against whichever run survives, the wrong one,
+  silently. Instead the point carries an optional `relPos` (one
+  `Y.RelativePosition` at the caret) plus bilateral `leftContext`/`rightContext`
+  (each max 64 UTF-16 code units, required-but-may-be-empty at document edges).
+  Resolution, implemented client-side: rung 1 decodes `relPos` and verifies
+  BOTH contexts around the decoded point (stale-not-correct, like the text
+  anchor's quote check); rung 2 searches for the UNIQUE
+  `leftContext`+`rightContext` seam — any ambiguity resolves orphaned, never a
+  guess; rung 3 orphaned. This variant ships contracts-first: its corpus cases
+  were added HERE with the deliberate same-diff digest re-pin ADR-CONTRACTS-116
+  allows (PRD-00933), and the backend boundary adopts both in PRD-00934 — until
+  then the upstream diff shows expected forward drift, and `anchor-corpus:sync`
+  must not be run (it would erase the new cases).
 - **A comment's `body` is null exactly when `deletedAt` is set, and such a
   comment carries no mentions.** A soft-deleted comment is a REDACTED
   PROJECTION, not a removed row — the tombstone keeps its position in the
@@ -79,7 +95,7 @@ arbitrate — see the first invariant.
 
 | Export                            | Description                                                                 |
 | --------------------------------- | --------------------------------------------------------------------------- |
-| `CommentAnchorSchema`             | `{document,v:1}` \| `{text,v:1,…}`, strict, discriminated on `type`         |
+| `CommentAnchorSchema`             | `{document,v:1}` \| `{text,v:1,…}` \| `{text-insertion,v:1,…}`, strict      |
 | `COMMENT_ANCHOR_TYPES`            | The anchor discriminants, as a vocabulary tuple                             |
 | `CommentAnchorTypeSchema`         | Zod mirror of `COMMENT_ANCHOR_TYPES` — what `anchorType` is checked against |
 | `COMMENT_THREAD_STATUSES`         | `open` \| `resolved` — there is no third state                              |
@@ -93,11 +109,17 @@ arbitrate — see the first invariant.
 | `CommentThreadListResponseSchema` | `GET /api/comments`                                                         |
 | `MentionableCandidateSchema`      | One offerable mention target — no email, no access level                    |
 | `MentionableResponseSchema`       | `GET /api/company-md/docs/{id}/mentionable`                                 |
+| `COMMENT_THREAD_KINDS`            | `comment` \| `suggestion` — a suggestion IS a comment thread                |
+| `SUGGESTION_OPS`                  | `insert` \| `delete` \| `replace` — what a suggestion proposes              |
+| `SUGGESTION_STATUSES`             | `open` \| `accepted` \| `rejected` — the SECOND status level, terminal      |
+| `SuggestionSchema`                | The versioned suggestion payload (`v:1`), strict, `insertedText` optional   |
 
 ## Dependencies
 
 - `zod` — schemas are canonical, types are inferred.
-- `./anchor` ← `./schemas`. Nothing outside this directory is imported: the
+- `./anchor` ← `./schemas`; `./suggestion` is a leaf (zod only) so `./schemas`
+  can import the thread-kind projection from it without a cycle.
+- Nothing outside this directory is imported: the
   comment vocabulary binds to the existing `commenter` band of
   `../permissions`'s `AccessLevel` and introduces no access level of its own, so
   it needs no import to say so.

package/src/comments/__tests__/anchor-corpus.test.ts

@@ -23,6 +23,14 @@
  * re-copies, and ADR-CONTRACTS-116 records that the upstream half is still a
  * documented promise rather than a gate.
  *
+ * ONE deliberate exception is live (PRD-00933, ADR slug
+ * suggested-edits-wire-vocabulary): the text-insertion cases were added HERE
+ * first, with the same-diff re-pin ADR-CONTRACTS-116 allows, because that
+ * variant is published before the backend boundary adopts it. The backend
+ * copy catches up in PRD-00934 — until then `--check` reports expected
+ * forward drift where an upstream tree is reachable, and `sync` must NOT be
+ * run (it would overwrite the new cases with the older upstream file).
+ *
  * The named rejection tests below are additional rather than a substitute: the
  * corpus covers the same ground by fixture name, and these say in prose what
  * the strict variants are FOR.
@@ -41,6 +49,24 @@ interface AnchorCase {
   anchor: unknown;
 }
 
+/**
+ * The additive fields the text-insertion rows carry beside `anchor`
+ * (PRD-00933): the document the anchor was authored against and the outcome
+ * the resolution ladder must produce for it. Inert descriptive data as far as
+ * the parse loops are concerned — the suite below is what keeps it honest.
+ */
+interface InsertionFixture extends AnchorCase {
+  anchor: { type: "text-insertion"; leftContext: string; rightContext: string };
+  document: string;
+  expectedResolution:
+    { outcome: "resolved"; offset: number } | { outcome: "orphaned" };
+}
+
+const isInsertionFixture = (c: AnchorCase): c is InsertionFixture => {
+  const anchor = c.anchor as { type?: unknown };
+  return anchor !== null && anchor?.type === "text-insertion";
+};
+
 /** The subset of `comment-anchors.provenance.json` this suite enforces. */
 interface CorpusPin {
   source: { repo: string; path: string };
@@ -118,6 +144,66 @@ describe("CommentAnchorSchema against the mirrored corpus", () => {
   }
 });
 
+describe("the text-insertion fixtures resolve as they claim", () => {
+  // The corpus's text-insertion rows record a document and an expected
+  // resolution outcome (PRD-00933) so the app's resolver (PRD-00935+) has
+  // pinned ground truth to test against. Nothing parses those fields, so
+  // without this suite a fixture whose document does not actually contain the
+  // seam it claims — or contains it twice where it claims once — would sit
+  // green here and mislead the resolver's suite downstream. This block
+  // re-derives each outcome from the document under the rung-2 semantics
+  // documented on `TextInsertionAnchorSchema`: a seam is an offset where
+  // `leftContext` ends and `rightContext` begins, only a UNIQUE seam
+  // resolves, and any ambiguity is orphaned — never a guess.
+  const seamOffsets = (
+    document: string,
+    left: string,
+    right: string,
+  ): number[] => {
+    const offsets: number[] = [];
+    // <= length: the seam after the final character is a real insertion
+    // point (document end). All arithmetic is UTF-16 code units — plain
+    // JS string coordinates, no Unicode normalization.
+    for (let i = 0; i <= document.length; i++) {
+      if (
+        i >= left.length &&
+        document.slice(i - left.length, i) === left &&
+        document.startsWith(right, i)
+      ) {
+        offsets.push(i);
+      }
+    }
+    return offsets;
+  };
+
+  const insertionCases = corpus.accept.filter(isInsertionFixture);
+
+  it("has the four required insertion fixtures, so none went missing", () => {
+    // Position 0, document end, ambiguous repeated seam, surrogate-pair
+    // flanked — the user-specified minimum. A corpus edit that drops one
+    // must fail loudly, not shrink the loop below.
+    expect(insertionCases.length).toBeGreaterThanOrEqual(4);
+  });
+
+  for (const { name, anchor, document, expectedResolution } of insertionCases) {
+    it(`resolves ${name} to its recorded outcome`, () => {
+      const offsets = seamOffsets(
+        document,
+        anchor.leftContext,
+        anchor.rightContext,
+      );
+      if (expectedResolution.outcome === "resolved") {
+        expect(offsets).toEqual([expectedResolution.offset]);
+      } else {
+        // Orphaned-by-ambiguity: the seam occurs MORE than once. (A seam
+        // occurring zero times is also orphaned, but these fixtures pin the
+        // ambiguity rule specifically — the case where guessing is tempting.)
+        expect(offsets.length).toBeGreaterThan(1);
+      }
+    });
+  }
+});
+
 describe("the anchor's load-bearing refusals, named", () => {
   it("rejects a text anchor with no quote", () => {
     // `quote` is the DURABLE FALLBACK — what a resolving client re-finds the

package/src/comments/__tests__/anchor-insertion.test.ts

@@ -0,0 +1,136 @@
+/**
+ * The text-insertion anchor variant, held to its published bounds
+ * (ADR slug suggested-edits-wire-vocabulary).
+ *
+ * HAND-WRITTEN RATHER THAN CORPUS-DRIVEN, unlike the sibling suite: each
+ * case here states in prose what one published bound is FOR. The mirrored
+ * corpus in `./fixtures/comment-anchors.json` ALSO carries text-insertion
+ * cases — added contracts-first under PRD-00933 with the deliberate same-diff
+ * digest re-pin ADR-CONTRACTS-116 allows, since this variant ships before
+ * the backend boundary adopts it (PRD-00934). Those corpus rows additionally
+ * pin document text and expected resolution outcomes, which this suite does
+ * not duplicate.
+ *
+ * Negative tests mutate ONE field of a well-formed factory object, so each
+ * fails on the field under test and nothing incidental.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  COMMENT_ANCHOR_TYPES,
+  CommentAnchorSchema,
+  CommentAnchorTypeSchema,
+} from "../anchor.js";
+
+/** A well-formed insertion anchor; override one field per negative test. */
+const makeInsertionAnchor = (over: Record<string, unknown> = {}) => ({
+  type: "text-insertion",
+  v: 1,
+  relPos: "AQLmzsvNAgA=",
+  leftContext: "the quarterly ",
+  rightContext: " goals",
+  ...over,
+});
+
+describe("the text-insertion anchor variant", () => {
+  it("accepts a full anchor: relPos plus bilateral context", () => {
+    expect(CommentAnchorSchema.safeParse(makeInsertionAnchor()).success).toBe(
+      true,
+    );
+  });
+
+  it("accepts an anchor with no relPos — the quote-path twin", () => {
+    // A client without an attached collab session cannot encode a
+    // Y.RelativePosition; the context seam is then the only resolution path.
+    // If this stops parsing, suggesting an insertion from outside the editor
+    // breaks.
+    const { relPos: _relPos, ...rest } = makeInsertionAnchor();
+    expect(CommentAnchorSchema.safeParse(rest).success).toBe(true);
+  });
+
+  it("accepts an empty leftContext — insertion at position 0", () => {
+    expect(
+      CommentAnchorSchema.safeParse(makeInsertionAnchor({ leftContext: "" }))
+        .success,
+    ).toBe(true);
+  });
+
+  it("accepts an empty rightContext — insertion at document end", () => {
+    expect(
+      CommentAnchorSchema.safeParse(makeInsertionAnchor({ rightContext: "" }))
+        .success,
+    ).toBe(true);
+  });
+
+  it("accepts contexts measured in UTF-16 code units, emoji included", () => {
+    // 32 astral emoji = 64 UTF-16 code units: exactly at the bound. The
+    // published bound is code units, not code points — the same coordinate
+    // system as mention offsets, with no Unicode normalization anywhere.
+    const emoji64 = "🎯".repeat(32);
+    expect(emoji64.length).toBe(64);
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeInsertionAnchor({ leftContext: emoji64, rightContext: emoji64 }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("rejects a context over 64 code units", () => {
+    // Bounded like prefix/suffix: context disambiguates a seam, it does not
+    // carry the document.
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeInsertionAnchor({ leftContext: "x".repeat(65) }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("rejects a missing context field", () => {
+    // leftContext/rightContext are REQUIRED-but-may-be-empty, so "nothing on
+    // that side" and "this client forgot to send it" stay distinguishable.
+    const { rightContext: _rightContext, ...rest } = makeInsertionAnchor();
+    expect(CommentAnchorSchema.safeParse(rest).success).toBe(false);
+  });
+
+  it("rejects an unknown version", () => {
+    // `v` is the evolution hatch: a new shape is a new `v`, and a resolving
+    // client must never guess at fields it half-recognises.
+    expect(
+      CommentAnchorSchema.safeParse(makeInsertionAnchor({ v: 2 })).success,
+    ).toBe(false);
+  });
+
+  it("rejects a relPos that is not base64", () => {
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeInsertionAnchor({ relPos: "not base64!!" }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("rejects text-anchor fields on an insertion anchor", () => {
+    // STRICT like the other variants: a client that sent `quote` meant to
+    // anchor to a range and got the discriminator wrong; storing the mistake
+    // yields a suggestion that can never be placed.
+    expect(
+      CommentAnchorSchema.safeParse(makeInsertionAnchor({ quote: "stray" }))
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("the widened anchor-type vocabulary", () => {
+  it("carries text-insertion in the tuple and the enum", () => {
+    // What CommentThreadSummarySchema's denormalised `anchorType` projection
+    // is checked against — a suggestion thread's summary row must not fail to
+    // parse on its own discriminant.
+    expect(COMMENT_ANCHOR_TYPES).toContain("text-insertion");
+    expect(CommentAnchorTypeSchema.safeParse("text-insertion").success).toBe(
+      true,
+    );
+  });
+
+  it("still refuses discriminants outside the vocabulary", () => {
+    expect(CommentAnchorTypeSchema.safeParse("region").success).toBe(false);
+  });
+});

package/src/comments/__tests__/fixtures/README.md

@@ -35,6 +35,23 @@ obvious to the next reader.
   rewrites the pin in the same step. Editing this side to make a test pass fails
   the pin; editing it and re-pinning by hand defeats the check, and shows up as
   exactly that in the diff.
+- **ONE deliberate exception is live (PRD-00933, ADR slug
+  suggested-edits-wire-vocabulary).** The `text-insertion` cases were added
+  HERE first, with the same-diff re-pin ADR-CONTRACTS-116 explicitly allows,
+  because that anchor variant is published contracts-first — the backend
+  boundary adopts it in PRD-00934, against the npm-published version of this
+  package, and only then mirrors these cases into its own fixture file. Until
+  that lands, `pnpm anchor-corpus:check` reports expected FORWARD drift
+  wherever a backend tree is reachable, and `pnpm anchor-corpus:sync` must
+  NOT be run: it would overwrite the new cases with the older upstream file.
+- **Text-insertion rows carry two additive fields beside `anchor`:**
+  `document` (the text the anchor was authored against) and
+  `expectedResolution` (`{ outcome: "resolved", offset }` in zero-based UTF-16
+  code units, or `{ outcome: "orphaned" }` when the context seam is ambiguous
+  and resolution must never guess). The parse loops ignore them; the
+  fixture-consistency suite in `../anchor-corpus.test.ts` re-derives each
+  outcome from the document, so the recorded ground truth cannot rot silently
+  before the app's resolver (PRD-00935+) tests against it.
 - **It is listed in `/.prettierignore`.** Prettier reflows the long anchor
   objects, which would break the byte identity (and fail the pin). The file
   carries the backend's formatting, not this repo's. The pin beside it is NOT

package/src/comments/__tests__/fixtures/comment-anchors.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "STABLE CONTRACT CORPUS for the comment-anchor route boundary (PRD-00920 / ADR-BE-512 §4). Named accept/reject cases for CommentAnchorSchema (src/api/http/routes/comments/comments.schemas.ts). PRD-00922 copies this file into @company-semantics/contracts and mechanically diffs the two copies, so schema drift between the backend boundary and the published contract is caught by a file comparison. Change cases here only together with the schema; never hand-tune one side.",
+  "$comment": "STABLE CONTRACT CORPUS for the comment-anchor route boundary (PRD-00920 / ADR-BE-512 §4). Named accept/reject cases for CommentAnchorSchema (src/api/http/routes/comments/comments.schemas.ts). PRD-00922 copies this file into @company-semantics/contracts and mechanically diffs the two copies, so schema drift between the backend boundary and the published contract is caught by a file comparison. Change cases here only together with the schema; never hand-tune one side. EXCEPTION (PRD-00933, ADR slug suggested-edits-wire-vocabulary): the text-insertion cases below were added CONTRACTS-FIRST, with a deliberate digest re-pin in the same diff, because that anchor variant is published here before the backend boundary adopts it. The backend copy catches up in PRD-00934 — until then the upstream diff shows expected forward drift; do NOT 'fix' it with anchor-corpus:sync, which would erase these cases. Text-insertion rows additively carry 'document' and 'expectedResolution' beside 'anchor': inert descriptive data pinning the resolution-ladder outcome (offsets are zero-based UTF-16 code units; 'orphaned' means the context seam is ambiguous and resolution must never guess). The parse loops ignore the extra keys.",
   "accept": [
     {
       "name": "document-anchor",
@@ -26,6 +26,51 @@
         "prefix": "",
         "suffix": ""
       }
+    },
+    {
+      "name": "text-insertion-at-position-0",
+      "anchor": {
+        "type": "text-insertion",
+        "v": 1,
+        "leftContext": "",
+        "rightContext": "Welcome to"
+      },
+      "document": "Welcome to the quarterly plan.",
+      "expectedResolution": { "outcome": "resolved", "offset": 0 }
+    },
+    {
+      "name": "text-insertion-at-document-end",
+      "anchor": {
+        "type": "text-insertion",
+        "v": 1,
+        "leftContext": "quarterly goals.",
+        "rightContext": ""
+      },
+      "document": "We agreed to ship the quarterly goals.",
+      "expectedResolution": { "outcome": "resolved", "offset": 38 }
+    },
+    {
+      "name": "text-insertion-ambiguous-repeated-seam",
+      "anchor": {
+        "type": "text-insertion",
+        "v": 1,
+        "leftContext": "item ",
+        "rightContext": "done"
+      },
+      "document": "item done, item done, item done",
+      "expectedResolution": { "outcome": "orphaned" }
+    },
+    {
+      "name": "text-insertion-flanked-by-surrogate-pairs",
+      "anchor": {
+        "type": "text-insertion",
+        "v": 1,
+        "relPos": "AQLmzsvNAgA=",
+        "leftContext": "goals 🎯",
+        "rightContext": "🚀 shipped"
+      },
+      "document": "Q3 goals 🎯🚀 shipped early",
+      "expectedResolution": { "outcome": "resolved", "offset": 11 }
     }
   ],
   "reject": [

package/src/comments/__tests__/fixtures/comment-anchors.provenance.json

@@ -1,9 +1,9 @@
 {
-  "$comment": "Provenance pin for ./comment-anchors.json, which is a byte-for-byte copy of company-semantics-backend/tests/fixtures/comment-anchors.json (ADR-CONTRACTS-116). anchor-corpus.test.ts re-derives this digest from the file's bytes on every run, so an edit made on THIS side fails CI instead of quietly making the corpus this repo's own. Drift introduced on the BACKEND side is not observable from contracts CI and is not gated here. Regenerate with `pnpm anchor-corpus:sync`; never hand-edit this file or the corpus.",
+  "$comment": "Provenance pin for ./comment-anchors.json, which is a byte-for-byte copy of company-semantics-backend/tests/fixtures/comment-anchors.json (ADR-CONTRACTS-116). anchor-corpus.test.ts re-derives this digest from the file's bytes on every run, so an edit made on THIS side fails CI instead of quietly making the corpus this repo's own. Drift introduced on the BACKEND side is not observable from contracts CI and is not gated here. Regenerate with `pnpm anchor-corpus:sync`; never hand-edit this file or the corpus — with ONE reviewed exception, the deliberate same-diff re-pin ADR-CONTRACTS-116 allows: PRD-00933 (ADR slug suggested-edits-wire-vocabulary) added the text-insertion cases contracts-first, because that variant is published here before the backend boundary adopts it. The backend copy catches up in PRD-00934; until then `anchor-corpus:check` reports expected forward drift wherever a backend tree is reachable, and `anchor-corpus:sync` must NOT be run (it would overwrite the new cases with the older upstream file).",
   "source": {
     "repo": "company-semantics-backend",
     "path": "tests/fixtures/comment-anchors.json"
   },
-  "bytes": 2649,
-  "sha256": "84fa0040c9acc166a5551185950e5dc8afffcc5fd63a1f17080422318b405c8c"
+  "bytes": 4749,
+  "sha256": "d4bba06575774f204effe4b2256a77208918a769cb82d73fdff8d16cdbf76a53"
 }

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

@@ -54,6 +54,8 @@ function makeThread(over: Record<string, unknown> = {}) {
     id: THREAD_ID,
     subjectType: "company_md",
     subjectId: DOC_ID,
+    kind: "comment",
+    suggestion: null,
     anchorType: "text",
     anchor: {
       type: "text",
@@ -240,6 +242,83 @@ describe("CommentThreadSchema", () => {
   });
 });
 
+describe("CommentThreadSummarySchema kind and suggestion", () => {
+  it("a zero-comment suggestion thread parses through both response shapes", () => {
+    // The full suggestion projection: kind `suggestion`, a v1 payload, a
+    // zero-width text-insertion anchor, and NO comments. The backend creates a
+    // suggestion thread without a first comment (the payload IS the content),
+    // so `comments: []` must parse — a min-length on the comments array would
+    // refuse every freshly-created suggestion.
+    const suggestionThread = makeThread({
+      kind: "suggestion",
+      suggestion: {
+        v: 1,
+        op: "insert",
+        insertedText: "and measure adoption weekly",
+        status: "open",
+      },
+      anchorType: "text-insertion",
+      anchor: {
+        type: "text-insertion",
+        v: 1,
+        leftContext: "quarterly goals",
+        rightContext: " by March",
+      },
+      comments: [],
+    });
+    expect(CommentThreadSchema.safeParse(suggestionThread).success).toBe(true);
+    expect(
+      CommentThreadListResponseSchema.safeParse({ threads: [suggestionThread] })
+        .success,
+    ).toBe(true);
+  });
+
+  it("parses a legacy-shaped comment thread — kind comment, suggestion null", () => {
+    // Every thread written before suggestions existed arrives exactly like
+    // this: the backend projects kind `comment` and suggestion null onto old
+    // rows, so the pre-suggestion shape plus those two fields must keep
+    // parsing untouched.
+    expect(CommentThreadSchema.safeParse(makeThread()).success).toBe(true);
+  });
+
+  it("requires kind — the backend always projects it, so absence is malformed", () => {
+    const { kind: _dropped, ...withoutKind } = makeThread();
+    expect(CommentThreadSchema.safeParse(withoutKind).success).toBe(false);
+  });
+
+  it("parses a decided suggestion via the two-level status model", () => {
+    // The thread enum is NOT widened: a decided suggestion is thread status
+    // `resolved` with suggestion.status carrying which way it went, and
+    // resolvedByUserId/resolvedAt doubling as the decision actor/time.
+    expect(
+      CommentThreadSchema.safeParse(
+        makeThread({
+          kind: "suggestion",
+          suggestion: { v: 1, op: "delete", status: "accepted" },
+          anchorType: "text",
+          status: "resolved",
+          resolvedByUserId: USER_ID,
+          resolvedAt: "2026-08-02T09:00:00.000Z",
+          comments: [],
+        }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("rejects a suggestion payload outside the published shape", () => {
+    // SuggestionSchema is strict — an unknown field means a newer dialect,
+    // which must arrive as a new `v`, not as loose extras.
+    expect(
+      CommentThreadSchema.safeParse(
+        makeThread({
+          kind: "suggestion",
+          suggestion: { v: 1, op: "delete", status: "open", extra: true },
+        }),
+      ).success,
+    ).toBe(false);
+  });
+});
+
 describe("CommentThreadListResponseSchema", () => {
   it("parses an empty subject", () => {
     expect(

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

@@ -0,0 +1,130 @@
+/**
+ * The suggestion payload vocabulary, held to the invariants its JSDoc claims
+ * (ADR slug suggested-edits-wire-vocabulary).
+ *
+ * Every negative test mutates ONE field of a well-formed factory result, for
+ * the reason `./schemas.test.ts` states: a hand-built broken object can pass
+ * for the wrong reason — it fails on the field nobody was testing.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  COMMENT_THREAD_KINDS,
+  SUGGESTION_OPS,
+  SUGGESTION_STATUSES,
+  SuggestionSchema,
+} from "../suggestion.js";
+
+function makeSuggestion(over: Record<string, unknown> = {}) {
+  return {
+    v: 1,
+    op: "replace",
+    insertedText: "ship the quarterly goals by April",
+    status: "open",
+    ...over,
+  };
+}
+
+describe("the vocabulary tuples", () => {
+  it("COMMENT_THREAD_KINDS is exactly comment and suggestion", () => {
+    expect([...COMMENT_THREAD_KINDS]).toEqual(["comment", "suggestion"]);
+  });
+
+  it("SUGGESTION_OPS is exactly insert, delete and replace", () => {
+    expect([...SUGGESTION_OPS]).toEqual(["insert", "delete", "replace"]);
+  });
+
+  it("SUGGESTION_STATUSES is exactly open, accepted and rejected", () => {
+    // The SECOND status level. The thread-level enum stays open|resolved —
+    // `./schemas.test.ts` pins that separately — and the decision lives here.
+    expect([...SUGGESTION_STATUSES]).toEqual(["open", "accepted", "rejected"]);
+  });
+});
+
+describe("SuggestionSchema", () => {
+  it("parses an insert payload", () => {
+    expect(
+      SuggestionSchema.safeParse(
+        makeSuggestion({ op: "insert", insertedText: "new sentence" }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("parses a replace payload", () => {
+    expect(SuggestionSchema.safeParse(makeSuggestion()).success).toBe(true);
+  });
+
+  it("parses a delete payload WITHOUT insertedText", () => {
+    // The reason insertedText is optional in the READ schema: a delete has
+    // nothing to insert. "Required for insert/replace" is the backend request
+    // schema's superRefine, deliberately not re-stated here.
+    const { insertedText: _dropped, ...deletePayload } = makeSuggestion({
+      op: "delete",
+    });
+    expect(SuggestionSchema.safeParse(deletePayload).success).toBe(true);
+  });
+
+  it("parses a decided payload", () => {
+    expect(
+      SuggestionSchema.safeParse(makeSuggestion({ status: "accepted" }))
+        .success,
+    ).toBe(true);
+    expect(
+      SuggestionSchema.safeParse(makeSuggestion({ status: "rejected" }))
+        .success,
+    ).toBe(true);
+  });
+
+  it("rejects an op outside the vocabulary", () => {
+    expect(
+      SuggestionSchema.safeParse(makeSuggestion({ op: "move" })).success,
+    ).toBe(false);
+  });
+
+  it("rejects a status outside the vocabulary", () => {
+    // Notably `resolved`: that is the THREAD's terminal state, not the
+    // suggestion's. A payload claiming it means the writer confused the two
+    // status levels.
+    expect(
+      SuggestionSchema.safeParse(makeSuggestion({ status: "resolved" }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects an empty insertedText — absent and empty stay distinguishable", () => {
+    expect(
+      SuggestionSchema.safeParse(makeSuggestion({ insertedText: "" })).success,
+    ).toBe(false);
+  });
+
+  it("rejects insertedText over 10000 code units", () => {
+    expect(
+      SuggestionSchema.safeParse(
+        makeSuggestion({ insertedText: "x".repeat(10001) }),
+      ).success,
+    ).toBe(false);
+    expect(
+      SuggestionSchema.safeParse(
+        makeSuggestion({ insertedText: "x".repeat(10000) }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("rejects unknown keys — a newer dialect must arrive as a new v", () => {
+    expect(
+      SuggestionSchema.safeParse(makeSuggestion({ decidedBy: "someone" }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects any v other than 1", () => {
+    expect(SuggestionSchema.safeParse(makeSuggestion({ v: 2 })).success).toBe(
+      false,
+    );
+  });
+
+  it("requires status — the projection always composes it", () => {
+    const { status: _dropped, ...withoutStatus } = makeSuggestion();
+    expect(SuggestionSchema.safeParse(withoutStatus).success).toBe(false);
+  });
+});

package/src/comments/anchor.ts

@@ -96,14 +96,73 @@ const TextAnchorSchema = z.strictObject({
 });
 
 /**
- * The anchor types, as a vocabulary tuple.
+ * A ZERO-WIDTH insertion point — where an `insert` suggestion proposes to add
+ * text (ADR slug suggested-edits-wire-vocabulary). This is a REAL
+ * representation of a point between two characters, deliberately NOT an anchor
+ * to an adjacent quoted run of existing text: a persisted suggestion outlives
+ * concurrent edits, and an adjacency convention ("insert after this quote")
+ * resolves against whichever run happens to survive — the wrong one, silently.
+ *
+ * `relPos` is a single `Y.RelativePosition` at the caret, OPTIONAL for the
+ * same reason `relStart`/`relEnd` are on the text anchor: a client without an
+ * attached collab session cannot produce one. Optional means "this client
+ * could not", never "this client chose not to".
+ *
+ * `leftContext`/`rightContext` are the durable fallback — the text
+ * immediately before and after the point. They are required-but-may-be-empty
+ * (max 64 UTF-16 code units each, like `prefix`/`suffix`): either may be
+ * empty or short at a document edge, and an empty string means "there is
+ * nothing on that side", which must stay distinguishable from "this client
+ * forgot to send it". No Unicode normalization happens anywhere on this path.
+ *
+ * RESOLUTION SEMANTICS (implemented client-side in the app; the backend is a
+ * passthrough that interprets nothing):
+ *   1. Decode `relPos` and verify BOTH contexts around the decoded point. A
+ *      point whose surroundings no longer match is STALE, not correct — the
+ *      same rule as the text anchor's quote check.
+ *   2. Search the document for the `leftContext`+`rightContext` seam. Only a
+ *      UNIQUE match resolves; any ambiguity (the seam occurs more than once)
+ *      resolves ORPHANED, never a guess.
+ *   3. Orphaned.
+ *
+ * CONTRACTS-FIRST ORDERING NOTE: unlike the two variants above, this variant
+ * is published here BEFORE the backend route boundary adopts it (PRD-00934
+ * lands the backend half against the npm-published version of this package).
+ * The mirrored corpus gained its text-insertion cases HERE, contracts-first,
+ * via the deliberate same-diff digest re-pin ADR-CONTRACTS-116 allows; the
+ * backend copy catches up in PRD-00934, and until it does the upstream diff
+ * shows expected forward drift (do not "fix" it with anchor-corpus:sync).
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00933, must_log).
+ * The reference writes these declarations with single-quoted strings; what
+ * ships below is double-quoted because that is this repo's Prettier default
+ * (no `.prettierrc`, so `singleQuote` is false). Same precedent as the
+ * PRD-00922 note above: a different spelling of the same schema, nothing
+ * about what is accepted or refused changed.
+ */
+const TextInsertionAnchorSchema = z.strictObject({
+  type: z.literal("text-insertion"),
+  v: z.literal(1),
+  relPos: RelativePositionSchema.optional(),
+  leftContext: z.string().max(64),
+  rightContext: z.string().max(64),
+});
+
+/**
+ * The anchor types, as a vocabulary tuple:
+ * `["document", "text", "text-insertion"]` (widened by PRD-00933; Prettier
+ * wraps the declaration below because it exceeds the print width).
  *
  * Mirrors the union's discriminants, and is what `CommentThreadSummarySchema`'s
  * denormalised `anchorType` column is checked against — the server projects the
  * discriminant out of the jsonb so a client can filter threads without parsing
  * every anchor.
  */
-export const COMMENT_ANCHOR_TYPES = ["document", "text"] as const;
+export const COMMENT_ANCHOR_TYPES = [
+  "document",
+  "text",
+  "text-insertion",
+] as const;
 export const CommentAnchorTypeSchema = z.enum(COMMENT_ANCHOR_TYPES);
 export type CommentAnchorType = z.infer<typeof CommentAnchorTypeSchema>;
 
@@ -116,5 +175,6 @@ export type CommentAnchorType = z.infer<typeof CommentAnchorTypeSchema>;
 export const CommentAnchorSchema = z.discriminatedUnion("type", [
   DocumentAnchorSchema,
   TextAnchorSchema,
+  TextInsertionAnchorSchema,
 ]);
 export type CommentAnchor = z.infer<typeof CommentAnchorSchema>;

package/src/comments/index.ts

@@ -41,3 +41,17 @@ export type {
   MentionableCandidate,
   MentionableResponse,
 } from "./schemas";
+
+export {
+  COMMENT_THREAD_KINDS,
+  SUGGESTION_OPS,
+  SUGGESTION_STATUSES,
+  SuggestionSchema,
+} from "./suggestion";
+
+export type {
+  CommentThreadKind,
+  Suggestion,
+  SuggestionOp,
+  SuggestionStatus,
+} from "./suggestion";

package/src/comments/schemas.ts

@@ -19,6 +19,7 @@
  */
 import { z } from "zod";
 import { CommentAnchorSchema, CommentAnchorTypeSchema } from "./anchor";
+import { COMMENT_THREAD_KINDS, SuggestionSchema } from "./suggestion";
 
 // =============================================================================
 // Vocabulary
@@ -154,11 +155,30 @@ export type CommentProjection = z.infer<typeof CommentSchema>;
  * the server. It is redundant with `anchor.type` and that is the point: a client
  * can bucket threads into document-level and text-level without parsing every
  * anchor, and the two are written together so they cannot disagree.
+ *
+ * `kind` is REQUIRED, never optional: the backend always projects it, and
+ * `comment` is every thread written before suggestions existed — so absence is
+ * a malformed response, not a legacy row (see `COMMENT_THREAD_KINDS`).
+ *
+ * `suggestion` is null EXACTLY WHEN `kind` is `comment`. Like the redaction
+ * invariant on `CommentSchema`, this null-iff rule is DOCUMENTED here and
+ * enforced by backend CHECK constraints, not by a Zod refinement — a refinement
+ * 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.
+ *
+ * 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
+ * thread status `resolved` with `suggestion.status` carrying which way it went
+ * (`accepted` | `rejected`), and `resolvedByUserId`/`resolvedAt` double as the
+ * decision actor and time — there is no second actor/timestamp pair.
  */
 export const CommentThreadSummarySchema = z.object({
   id: z.string(),
   subjectType: CommentSubjectTypeSchema,
   subjectId: z.string(),
+  kind: z.enum(COMMENT_THREAD_KINDS),
+  suggestion: SuggestionSchema.nullable(),
   anchorType: CommentAnchorTypeSchema,
   anchor: CommentAnchorSchema,
   status: CommentThreadStatusSchema,

package/src/comments/suggestion.ts

@@ -0,0 +1,73 @@
+/**
+ * The suggestion payload — the proposed document edit a suggestion thread
+ * carries (ADR slug suggested-edits-wire-vocabulary).
+ *
+ * READ VOCABULARY ONLY, like the rest of this directory: the create/accept/
+ * reject request bodies stay backend-side per ADR-CONT-029. This module is
+ * deliberately a LEAF — it imports nothing but `zod`, because `./schemas` will
+ * import from it (the thread summary's `kind`/`suggestion` projection) and an
+ * import back the other way would be a cycle.
+ *
+ * Zod-canonical: the schema is the source of truth, the type is inferred.
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00933, must_log).
+ * The reference block writes these declarations with single-quoted strings;
+ * what ships below is double-quoted because that is this repo's Prettier
+ * default (there is no `.prettierrc`, so `singleQuote` is false and
+ * `pnpm format:check` rewrites any single-quoted string here). Same precedent
+ * as `./anchor`'s PRD-00922 note: a different spelling of the same schema,
+ * nothing about what is accepted or refused changed.
+ */
+import { z } from "zod";
+
+/**
+ * Thread kinds. A suggestion IS a comment thread — same table, same replies,
+ * mentions and notifications — carrying a proposed document edit. `comment`
+ * is every thread written before suggestions existed, which is why the
+ * backend always projects this field rather than leaving it optional.
+ */
+export const COMMENT_THREAD_KINDS = ["comment", "suggestion"] as const;
+export type CommentThreadKind = (typeof COMMENT_THREAD_KINDS)[number];
+
+/**
+ * What a suggestion proposes doing to the anchored range: `insert` at a
+ * zero-width point, `delete` the anchored quote, or `replace` it.
+ */
+export const SUGGESTION_OPS = ["insert", "delete", "replace"] as const;
+export type SuggestionOp = (typeof SUGGESTION_OPS)[number];
+
+/**
+ * open -> accepted | rejected. Terminal states are terminal: there is no
+ * reopen for a decided suggestion (unlike comment resolve/reopen). This is
+ * the SECOND status level — the thread-level `status` enum stays exactly
+ * `open | resolved`, and a decided suggestion arrives as thread status
+ * `resolved` with this field carrying which way it went. Widening the closed
+ * thread enum instead would be a parse outage for every deployed client.
+ */
+export const SUGGESTION_STATUSES = ["open", "accepted", "rejected"] as const;
+export type SuggestionStatus = (typeof SUGGESTION_STATUSES)[number];
+
+/**
+ * Versioned suggestion payload. Evolution = new `v` variants, never mutation
+ * (same rule as CommentAnchor). `status` is composed by the backend read
+ * projection from its dedicated status column — the stored jsonb does NOT
+ * carry it; one truth per field.
+ *
+ * `insertedText`: required for insert/replace, absent for delete — enforced
+ * by the backend request schema's superRefine, not here. This READ schema
+ * keeps it optional so a delete payload parses without it; refining here
+ * would make this package refuse a response the server is willing to emit
+ * (the same reasoning as `./schemas`' redaction invariant).
+ *
+ * Strict: a payload carrying fields outside this shape is refused rather than
+ * accepted with the extras dropped — an unknown field means the writer was
+ * speaking a newer dialect, and that must arrive as a new `v`, not as loose
+ * extras a resolving client half-recognises.
+ */
+export const SuggestionSchema = z.strictObject({
+  v: z.literal(1),
+  op: z.enum(SUGGESTION_OPS),
+  insertedText: z.string().min(1).max(10000).optional(),
+  status: z.enum(SUGGESTION_STATUSES),
+});
+export type Suggestion = z.infer<typeof SuggestionSchema>;

package/src/index.ts

@@ -333,7 +333,10 @@ export type {
 export {
   COMMENT_ANCHOR_TYPES,
   COMMENT_SUBJECT_TYPES,
+  COMMENT_THREAD_KINDS,
   COMMENT_THREAD_STATUSES,
+  SUGGESTION_OPS,
+  SUGGESTION_STATUSES,
 } from "./comments/index";
 
 export {
@@ -348,6 +351,7 @@ export {
   CommentThreadSummarySchema,
   MentionableCandidateSchema,
   MentionableResponseSchema,
+  SuggestionSchema,
 } from "./comments/index";
 
 export type {
@@ -357,11 +361,15 @@ export type {
   CommentProjection,
   CommentSubjectType,
   CommentThread,
+  CommentThreadKind,
   CommentThreadListResponse,
   CommentThreadStatus,
   CommentThreadSummary,
   MentionableCandidate,
   MentionableResponse,
+  Suggestion,
+  SuggestionOp,
+  SuggestionStatus,
 } from "./comments/index";
 
 // Chat domain types