@company-semantics/contracts 45.1.0 → 45.3.0

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);
+  });
+});

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

@@ -0,0 +1,58 @@
+# comments/\_\_tests\_\_/fixtures/
+
+## Purpose
+
+Holds `comment-anchors.json`, the **stable contract corpus** for the comment
+anchor — named accept and reject cases that `CommentAnchorSchema` is run over by
+`../anchor-corpus.test.ts`.
+
+The file is a directory of its own rather than a `fixtures.ts` module (the shape
+used elsewhere under `src/`) for one reason: it is **not this repo's file**. It
+is a byte-for-byte copy of
+`company-semantics-backend/tests/fixtures/comment-anchors.json`, and keeping it
+as inert data in a directory of its own is what makes "copied, never edited"
+obvious to the next reader.
+
+## Invariants
+
+- **The file is copied BYTE-FOR-BYTE from the backend suite.** The backend route
+  boundary is the only place a comment anchor is ever validated (it stores
+  opaque jsonb and interprets nothing), so the corpus the boundary is tested
+  with and the corpus the published contract is tested with must be the same
+  bytes. If they were merely "kept in sync by hand", the one risk this whole
+  domain exists to manage — silent app/contracts drift on a shape no server
+  checks — would be back.
+- **Only ONE direction of that copy is gated, and it is this one.**
+  `comment-anchors.provenance.json` pins the copy's sha256 and byte length, and
+  `../anchor-corpus.test.ts` re-derives both on every run — so an edit made
+  here fails CI. A change made in the BACKEND file is invisible from this repo:
+  contracts CI checks out one repo and must not depend on the backend to look.
+  `pnpm anchor-corpus:check` diffs the live upstream file when a backend tree is
+  reachable and says so when it is not. See ADR-CONTRACTS-116 for where the
+  upstream gate belongs (backend CI, via `node_modules`).
+- **Never hand-tune this file.** Change the anchor schema and the corpus
+  together, in the backend, then re-copy with `pnpm anchor-corpus:sync`, which
+  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.
+- **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
+  ignored — it is this repo's file and Prettier owns its formatting.
+- **Cases are addressed by `name`, not by index.** Both tests iterate the
+  `accept` and `reject` arrays and use each case's `name` as its test label, so
+  a case added upstream is covered here the moment it is copied over, with no
+  edit to the test.
+
+## Public API
+
+None — test-only fixture data. `comment-anchors.provenance.json` is generated;
+regenerate it with `pnpm anchor-corpus:sync` rather than editing it.
+
+## Dependencies
+
+- Upstream source: `company-semantics-backend/tests/fixtures/comment-anchors.json`
+  (authored alongside the anchor boundary; see backend ADR slug
+  `polymorphic-comment-threads`).
+- `scripts/anchor-corpus.ts` — writes the pin (`--sync`) and verifies it
+  (`--check`, the default).

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

@@ -0,0 +1,94 @@
+{
+  "$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.",
+  "accept": [
+    {
+      "name": "document-anchor",
+      "anchor": { "type": "document", "v": 1 }
+    },
+    {
+      "name": "text-anchor-with-relative-positions",
+      "anchor": {
+        "type": "text",
+        "v": 1,
+        "relStart": "AAECAwQ=",
+        "relEnd": "BQYHCAk=",
+        "quote": "ship the quarterly goals",
+        "prefix": "agreed to ",
+        "suffix": " by March"
+      }
+    },
+    {
+      "name": "text-anchor-quote-only",
+      "anchor": {
+        "type": "text",
+        "v": 1,
+        "quote": "ship the quarterly goals",
+        "prefix": "",
+        "suffix": ""
+      }
+    }
+  ],
+  "reject": [
+    {
+      "name": "text-anchor-missing-quote",
+      "anchor": { "type": "text", "v": 1, "prefix": "agreed to ", "suffix": " by March" }
+    },
+    {
+      "name": "document-anchor-carrying-text-fields",
+      "anchor": {
+        "type": "document",
+        "v": 1,
+        "quote": "stray quote",
+        "prefix": "",
+        "suffix": ""
+      }
+    },
+    {
+      "name": "unknown-version-document",
+      "anchor": { "type": "document", "v": 2 }
+    },
+    {
+      "name": "unknown-version-text",
+      "anchor": { "type": "text", "v": 2, "quote": "q", "prefix": "", "suffix": "" }
+    },
+    {
+      "name": "unknown-anchor-type",
+      "anchor": { "type": "region", "v": 1 }
+    },
+    {
+      "name": "oversized-prefix",
+      "anchor": {
+        "type": "text",
+        "v": 1,
+        "quote": "q",
+        "prefix": "ppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppp",
+        "suffix": ""
+      }
+    },
+    {
+      "name": "oversized-suffix",
+      "anchor": {
+        "type": "text",
+        "v": 1,
+        "quote": "q",
+        "prefix": "",
+        "suffix": "sssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss"
+      }
+    },
+    {
+      "name": "empty-quote",
+      "anchor": { "type": "text", "v": 1, "quote": "", "prefix": "", "suffix": "" }
+    },
+    {
+      "name": "relstart-not-base64",
+      "anchor": {
+        "type": "text",
+        "v": 1,
+        "relStart": "not base64!!",
+        "quote": "q",
+        "prefix": "",
+        "suffix": ""
+      }
+    }
+  ]
+}

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

@@ -0,0 +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.",
+  "source": {
+    "repo": "company-semantics-backend",
+    "path": "tests/fixtures/comment-anchors.json"
+  },
+  "bytes": 2649,
+  "sha256": "84fa0040c9acc166a5551185950e5dc8afffcc5fd63a1f17080422318b405c8c"
+}