@company-semantics/contracts 51.0.0 → 51.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "51.0.0",
+  "version": "51.2.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -148,9 +148,9 @@
     "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
-    "tsx": "^4.23.11",
+    "tsx": "^4.23.12",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.66.0",
+    "typescript-eslint": "^8.67.0",
     "vite": "^8.2.1",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '6dcd82441a54' as const;
-export const SPEC_HASH_FULL = '6dcd82441a54409faaa94d94f36a43cd72894c7e655fb49f5eb758a0963c9a43' as const;
+export const SPEC_HASH = 'b044ca016033' as const;
+export const SPEC_HASH_FULL = 'b044ca016033c3a7224160a73898e3f551218dbef0139a23601f1ca4eb171d15' as const;

package/src/api/generated.ts

@@ -3565,6 +3565,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments/threads/{threadId}/anchor-trace": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Report where a thread's anchored passage used to be */
+        post: operations["stampCommentAnchorTrace"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments/threads/{threadId}/accept-intent": {
         parameters: {
             query?: never;
@@ -4720,7 +4737,7 @@ export interface components {
             summary: {
                 executionId: string;
                 /** @enum {string} */
-                kind: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest";
+                kind: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
                 target: {
                     /** @constant */
                     type: "slack";
@@ -6514,6 +6531,9 @@ export interface components {
         CommentThreadSummaryResponse: {
             thread: components["schemas"]["CommentThreadSummary"];
         };
+        AnchorTraceRequest: {
+            lastAnchoredOffset: number;
+        };
         /** @description The acceptance lease: the opaque claim token that alone can complete the accept, and how long the lease lives. */
         SuggestionClaimResponse: {
             claimToken: string;
@@ -6550,12 +6570,13 @@ export interface components {
             /** @enum {string} */
             category: "version" | "source" | "lifecycle" | "access" | "sync";
             /** @enum {string} */
-            eventType: "doc_created" | "source_added" | "source_removed" | "content_generated" | "external_sync_completed" | "access_granted" | "access_revoked" | "access_updated" | "sharing_policy_changed" | "visibility_changed" | "owner_transferred" | "discoverability_changed";
+            eventType: "doc_created" | "doc_renamed" | "doc_moved" | "source_added" | "source_attached" | "source_detached" | "source_removed" | "source_extraction_started" | "source_extraction_succeeded" | "source_extraction_failed" | "content_generated" | "external_sync_completed" | "access_granted" | "access_revoked" | "access_updated" | "sharing_policy_changed" | "visibility_changed" | "owner_transferred" | "discoverability_changed";
             actor: components["schemas"]["CompanyMdDocVersionActor"] | null;
             subject: string | null;
             target: components["schemas"]["CompanyMdDocHistoryTarget"] | null;
             previousValue: string | null;
             newValue: string | null;
+            correlationId: string | null;
         };
         /** @description The singular actor a version is attributed to, in product vocabulary. */
         CompanyMdDocVersionActor: {
@@ -6612,6 +6633,7 @@ export interface components {
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
+            lastAnchoredOffset: number | null;
             createdAt: string;
             updatedAt: string;
             comments: components["schemas"]["Comment"][];
@@ -6686,6 +6708,7 @@ export interface components {
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
+            lastAnchoredOffset: number | null;
             createdAt: string;
             updatedAt: string;
         };
@@ -8519,7 +8542,7 @@ export interface operations {
             query?: {
                 cursor?: string;
                 limit?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest";
+                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
                 targetType?: string;
                 periodStart?: string;
                 periodEnd?: string;
@@ -8654,7 +8677,7 @@ export interface operations {
             query?: {
                 limit?: number;
                 offset?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest";
+                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
                 kindPrefix?: string;
             };
             header?: never;
@@ -12833,6 +12856,46 @@ export interface operations {
             };
         };
     };
+    stampCommentAnchorTrace: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AnchorTraceRequest"];
+            };
+        };
+        responses: {
+            /** @description Offset recorded, or the already-recorded thread returned unchanged (first write wins) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Invalid body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not comment on its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     acceptSuggestionIntent: {
         parameters: {
             query?: never;

package/src/comments/README.md

@@ -2,26 +2,46 @@
 
 ## Purpose
 
-The published **read** vocabulary of the comment surface: where a thread hangs
+The published **read** vocabulary of the comment surface — where a thread hangs
 (`CommentAnchorSchema`), what a thread and its comments look like on the wire
 (`CommentThreadSchema`, `CommentSchema`, `CommentMentionSchema`), and who a
-comment may name (`MentionableResponseSchema`).
+comment may name (`MentionableResponseSchema`) — together with the one published
+INTERPRETATION of an anchor, in both directions: reading one against a document
+(`resolveAnchorFromText`, `anchorStillReads`, `plannedEdit`), composing one from
+a range (`createTextAnchorFromRange`, `createTextInsertionAnchorAt`), the size
+bounds both halves share (`./anchor-constants`), and the receipt that proves an
+accepted suggestion's edit already landed (`SUGGESTION_RECEIPTS_MAP`).
 
 This exists as a published contract rather than an app-local type because two
 independent clients have to agree about it without a server in the middle to
-arbitrate — see the first invariant.
+arbitrate — see the first two invariants. Publishing the SHAPE bounded that
+risk; publishing the interpretation closes it (ADR-CONTRACTS-127), because a
+second implementation is now an IMPORT rather than a second description.
+Interpretation is pure, dependency-free derivation of published vocabulary, so
+it stays inside the vocabulary-guard's rules — request bodies still do not.
 
 ## Invariants
 
-- **The anchor is the contract between the client that WRITES it and the client
-  that later RESOLVES it, and the backend is a passthrough that cannot catch
-  drift in it.** The route boundary validates the anchor's SHAPE and stores the
+- **STORAGE IS STILL A PASSTHROUGH, and it still cannot catch drift in an
+  anchor.** The route boundary validates the anchor's SHAPE and stores the
   result as opaque jsonb; the service, the database and every projection treat
   it as bytes and interpret nothing. So if the writing client and the resolving
   client disagree about what these fields mean, the write succeeds, the read
   succeeds, and the comment silently lands on the wrong text. There is no
   server-side tripwire, and there cannot be one — which is precisely why the
-  shape is published here instead of being declared twice.
+  shape is published here instead of being declared twice. ADR-CONTRACTS-127
+  left this half exactly as it was.
+- **INTERPRETATION IS NO LONGER PER-CONSUMER — that is the half that did
+  change, and both halves are true at once.** `resolveAnchorFromText`,
+  `anchorStillReads`, `plannedEdit`, `createTextAnchorFromRange` and
+  `createTextInsertionAnchorAt` are the ONE published reading of those bytes
+  (ADR-CONTRACTS-127), so the backend becoming an eligible applier and a comment
+  pass running server-side are imports rather than a third and fourth
+  description of the same rules. This does NOT make the server an arbiter: the
+  anchor column is still opaque jsonb, still uninterpreted by the database and
+  by every projection, and the boundary still validates shape only. A reader who
+  takes either half alone gets the model wrong — one way they expect the server
+  to catch a bad anchor, the other way they write a second resolver.
 - **`v` is the evolution hatch, and it is the only thing that bounds that
   risk.** A client that meets an anchor it cannot resolve sees an unfamiliar `v`
   and degrades on purpose instead of guessing at fields it half-recognises. New
@@ -43,15 +63,102 @@ arbitrate — see the first invariant.
   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
+  Resolution: rung 1 decodes `relPos` and verifies BOTH contexts around the
+  decoded point (stale-not-correct, like the text anchor's quote check) and
+  stays with the consumer, since decoding needs `yjs` and a live replica; rung 2
+  is published here as `resolveAnchorFromText` and 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).
+- **AMBIGUITY RESOLVES ORPHANED, AT BOTH LEVELS, AND NEVER BINDS TO THE FIRST
+  OCCURRENCE.** For a `text` anchor, `resolveAnchorFromText` searches the
+  context-qualified `prefix`+`quote`+`suffix` first, and TWO occurrences of that
+  string mean the context FAILED to identify a candidate — so the answer is
+  `orphaned`, and it does not then fall back to the bare quote, which would only
+  re-ask a question already known to be ambiguous. Absence is not ambiguity: an
+  ABSENT context does fall through to the bare `quote`, where a repeated quote is
+  orphaned in its own right. A repeated insertion seam gets the same answer for
+  the same reason, and an EMPTY seam is refused on a non-empty document rather
+  than treated as matching everywhere — an empty needle is a fact about the
+  search, not evidence about the point. (The one exception is the empty
+  document, where 0 is the only point there is.)
+  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.
+  Nothing outside this package enforces the rule: a consumer composing its own
+  rung 1 can resolve ambiguously THERE and never reach the published ladder's
+  refusal, so this is written down rather than typed (ADR-CONTRACTS-127).
+- **The applier must not trust the finder.** `anchorStillReads` is a SECOND
+  assertion, independent of `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", the assertion answers
+  "is what lands there still the thing", and a consumer composing the Yjs rung on
+  top supplies a position this package never computed. A `document` anchor
+  answers `false`: it names no characters, so it can vouch for no range.
+- **A no-op is a refusal, not a cheap success.** `plannedEdit` returns `null` for
+  an `insert`/`replace` carrying no text and for a `delete`/`replace` over a
+  collapsed range. Each of those would otherwise run a transaction that writes a
+  receipt and changes not one character — the thread reported as `accepted` over
+  a document that never received the proposal. Both shapes mean the payload and
+  the anchor disagree about what kind of edit this is, and settling that
+  disagreement is not this package's to do.
+- **The receipt is the durable proof that the edit ALREADY LANDED, and its KEY
+  is the contract.** Acceptance is apply-then-record, so there is one window —
+  between the transaction and the acknowledgement — in which the document has
+  changed and the thread still says `open`. `SUGGESTION_RECEIPTS_MAP` names the
+  root map the receipt is written into, in the SAME transaction as the edit, so
+  either both survived or neither did. A receipt written under any other name
+  lands in a map nobody reads while the reader watches a map nobody writes:
+  nothing throws, and the accept control stays live over an edit already in the
+  body. The name is spelled once, here, exactly as `COMPANY_MD_COLLAB_TEXT_KEY`
+  is for the body text.
+- **The receipt lives BESIDE the body, never inside it, and ABSENCE IS NOT
+  PROOF.** It is a root map on the same document as the text, not a span in the
+  text — it must never reach the markdown source, an export, or the content
+  hash. And a reader holding no replica holds no receipts, so an empty map means
+  "no receipt is KNOWN HERE", never "no receipt exists": every consumer acts on
+  PRESENCE only. `readSuggestionReceipt` drops a malformed row to `null` rather
+  than surfacing a partial one precisely because that lands in the state every
+  consumer already has to handle correctly.
+- **The receipt row is STRICT and carries no `v`, unlike the anchor and the
+  suggestion.** Those two are negotiated payloads that must grow while old
+  readers keep parsing. The receipt is three fields the shipped applier already
+  writes, promoted here rather than redesigned — a required `v` would make the
+  published parser reject every receipt in existence. A fourth fact arrives as a
+  new key or a versioned successor schema, never by widening this row.
+- **CAPTURE AND ACCEPT ARE DIFFERENT NUMBERS, and collapsing them is a SILENT
+  REJECTION.** `ANCHOR_CONTEXT_CHARS` (32) is how much context a CONSTRUCTOR
+  captures either side of a range; `ANCHOR_AFFIX_MAX_CHARS` (64) is the largest
+  affix `CommentAnchorSchema` will ACCEPT. The gap is the point, not an
+  oversight: the capture width is a write-side choice that may change, while the
+  accept bound is a promise made to every anchor already in storage — durable
+  jsonb the server never re-validates. Narrowing accept to capture refuses
+  anchors a client with a wider capture already wrote; widening capture past
+  accept composes anchors the boundary then refuses, losing a comment AFTER it
+  was written. Both numbers now have exactly one declaration each, in
+  `./anchor-constants`, which is what keeps a schema change and a constructor
+  change from drifting apart — but nothing mechanical stops the two from being
+  set equal, so the distinction lives here.
+- **Composing an anchor refuses rather than truncates, for the same reason
+  resolving it refuses rather than guesses.** `createTextAnchorFromRange` and
+  `createTextInsertionAnchorAt` return `null` for a non-integer or out-of-order
+  range, a range outside the text, an EMPTY range (the zero-width case has its
+  own constructor) and a quote past `QUOTE_MAX_CHARS`. A truncated quote yields
+  an anchor that parses, passes the boundary and resolves — onto a range the
+  caller never selected. Both validate the object they built through
+  `CommentAnchorSchema` before returning it, so the only anchors this package
+  emits are anchors the route boundary accepts: an anchor rejected there is a
+  comment lost AFTER it was composed.
+- **The relative-position fields are never produced here, and their absence is
+  a fact, not an omission.** Encoding a `Y.RelativePosition` needs `yjs`, which
+  the vocabulary-guard forbids this package from importing, and it needs a live
+  replica besides. A consumer holding a `Y.Text` merges `relStart`/`relEnd` (or
+  `relPos`) onto the returned anchor itself — the same seam `./resolve` holds,
+  where a consumer composes rung 1 on top of the published text-only ladder.
 - **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
@@ -93,32 +200,68 @@ arbitrate — see the first invariant.
 
 ## Public API
 
-| Export                            | Description                                                                 |
-| --------------------------------- | --------------------------------------------------------------------------- |
-| `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                              |
-| `CommentThreadStatusSchema`       | Zod mirror of `COMMENT_THREAD_STATUSES`                                     |
-| `COMMENT_SUBJECT_TYPES`           | What a thread can hang off — closed, sized to what admits comments          |
-| `CommentSubjectTypeSchema`        | Zod mirror of `COMMENT_SUBJECT_TYPES`                                       |
-| `CommentMentionSchema`            | One mention: user id, nullable UTF-16 range, read-time display name         |
-| `CommentSchema`                   | One comment; `body` null iff soft-deleted (infers `CommentProjection`)      |
-| `CommentThreadSummarySchema`      | A thread without its comments — the resolve/reopen response                 |
-| `CommentThreadSchema`             | A thread with all its comments, oldest-first, tombstones included           |
-| `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   |
+| Export                            | Description                                                                    |
+| --------------------------------- | ------------------------------------------------------------------------------ |
+| `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                                 |
+| `CommentThreadStatusSchema`       | Zod mirror of `COMMENT_THREAD_STATUSES`                                        |
+| `COMMENT_SUBJECT_TYPES`           | What a thread can hang off — closed, sized to what admits comments             |
+| `CommentSubjectTypeSchema`        | Zod mirror of `COMMENT_SUBJECT_TYPES`                                          |
+| `CommentMentionSchema`            | One mention: user id, nullable UTF-16 range, read-time display name            |
+| `CommentSchema`                   | One comment; `body` null iff soft-deleted (infers `CommentProjection`)         |
+| `CommentThreadSummarySchema`      | A thread without its comments — the resolve/reopen response                    |
+| `CommentThreadSchema`             | A thread with all its comments, oldest-first, tombstones included              |
+| `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      |
+| `ANCHOR_CONTEXT_CHARS`            | `32` — how much context a CONSTRUCTOR captures either side of a range          |
+| `ANCHOR_AFFIX_MAX_CHARS`          | `64` — the largest affix the schema ACCEPTS (prefix/suffix/left/right)         |
+| `QUOTE_MAX_CHARS`                 | `2000` — the largest `quote` a text anchor may carry                           |
+| `RELATIVE_POSITION_MAX_CHARS`     | `512` — cap on one encoded `Y.RelativePosition`, in base64 chars               |
+| `resolveAnchorFromText`           | Anchor + text → `AnchorResolution`. Total, pure, text-only; never throws       |
+| `AnchorResolution`                | `resolved{start,end,rung}` \| `document` \| `orphaned` — three outcomes        |
+| `findSoleOccurrence`              | `absent` \| `unique{index}` \| `ambiguous`; overlaps count, empty is ambiguous |
+| `Occurrence`                      | The result of `findSoleOccurrence`                                             |
+| `contextsMatchAt`                 | Do these contexts still flank this point — with the two length guards          |
+| `contextBefore` / `contextAfter`  | Capture `ANCHOR_CONTEXT_CHARS` of context, never splitting a surrogate pair    |
+| `anchorStillReads`                | The SECOND assertion: does the resolved place still hold what the anchor says  |
+| `plannedEdit`                     | Suggestion + resolution → the one mutation, or `null` when it would do nothing |
+| `PlannedEdit`                     | `{at, deleteLength, insert}` — delete then insert, at one point                |
+| `createTextAnchorFromRange`       | Range → validated text anchor, or `null`; refuses rather than truncates        |
+| `createTextInsertionAnchorAt`     | Point → validated zero-width anchor, or `null`; no relative position           |
+| `TextRange`                       | `{text, start, end}` — the offsets travel WITH the string they index           |
+| `SUGGESTION_RECEIPTS_MAP`         | `suggestionReceipts` — the root map key, keyed within by thread id             |
+| `SuggestionReceiptSchema`         | `{claimToken, appliedAt, byUserId}`, strict; no `v`, and that is deliberate    |
+| `SuggestionReceipt`               | One applied suggestion's durable proof that its edit landed in the body        |
+| `readSuggestionReceipt`           | Unknown → receipt or `null`; a malformed row is dropped, never surfaced        |
 
 ## Dependencies
 
 - `zod` — schemas are canonical, types are inferred.
-- `./anchor` ← `./schemas`; `./suggestion` is a leaf (zod only) so `./schemas`
-  can import the thread-kind projection from it without a cycle.
+- `./anchor-constants` ← `./anchor` ← `./schemas`; `./anchor-constants` is a
+  leaf with no imports at all (four numbers and their rationale), so the bounds
+  can be read by a constructor without pulling in the schema. `./resolve` sits
+  beside `./schemas` on that chain — it imports `./anchor-constants` for the
+  capture width and the anchor union as a TYPE only, so nothing about the
+  interpretation can drift from the shape it interprets. `./verify` sits one
+  step further out, importing `contextsMatchAt` from `./resolve` at runtime
+  rather than re-deriving it — 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. `./create` sits beside `./verify`,
+  importing `contextBefore`/`contextAfter` from `./resolve` at runtime and
+  `CommentAnchorSchema` from `./anchor` — the construction half must capture
+  exactly what the resolution half searches for, and validate against exactly
+  the schema the boundary applies, so neither is re-derived. `./suggestion` is
+  likewise a leaf (zod only) so `./schemas` can import the thread-kind
+  projection from it without a cycle. `./receipt` is a leaf for the same
+  reason — zod only, no reach for the anchor or the ladder — so anything in this
+  directory can import it later without one.
 - 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

package/src/comments/__tests__/README.md

@@ -33,6 +33,49 @@ text-anchor fields` name the two failure modes the strict variants exist for,
   anything the typechecker reaches would fail the build. Reading it keeps the
   fixture inert regardless of which file loads it. `node:fs` is fine in here —
   the vocabulary-guard skips `__tests__/`.
+- **Every `orphaned` expectation in `resolve.test.ts` is a case where a
+  FIRST-MATCH resolver returns a well-formed range.** That is the whole point of
+  those fixtures: the plausible wrong implementation never throws and never
+  looks broken — it produces a confident highlight on a paragraph the comment's
+  author never saw. A suite that only asserted the happy path would sit green
+  over it, so the refusals are the load-bearing half.
+- **Every `toBeNull()` expectation in `verify.test.ts` is a case where a
+  no-op-tolerant `plannedEdit` returns a well-formed edit.** `{ at,
+deleteLength: 0, insert: "" }` is a valid mutation that applies without error
+  and changes not one character; its symptom is a thread reported as `accepted`
+  over a document that never received the proposal. Same shape of argument as
+  the `orphaned` expectations above: the refusals are the load-bearing half.
+- **`verify.test.ts` builds the `document`-anchor resolution BY HAND, and that
+  is not a smell.** The shipped ladder answers `{ status: "document" }` for that
+  variant and never a `resolved`, so the case is unreachable through
+  `resolveAnchorFromText` — but a consumer's own Yjs rung can hand one in, and
+  the refusal is what makes that harmless.
+- **`create.test.ts` asserts against the SHIPPED resolver, not against the
+  anchor's fields.** A suite that only checked `prefix`/`quote`/`suffix` would
+  sit green over a capture width that disagreed with what the resolver searches
+  for — the two halves have to agree about the same geometry, and the round-trip
+  is the only assertion that says so. Its `toBeNull()` cases are the same shape
+  of argument as the `orphaned` ones: the truncating constructor returns a
+  well-formed anchor that parses, passes the boundary and resolves onto a range
+  the caller never selected.
+- **The surrogate round-trip is built so BOTH context windows land inside an
+  astral character.** The prefix window opens on the low half of one emoji and
+  the suffix window closes on the high half of another, because a blind slice
+  only emits a lone surrogate when the boundary actually falls there — a fixture
+  with emoji merely present would pass under the broken implementation.
+- **Every `toBeNull()` in `receipt.test.ts` is a row the PASS-THROUGH parser
+  hands back as an object.** `(v) => v as SuggestionReceipt` compiles, is green
+  on every well-formed row and never throws; it fails only when a peer writes
+  something else into the map, and then a row whose `claimToken` is `undefined`
+  reads as "this edit already landed" — the accept control is withdrawn from a
+  live suggestion with no way back. The `NaN`/`Infinity` cases are not
+  theoretical: a CRDT map replicates raw JavaScript values with no schema of its
+  own, so a peer can put a literal `NaN` in `appliedAt`.
+- **`SUGGESTION_RECEIPTS_MAP` is tested by restating its wire literal.** It
+  names a root map, so a rename is silent on both ends — the writer's receipt
+  lands where nobody reads, the reader watches where nobody writes. Asserting
+  `toBe("suggestionReceipts")` makes a rename a red test rather than a second
+  name. Same convention as `COMPANY_MD_COLLAB_TEXT_KEY` in `../../org`.
 - **Negative tests mutate ONE field of a well-formed factory result.** A
   hand-built broken object can pass for the wrong reason: it fails because of
   the field nobody was testing.
@@ -46,4 +89,20 @@ None — test-only.
 - `vitest` — `describe` / `it` / `expect`.
 - `node:fs`, `node:path`, `node:url` — to read the corpus and its pin from disk.
 - `node:crypto` — to re-derive the corpus digest.
-- `../anchor`, `../schemas` — the schemas under test.
+- `../anchor`, `../anchor-constants`, `../schemas` — the schemas and bounds
+  under test.
+- `../resolve` — the published resolver. `resolve.test.ts` drives it over the
+  SAME corpus rows `anchor-corpus.test.ts` re-derives by hand, which is what
+  makes that hand-rolled seam scan a cross-check of the shipped implementation
+  rather than of itself.
+- `../suggestion`, `../verify` — the canonical payload and the two total
+  functions the acceptance path runs before it writes. `verify.test.ts` takes
+  its resolutions from the SHIPPED resolver wherever the ladder can produce one,
+  so the geometry under test is the geometry a real applier is handed.
+- `../create` — the construction half. `create.test.ts` feeds every constructed
+  anchor back through `../resolve`, so it is a cross-check of the two published
+  halves against each other rather than of either against a restatement of
+  itself.
+- `../receipt` — the application receipt's key, schema and parser.
+  `receipt.test.ts` asserts the parser and the schema agree on the same row, so
+  a hand-rolled second set of checks beside the schema cannot drift from it.