@company-semantics/contracts 45.2.0 → 46.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "45.2.0",
+  "version": "46.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -48,6 +48,10 @@
       "types": "./src/chat/index.ts",
       "default": "./src/chat/index.ts"
     },
+    "./comments": {
+      "types": "./src/comments/index.ts",
+      "default": "./src/comments/index.ts"
+    },
     "./api": {
       "types": "./src/api/index.ts",
       "default": "./src/api/index.ts"
@@ -105,6 +109,8 @@
     "test": "NODE_OPTIONS='--max-old-space-size=4096' bash scripts/vitest-run.sh run",
     "test:run": "NODE_OPTIONS='--max-old-space-size=4096' bash scripts/vitest-run.sh run",
     "color": "tsx scripts/color.ts",
+    "anchor-corpus:check": "tsx scripts/anchor-corpus.ts",
+    "anchor-corpus:sync": "tsx scripts/anchor-corpus.ts --sync",
     "generate:spec-hash": "tsx scripts/generate-spec-hash.ts",
     "generate:spec-hash:check": "tsx scripts/generate-spec-hash.ts --check",
     "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash && pnpm generate:openapi-routes",
@@ -149,6 +155,7 @@
     "overrides": {
       "brace-expansion@<5.0.9": ">=5.0.9",
       "minimatch@<10.2.3": ">=10.2.3",
+      "nanoid@<3.3.17": ">=3.3.17",
       "js-yaml@>=4.0.0 <4.3.1": ">=4.3.1 <5.0.0",
       "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2 <6.0.0",
       "picomatch@<4.0.4": ">=4.0.4",
@@ -163,5 +170,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "795d779110bb8dee6374229e227dc7b7e813197c34a35bbe2066113e0939a988"
+  "securityRequirementsVersion": "dfe68368cb5b7fdc67290fba5cd5a920c9a2ca9c20a9e297232a467b2022e5b5"
 }

package/src/__tests__/resource-keys.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import {
   toQueryKey,
   fromQueryKey,
+  isResourceKeyShape,
   matchesResourceKey,
   type ResourceKey,
 } from "../resource-keys.js";
@@ -172,3 +173,61 @@ describe("resource-keys: companyMdAccessRequests (per-doc identity)", () => {
     expect(matchesResourceKey(toQueryKey(key), docKey)).toBe(false);
   });
 });
+
+describe("resource-keys: commentThreads (composite subject identity)", () => {
+  // The FIRST member of the union whose identity needs two segments. Every
+  // other key is [type, scope] or [type, scope, oneId], and `fromQueryKey`'s
+  // single-field path hard-asserts exactly two trailing segments — so this key
+  // exercises machinery nothing else does. See ADR-CONTRACTS-116.
+  const SUBJECT_ID = "77777777-7777-4777-8777-777777777777";
+  const key: ResourceKey = {
+    type: "commentThreads",
+    orgId: ORG_ID,
+    subjectType: "company_md",
+    subjectId: SUBJECT_ID,
+  };
+
+  it("serialises to [type, orgId, subjectType, subjectId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["commentThreads", ORG_ID, "company_md", SUBJECT_ID]);
+    expect(qk).toHaveLength(4);
+  });
+
+  it("round-trips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("is recognised by isResourceKeyShape", () => {
+    // The wire-boundary predicate the user-event schema gates
+    // `resource.invalidated` payloads on. It counts scope discriminators, and a
+    // key with two identity segments must still present exactly ONE scope —
+    // otherwise the coalescer drops every comment invalidation frame.
+    expect(isResourceKeyShape(key)).toBe(true);
+  });
+
+  it("discriminates two subjects of the same CLASS", () => {
+    const other: ResourceKey = {
+      ...key,
+      subjectId: "88888888-8888-4888-8888-888888888888",
+    };
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(toQueryKey(other), key)).toBe(false);
+  });
+
+  it("discriminates two subjects that share an ID across CLASSES", () => {
+    // The reason subjectType is in the key at all. Subject ids are per-class
+    // uuids; without the class segment, invalidating one class's thread list
+    // would flush another's for a colliding id.
+    const other: ResourceKey = { ...key, subjectType: "work_item" };
+    expect(matchesResourceKey(toQueryKey(other), key)).toBe(false);
+    expect(matchesResourceKey(toQueryKey(key), other)).toBe(false);
+  });
+
+  it("refuses a query key that is missing a segment", () => {
+    // A three-segment key would otherwise parse as some OTHER shape and hand
+    // the caller a ResourceKey with an undefined subjectId.
+    expect(() =>
+      fromQueryKey(["commentThreads", ORG_ID, "company_md"]),
+    ).toThrow(/commentThreads/);
+  });
+});

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 = '7f497f657ee3' as const;
-export const SPEC_HASH_FULL = '7f497f657ee3f1a81b096b02094743f5e0fa6a3d03c0bb92cdb0034762ca3ee7' as const;
+export const SPEC_HASH = '9421bda67789' as const;
+export const SPEC_HASH_FULL = '9421bda67789792a5303137aaeb2f7f886cb490e8db9bee11e03f2de13f94806' as const;

