@company-semantics/contracts 45.2.0 → 45.3.0

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"
+}

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

@@ -0,0 +1,274 @@
+/**
+ * The thread / comment / mention projections, held to the invariants their
+ * JSDoc claims (ADR-CONTRACTS-116).
+ *
+ * Every negative test mutates ONE field of a well-formed factory result. A
+ * hand-built broken object can pass for the wrong reason — it fails on the
+ * field nobody was testing — and these shapes have enough required fields for
+ * that to happen easily.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  COMMENT_SUBJECT_TYPES,
+  COMMENT_THREAD_STATUSES,
+  CommentMentionSchema,
+  CommentSchema,
+  CommentThreadListResponseSchema,
+  CommentThreadSchema,
+  CommentThreadStatusSchema,
+  MentionableResponseSchema,
+} from "../schemas.js";
+
+const THREAD_ID = "11111111-1111-4111-8111-111111111111";
+const COMMENT_ID = "22222222-2222-4222-8222-222222222222";
+const USER_ID = "33333333-3333-4333-8333-333333333333";
+const DOC_ID = "44444444-4444-4444-8444-444444444444";
+
+function makeMention(over: Record<string, unknown> = {}) {
+  return {
+    userId: USER_ID,
+    startOffset: 0,
+    endOffset: 9,
+    displayName: "Sam Chen",
+    ...over,
+  };
+}
+
+function makeComment(over: Record<string, unknown> = {}) {
+  return {
+    id: COMMENT_ID,
+    threadId: THREAD_ID,
+    authorUserId: USER_ID,
+    body: "Should this say Q3 or Q4?",
+    editedAt: null,
+    deletedAt: null,
+    createdAt: "2026-08-01T12:00:00.000Z",
+    mentions: [],
+    ...over,
+  };
+}
+
+function makeThread(over: Record<string, unknown> = {}) {
+  return {
+    id: THREAD_ID,
+    subjectType: "company_md",
+    subjectId: DOC_ID,
+    anchorType: "text",
+    anchor: {
+      type: "text",
+      v: 1,
+      quote: "ship the quarterly goals",
+      prefix: "agreed to ",
+      suffix: " by March",
+    },
+    status: "open",
+    createdByUserId: USER_ID,
+    resolvedByUserId: null,
+    resolvedAt: null,
+    createdAt: "2026-08-01T12:00:00.000Z",
+    updatedAt: "2026-08-01T12:00:00.000Z",
+    comments: [makeComment()],
+    ...over,
+  };
+}
+
+describe("CommentThreadStatus", () => {
+  it("is exactly open and resolved", () => {
+    expect([...COMMENT_THREAD_STATUSES]).toEqual(["open", "resolved"]);
+  });
+
+  it("rejects a thread status outside the enum", () => {
+    // Notably `deleted`: a thread whose comments are all soft-deleted is still
+    // an ordinary resolvable thread, and inventing a third state client-side
+    // would give the resolve/reopen transition somewhere it can never return
+    // from.
+    expect(CommentThreadStatusSchema.safeParse("deleted").success).toBe(false);
+    expect(CommentThreadStatusSchema.safeParse("").success).toBe(false);
+  });
+
+  it("rejects a thread carrying a status outside the enum", () => {
+    expect(
+      CommentThreadSchema.safeParse(makeThread({ status: "archived" })).success,
+    ).toBe(false);
+  });
+});
+
+describe("CommentSubjectType", () => {
+  it("is closed, not a free string", () => {
+    // Sized to the ACL entity types that admit comments. A free string here
+    // would let a client address a subject class the server has no policy for
+    // and read the 404 as "not found" rather than "never supported".
+    expect([...COMMENT_SUBJECT_TYPES]).toEqual([
+      "company_md",
+      "strategy_doc",
+      "work_item",
+      "meeting_recording",
+    ]);
+    expect(
+      CommentThreadSchema.safeParse(makeThread({ subjectType: "chat" }))
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("CommentSchema and the redaction invariant", () => {
+  it("parses a well-formed comment", () => {
+    expect(CommentSchema.safeParse(makeComment()).success).toBe(true);
+  });
+
+  it("parses a soft-deleted comment projection with a null body", () => {
+    // THE TOMBSTONE. A soft-deleted comment is a REDACTED PROJECTION, not a
+    // removed row: body null, mentions empty, everything else retained. If this
+    // stops parsing, a single deleted comment fails the whole thread load —
+    // and the tombstone is what keeps the surrounding replies in order and
+    // keeps an all-deleted thread distinguishable from an empty one.
+    const parsed = CommentSchema.safeParse(
+      makeComment({
+        body: null,
+        deletedAt: "2026-08-02T09:00:00.000Z",
+        mentions: [],
+      }),
+    );
+    expect(parsed.success).toBe(true);
+  });
+
+  it("parses an unattributed comment — a tombstoned author is not an error", () => {
+    expect(
+      CommentSchema.safeParse(makeComment({ authorUserId: null })).success,
+    ).toBe(true);
+  });
+
+  it("requires the mentions array — absent is not the same as empty", () => {
+    const { mentions: _dropped, ...withoutMentions } = makeComment();
+    expect(CommentSchema.safeParse(withoutMentions).success).toBe(false);
+  });
+});
+
+describe("CommentMentionSchema offsets", () => {
+  it("parses a mention whose range is null", () => {
+    // Null on every row today — `comment_mentions` has no offset columns yet.
+    // A client must render these as "highlight nothing", so they must parse.
+    expect(
+      CommentMentionSchema.safeParse(
+        makeMention({ startOffset: null, endOffset: null }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("measures in UTF-16 CODE UNITS, so an emoji costs two", () => {
+    // The convention, pinned by arithmetic rather than by comment. `"🎉 hi "`
+    // is SIX code units — the emoji is a surrogate pair — so the mention that
+    // follows it starts at 6. A client measuring in code points would compute 5
+    // and highlight one character to the left, and would keep sliding by one
+    // per preceding emoji. Nothing normalizes the body on this path, which is
+    // what makes the count on the wire the same count a client can reproduce.
+    const body = "🎉 hi @Sam Chen";
+    expect(body.length).toBe(15);
+    const start = body.indexOf("@");
+    expect(start).toBe(6);
+
+    const comment = CommentSchema.safeParse(
+      makeComment({
+        body,
+        mentions: [makeMention({ startOffset: start, endOffset: body.length })],
+      }),
+    );
+    expect(comment.success).toBe(true);
+    // endOffset is EXCLUSIVE: slicing [start, end) yields exactly the mention.
+    expect(body.slice(start, body.length)).toBe("@Sam Chen");
+  });
+
+  it("rejects a negative offset", () => {
+    expect(
+      CommentMentionSchema.safeParse(makeMention({ startOffset: -1 })).success,
+    ).toBe(false);
+  });
+
+  it("rejects a fractional offset", () => {
+    // A code-unit index is an integer by construction; a fraction means someone
+    // measured in something else.
+    expect(
+      CommentMentionSchema.safeParse(makeMention({ endOffset: 2.5 })).success,
+    ).toBe(false);
+  });
+});
+
+describe("CommentThreadSchema", () => {
+  it("parses a well-formed thread with its comments", () => {
+    expect(CommentThreadSchema.safeParse(makeThread()).success).toBe(true);
+  });
+
+  it("parses a document-anchored thread", () => {
+    expect(
+      CommentThreadSchema.safeParse(
+        makeThread({
+          anchorType: "document",
+          anchor: { type: "document", v: 1 },
+        }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("rejects a thread whose anchor is invalid", () => {
+    // The thread is the only place an anchor reaches a client, so a thread must
+    // not parse around a broken one — that would hand the app an anchor it
+    // cannot resolve while telling it the response was fine.
+    expect(
+      CommentThreadSchema.safeParse(
+        makeThread({ anchor: { type: "text", v: 1, prefix: "", suffix: "" } }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("keeps tombstones in the comment list rather than filtering them", () => {
+    const thread = CommentThreadSchema.parse(
+      makeThread({
+        comments: [
+          makeComment({
+            id: "55555555-5555-4555-8555-555555555555",
+            body: null,
+            deletedAt: "2026-08-02T09:00:00.000Z",
+          }),
+          makeComment(),
+        ],
+      }),
+    );
+    expect(thread.comments).toHaveLength(2);
+    expect(thread.comments[0].body).toBeNull();
+  });
+});
+
+describe("CommentThreadListResponseSchema", () => {
+  it("parses an empty subject", () => {
+    expect(
+      CommentThreadListResponseSchema.safeParse({ threads: [] }).success,
+    ).toBe(true);
+  });
+
+  it("parses a subject with threads", () => {
+    expect(
+      CommentThreadListResponseSchema.safeParse({ threads: [makeThread()] })
+        .success,
+    ).toBe(true);
+  });
+});
+
+describe("MentionableResponseSchema", () => {
+  it("parses a candidate list", () => {
+    expect(
+      MentionableResponseSchema.safeParse({
+        items: [{ userId: USER_ID, displayName: "Sam Chen", avatarUrl: null }],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("carries no access level — a picker is not an access-inspection surface", () => {
+    // The candidates ARE the document's readers. Returning the band each one
+    // holds would turn an autocomplete into a way to enumerate who can do what,
+    // so the field must stay absent from the shape rather than merely unset.
+    expect(
+      Object.keys(MentionableResponseSchema.shape.items.element.shape).sort(),
+    ).toEqual(["avatarUrl", "displayName", "userId"]);
+  });
+});

package/src/comments/anchor.ts

@@ -0,0 +1,120 @@
+/**
+ * The comment anchor — where on a subject a thread hangs (ADR-CONTRACTS-116).
+ *
+ * THE ANCHOR IS THE CONTRACT BETWEEN THE CLIENT THAT WRITES IT AND THE CLIENT
+ * THAT LATER RESOLVES IT. The backend is a PASSTHROUGH: it validates this shape
+ * at the route boundary, stores the result as opaque jsonb, and interprets
+ * nothing (backend ADR slug polymorphic-comment-threads §4). So a disagreement
+ * between the writing client and the resolving client about what these fields
+ * MEAN produces silently mis-placed comments with no server-side tripwire — the
+ * write succeeds, the read succeeds, and the highlight lands on the wrong text.
+ * That is why the shape is published here rather than declared app-locally.
+ *
+ * `v` is the evolution hatch and the only thing that bounds the risk above: a
+ * client that meets an anchor it cannot resolve sees an unfamiliar `v` and can
+ * degrade deliberately, instead of guessing at fields it half-recognises. New
+ * anchor shapes therefore arrive as new `v` variants, never as a migration of an
+ * existing one.
+ *
+ * Zod-canonical: the schema is the source of truth, the type is inferred.
+ *
+ * MIRRORED, NOT INVENTED. Every bound below is the backend route boundary's
+ * (`src/api/http/routes/comments/comments.schemas.ts`), and the accept/reject
+ * corpus at `./__tests__/fixtures/comment-anchors.json` is copied byte-for-byte
+ * from that suite's fixtures. Editing that copy HERE fails the anchor suite —
+ * its digest is pinned beside it. A change made at the BOUNDARY is not caught
+ * from this repo; a single-repo CI run cannot see that file, and this package
+ * must not depend on the backend to look. ADR-CONTRACTS-116 records which half
+ * is gated and where the missing gate belongs.
+ */
+import { z } from "zod";
+
+/**
+ * A base64 `Y.RelativePosition` payload, encoded by the client.
+ *
+ * Bounded so an anchor can never smuggle document-scale content through a field
+ * nothing on the server reads. The backend never decodes it — the bound and the
+ * charset are the only things anyone checks, so they have to be checked here
+ * too or a client can write a position no other client can decode.
+ */
+const RelativePositionSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .regex(/^[A-Za-z0-9+/]+={0,2}$/, "must be base64");
+
+/**
+ * The thread hangs off the subject AS A WHOLE — a comment on the document, not
+ * on a passage in it.
+ *
+ * Strict: a document anchor carrying `quote`/`prefix`/`relStart` is refused
+ * rather than silently accepted with the extra fields ignored. A client that
+ * sends those meant to anchor to text and got the discriminator wrong; storing
+ * the mistake would produce a thread that can never be placed.
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00922, must_log).
+ * The reference block writes this variant as
+ * `z.object({ type: z.literal('document'), v: z.literal(1) }).strict()`.
+ * What ships below is the same schema in two different spellings, not a
+ * different schema: `z.strictObject` is zod v4's idiom for `z.object().strict()`,
+ * and the double quotes are this repo's Prettier default (there is no
+ * `.prettierrc`, so `singleQuote` is false and `pnpm format:check` rewrites any
+ * single-quoted string here). Recorded because the reference is marked
+ * authoritative, and a reader diffing the two should be able to tell at a glance
+ * that nothing about what is accepted or refused changed.
+ */
+const DocumentAnchorSchema = z.strictObject({
+  type: z.literal("document"),
+  v: z.literal(1),
+});
+
+/**
+ * A text-anchored thread.
+ *
+ * `quote` is REQUIRED and is the durable fallback — it is what a resolving
+ * client re-finds the passage by when the relative positions no longer resolve,
+ * and it is also the composer's `Comment on "…"` label. An anchor with no quote
+ * is unplaceable the first time the document is edited, so it is refused.
+ *
+ * `relStart`/`relEnd` are OPTIONAL by design: a comment authored from a card or
+ * a list view has no attached collab session to encode a position from, and has
+ * only the quote path. Optional here means "this client could not produce one",
+ * never "this client chose not to".
+ *
+ * `prefix`/`suffix` disambiguate a quote that appears more than once. They are
+ * required-but-may-be-empty rather than optional, so "there is no surrounding
+ * context" and "this client forgot to send it" stay distinguishable.
+ */
+const TextAnchorSchema = z.strictObject({
+  type: z.literal("text"),
+  v: z.literal(1),
+  relStart: RelativePositionSchema.optional(),
+  relEnd: RelativePositionSchema.optional(),
+  quote: z.string().min(1).max(2000),
+  prefix: z.string().max(64),
+  suffix: z.string().max(64),
+});
+
+/**
+ * The anchor types, as a vocabulary tuple.
+ *
+ * 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 CommentAnchorTypeSchema = z.enum(COMMENT_ANCHOR_TYPES);
+export type CommentAnchorType = z.infer<typeof CommentAnchorTypeSchema>;
+
+/**
+ * The opaque, versioned anchor payload.
+ *
+ * Discriminated on `type` with STRICT variants, which is what makes the two
+ * failure modes above real refusals rather than silent coercions.
+ */
+export const CommentAnchorSchema = z.discriminatedUnion("type", [
+  DocumentAnchorSchema,
+  TextAnchorSchema,
+]);
+export type CommentAnchor = z.infer<typeof CommentAnchorSchema>;

package/src/comments/index.ts

@@ -0,0 +1,43 @@
+/**
+ * comments/ — the published wire contract for comment threads: the anchor
+ * union, the thread/comment/mention read projections, and the mention picker's
+ * response.
+ *
+ * See ./README.md for the domain, and ADR-CONTRACTS-116 for why each of these
+ * meets the promotion rule — and for what is deliberately NOT here (request
+ * bodies, per ADR-CONT-029).
+ */
+
+export {
+  COMMENT_ANCHOR_TYPES,
+  CommentAnchorTypeSchema,
+  CommentAnchorSchema,
+} from "./anchor";
+
+export type { CommentAnchor, CommentAnchorType } from "./anchor";
+
+export {
+  COMMENT_SUBJECT_TYPES,
+  COMMENT_THREAD_STATUSES,
+  CommentMentionSchema,
+  CommentSchema,
+  CommentSubjectTypeSchema,
+  CommentThreadListResponseSchema,
+  CommentThreadSchema,
+  CommentThreadStatusSchema,
+  CommentThreadSummarySchema,
+  MentionableCandidateSchema,
+  MentionableResponseSchema,
+} from "./schemas";
+
+export type {
+  CommentMention,
+  CommentProjection,
+  CommentSubjectType,
+  CommentThread,
+  CommentThreadListResponse,
+  CommentThreadStatus,
+  CommentThreadSummary,
+  MentionableCandidate,
+  MentionableResponse,
+} from "./schemas";