package/src/api/generated.ts

@@ -1531,6 +1531,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/docs/{id}/mentionable": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the document readers the caller may mention */
+        get: operations["listCompanyMdMentionableUsers"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/extract": {
         parameters: {
             query?: never;
@@ -3614,6 +3631,7 @@ export interface components {
             };
             candidateKey: string;
             contentSha256: string;
+            sourceSha256: string;
         };
         ResyncSlackAvatarCommitResponse: {
             /** @constant */
@@ -3628,6 +3646,7 @@ export interface components {
         ResyncSlackAvatarCommitRequest: {
             candidateKey: string;
             contentSha256: string;
+            sourceSha256: string;
         };
         SamlCallbackRequest: {
             SAMLResponse: string;
@@ -4891,6 +4910,10 @@ export interface components {
             seq: string;
             update: string;
         };
+        /** @description The document readers the caller may mention, ordered and bounded. */
+        CompanyMdMentionableResponse: {
+            items: components["schemas"]["CompanyMdMentionableCandidate"][];
+        };
         CompanyMdContextBankResponse: {
             items: {
                 id: string;
@@ -5737,7 +5760,7 @@ export interface components {
                 notification: {
                     id: string;
                     /** @enum {string} */
-                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied";
+                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply";
                     target: {
                         /** @enum {string} */
                         type: "company_md" | "org_unit" | "org" | "execution";
@@ -6278,6 +6301,12 @@ export interface components {
             subjectId: string;
             anchor: components["schemas"]["CommentAnchor"];
             body: string;
+            mentions?: {
+                /** Format: uuid */
+                userId: string;
+                startOffset: number;
+                endOffset: number;
+            }[];
         };
         /** @description The written reply, and whether it auto-reopened a resolved thread. */
         CommentReplyResponse: {
@@ -6286,6 +6315,12 @@ export interface components {
         };
         CommentReplyRequest: {
             body: string;
+            mentions?: {
+                /** Format: uuid */
+                userId: string;
+                startOffset: number;
+                endOffset: number;
+            }[];
         };
         /** @description The comment after the mutation (redacted projection after delete). */
         CommentResponse: {
@@ -6293,6 +6328,12 @@ export interface components {
         };
         EditCommentRequest: {
             body: string;
+            mentions?: {
+                /** Format: uuid */
+                userId: string;
+                startOffset: number;
+                endOffset: number;
+            }[];
         };
         /** @description The thread after a resolve/reopen transition. */
         CommentThreadSummaryResponse: {
@@ -6303,6 +6344,12 @@ export interface components {
             maxUpdateBytes: number;
             maxDocTextBytes: number;
         };
+        /** @description A principal who can read the document and may therefore be mentioned. */
+        CompanyMdMentionableCandidate: {
+            userId: string;
+            displayName: string;
+            avatarUrl: string | null;
+        };
         /** @description An ACL-admitted context-doc discovery hit. */
         ContextDocDiscoveryHit: {
             id: string;
@@ -6360,7 +6407,14 @@ export interface components {
             editedAt: string | null;
             deletedAt: string | null;
             createdAt: string;
-            mentions: string[];
+            mentions: components["schemas"]["CommentMention"][];
+        };
+        /** @description One mention on a comment: the mentioned user id, its zero-based exclusive-end UTF-16 range (null until the offset columns exist), and the display name resolved at read time. */
+        CommentMention: {
+            userId: string;
+            startOffset: number | null;
+            endOffset: number | null;
+            displayName: string;
         };
         /** @description A comment thread without its comments. */
         CommentThreadSummary: {
@@ -8774,6 +8828,45 @@ export interface operations {
             };
         };
     };
+    listCompanyMdMentionableUsers: {
+        parameters: {
+            query?: {
+                q?: string;
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Document readers the caller may mention, ordered and bounded */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdMentionableResponse"];
+                };
+            };
+            /** @description Invalid query parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Document not found, or the caller may not comment on it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     extractCompanyMd: {
         parameters: {
             query?: never;

package/src/comments/README.md

@@ -0,0 +1,115 @@
+# comments/
+
+## Purpose
+
+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`).
+
+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.
+
+## 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
+  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.
+- **`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
+  anchor shapes arrive as new `v` variants, never as a migration of an existing
+  one.
+- **`quote` is required on a text anchor; `relStart`/`relEnd` are not.** The
+  quote is the durable fallback a resolving client re-finds the passage by once
+  the relative positions stop resolving. A comment authored from a card has no
+  attached collab session and can only produce the quote path — optional there
+  means "this client could not", never "this client chose not to".
+- **The anchor variants are STRICT.** A document anchor carrying `quote` or
+  `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 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
+  `(createdAt ASC, id ASC)` sequence so the surrounding replies still read in
+  order, and a thread whose comments were all deleted stays distinguishable from
+  one that never had any. The rule is documented and writer-enforced rather than
+  expressed as a Zod refinement: a refinement would make this package refuse a
+  response the server is willing to emit, and it cannot appear in the OpenAPI
+  surface, so it would become a third description of the wire shape that no
+  parity guard can check.
+- **Mention offsets are ZERO-BASED, EXCLUSIVE-END UTF-16 CODE UNITS** into the
+  exact body string — plain JavaScript string coordinates. An emoji counts as
+  two units, so a client measuring in code points slides off by one per
+  preceding emoji, and **no Unicode normalization happens anywhere on this
+  path**: normalising before measuring changes the length and desynchronises
+  every offset after the first composed character.
+- **Mention identity renders from the mention row, never from the body
+  characters under the range.** A stale or forged range can only
+  mis-**highlight**; it can never misattribute a mention to the wrong person.
+  Offsets are nullable (and null on every row today, pending the offset
+  columns) — treat null as "highlight nothing", not as an error.
+- **These shapes are MIRRORED from the backend route boundary, not authored
+  here.** Every bound matches
+  `company-semantics-backend/src/api/http/routes/comments/comments.schemas.ts`,
+  and therefore matches the generated `components["schemas"]` view in `../api`.
+  The accept/reject corpus in `__tests__/fixtures/comment-anchors.json` is
+  copied **byte-for-byte** from that repo's `tests/fixtures/`. Only this side of
+  that copy is gated: its digest is pinned in
+  `__tests__/fixtures/comment-anchors.provenance.json` and re-derived on every
+  test run, so the corpus cannot be edited here quietly. A change made at the
+  boundary is NOT caught from this repo — nothing in a single-repo CI run can
+  see that file, and this package must not depend on the backend to look. See
+  ADR-CONTRACTS-116 for the split and for where the upstream gate belongs.
+- **Request bodies are NOT here** (ADR-CONT-029), and one of them must never
+  be: the mention set on a write is validated against a candidate list the
+  server derives from `effective_acl_grants`, so nothing a client sends may
+  widen who can be mentioned.
+
+## Public API
+
+| Export                            | Description                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------- |
+| `CommentAnchorSchema`             | `{document,v:1}` \| `{text,v:1,…}`, strict, discriminated on `type`         |
+| `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`                                 |
+
+## Dependencies
+
+- `zod` — schemas are canonical, types are inferred.
+- `./anchor` ← `./schemas`. 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.
+
+## Related vocabulary elsewhere in this package
+
+- `../resource-keys` carries `commentThreads` — the SSE coalescer's key for "the
+  threads on this subject". It lives there rather than app-locally because the
+  key registry **is** the coalescer's vocabulary; an unregistered key cannot be
+  routed through it.
+- `../user-notifications` carries `comment.mention` and `comment.reply` — the
+  durable inbox rows a comment produces.
+- `../notifications` carries the same two names as composable notifications —
+  the message that leaves the building. The overlap is expected and is the same
+  one `companyMd.access_requested` already has; the two unions are not derived
+  from each other.

package/src/comments/__tests__/README.md

@@ -0,0 +1,49 @@
+# comments/\_\_tests\_\_/
+
+## Purpose
+
+Contract tests for the published comment vocabulary: the anchor union against
+the mirrored corpus (`anchor-corpus.test.ts`), and the thread/comment/mention
+projections against the invariants their JSDoc claims (`schemas.test.ts`).
+
+## Invariants
+
+- **The anchor suite is DRIVEN BY THE CORPUS, not by hand-copied cases.** It
+  iterates every `accept` and every `reject` entry in
+  `./fixtures/comment-anchors.json` — a byte-for-byte copy of the backend's
+  fixture file — so a case added at the boundary is covered here as soon as the
+  file is re-copied, with no test edit. Hand-copying the cases would let the two
+  suites diverge silently, which is exactly the failure this domain exists to
+  prevent.
+- **The corpus's digest is pinned, and that pin is the only mechanical part of
+  the anti-drift story that runs in this repo's CI.** `the corpus is still the
+backend's bytes` re-derives the sha256 of `./fixtures/comment-anchors.json`
+  and compares it to `./fixtures/comment-anchors.provenance.json`, so editing
+  the corpus here — rather than upstream, then re-copying — fails. It does not
+  and cannot notice a change made in the backend file: a single-repo CI checkout
+  never sees it. `pnpm anchor-corpus:check` covers that half only where a
+  backend working tree is reachable, and reports when it is not.
+- **The named rejection tests are additional, not a substitute.** `rejects a
+text anchor with no quote` and `rejects a document anchor carrying
+text-anchor fields` name the two failure modes the strict variants exist for,
+  in prose, so a reader of the test list can see them without decoding fixture
+  names. The corpus covers the same ground mechanically; both are wanted.
+- **The corpus file is read with `readFileSync` + `JSON.parse`, not imported.**
+  `src/tsconfig.json` does not set `resolveJsonModule`, so a JSON import from
+  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__/`.
+- **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.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+- `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.

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

@@ -0,0 +1,202 @@
+/**
+ * The anchor union, held to the SAME corpus the backend route boundary is held
+ * to (ADR-CONTRACTS-116).
+ *
+ * WHY THIS SUITE IS FIXTURE-DRIVEN RATHER THAN HAND-WRITTEN. The backend
+ * validates an anchor's shape once, at the route boundary, and then stores
+ * opaque jsonb it never interprets. So nothing on the server can notice if this
+ * package's idea of a valid anchor drifts from that boundary's — the write
+ * succeeds, the read succeeds, and a comment lands on the wrong text.
+ * `./fixtures/comment-anchors.json` is therefore a byte-for-byte copy of the
+ * backend's fixture file, and this file runs `CommentAnchorSchema` over every
+ * case in it. A case added at the boundary is covered here the moment the file
+ * is re-copied. Hand-copying the cases would reintroduce exactly the drift the
+ * copy exists to prevent.
+ *
+ * The pinned-digest test below is the part of that defence that is MECHANICAL
+ * in this repo's CI: it re-derives the corpus's sha256 and compares it to
+ * `./fixtures/comment-anchors.provenance.json`, so an edit made on THIS side
+ * fails here. Drift introduced on the BACKEND side is NOT gated from contracts
+ * CI — a single-repo checkout cannot see that file, and this package must not
+ * depend on the backend to look. `pnpm anchor-corpus:check` diffs the live
+ * upstream file where a backend tree is reachable, `pnpm anchor-corpus:sync`
+ * re-copies, and ADR-CONTRACTS-116 records that the upstream half is still a
+ * documented promise rather than a gate.
+ *
+ * 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.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { CommentAnchorSchema } from "../anchor.js";
+
+/** One named case from the corpus. */
+interface AnchorCase {
+  name: string;
+  anchor: unknown;
+}
+
+/** The subset of `comment-anchors.provenance.json` this suite enforces. */
+interface CorpusPin {
+  source: { repo: string; path: string };
+  bytes: number;
+  sha256: string;
+}
+
+/**
+ * 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[];
+};
+
+const PIN_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "fixtures",
+  "comment-anchors.provenance.json",
+);
+
+describe("the corpus is still the backend's bytes", () => {
+  it("matches the digest pinned when it was copied", () => {
+    // The one check in this repo that notices the corpus being EDITED rather
+    // than re-copied. Without it, "byte-for-byte copy" is a comment: a case
+    // hand-tuned here to make a red test green would pass, and the published
+    // contract would quietly become its own authority instead of the
+    // boundary's mirror. Bytes, not parsed JSON — a reflow that preserves the
+    // parse still breaks the copy, which is why the file is in /.prettierignore.
+    //
+    // This does NOT see a change made upstream; nothing in a single-repo CI run
+    // can. See the file header and ADR-CONTRACTS-116.
+    const pin = JSON.parse(readFileSync(PIN_PATH, "utf8")) as CorpusPin;
+    const bytes = readFileSync(CORPUS_PATH);
+
+    expect(bytes.byteLength).toBe(pin.bytes);
+    expect(createHash("sha256").update(bytes).digest("hex")).toBe(pin.sha256);
+  });
+
+  it("names the upstream file it was copied from", () => {
+    // The pin is also the pointer a reader needs to run the diff by hand, so an
+    // emptied or reshaped source block is a failure, not a formality.
+    const pin = JSON.parse(readFileSync(PIN_PATH, "utf8")) as CorpusPin;
+
+    expect(pin.source.repo).toBe("company-semantics-backend");
+    expect(pin.source.path).toBe("tests/fixtures/comment-anchors.json");
+  });
+});
+
+describe("CommentAnchorSchema against the mirrored corpus", () => {
+  it("has both halves of the corpus, so neither loop can pass vacuously", () => {
+    // An empty array iterates cleanly and reports as a passing suite. This is
+    // the only assertion that notices a corpus copied as an empty shell.
+    expect(corpus.accept.length).toBeGreaterThan(0);
+    expect(corpus.reject.length).toBeGreaterThan(0);
+  });
+
+  for (const { name, anchor } of corpus.accept) {
+    it(`accepts ${name}`, () => {
+      expect(CommentAnchorSchema.safeParse(anchor).success).toBe(true);
+    });
+  }
+
+  for (const { name, anchor } of corpus.reject) {
+    it(`rejects ${name}`, () => {
+      expect(CommentAnchorSchema.safeParse(anchor).success).toBe(false);
+    });
+  }
+});
+
+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
+    // passage by once the relative positions stop resolving, and the composer's
+    // `Comment on "…"` label. An anchor without one is unplaceable the first
+    // time the document is edited, so it must never reach storage.
+    expect(
+      CommentAnchorSchema.safeParse({
+        type: "text",
+        v: 1,
+        prefix: "agreed to ",
+        suffix: " by March",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a document anchor carrying text-anchor fields", () => {
+    // The variants are STRICT on purpose. A client that sent `quote` on a
+    // document anchor meant to anchor to text and got the discriminator wrong;
+    // accepting it with the extras dropped stores a thread that can never be
+    // placed, and nothing downstream would ever flag it.
+    expect(
+      CommentAnchorSchema.safeParse({
+        type: "document",
+        v: 1,
+        quote: "stray quote",
+        prefix: "",
+        suffix: "",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects an unknown version on either variant", () => {
+    // `v` is the evolution hatch: a NEW shape is a new `v`, so a client must
+    // never accept a `v` it does not know and guess at the fields it
+    // half-recognises.
+    expect(
+      CommentAnchorSchema.safeParse({ type: "document", v: 2 }).success,
+    ).toBe(false);
+    expect(
+      CommentAnchorSchema.safeParse({
+        type: "text",
+        v: 2,
+        quote: "q",
+        prefix: "",
+        suffix: "",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a relative position that is not base64", () => {
+    // The backend never decodes these, so the charset bound is the ONLY thing
+    // standing between a malformed position and a client that cannot decode it
+    // either. This is the case a looser `z.string().max(4096)` would let
+    // through.
+    expect(
+      CommentAnchorSchema.safeParse({
+        type: "text",
+        v: 1,
+        relStart: "not base64!!",
+        quote: "q",
+        prefix: "",
+        suffix: "",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("accepts a text anchor with only the quote path", () => {
+    // The positive twin of the rule above: a comment authored from a card has
+    // no attached collab session and can produce no relative position at all.
+    // If this ever stops parsing, commenting outside the editor breaks.
+    expect(
+      CommentAnchorSchema.safeParse({
+        type: "text",
+        v: 1,
+        quote: "ship the quarterly goals",
+        prefix: "",
+        suffix: "",
+      }).success,
+    ).toBe(true);
+  });
+});