@company-semantics/contracts 45.1.0 → 45.3.0

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";

package/src/comments/schemas.ts

@@ -0,0 +1,227 @@
+/**
+ * The published read shapes of the comment surface (ADR-CONTRACTS-116).
+ *
+ * RESPONSE VOCABULARY ONLY. Request bodies stay backend-side per ADR-CONT-029 —
+ * a create/edit body is a transport concern, and one of them (the mention set)
+ * is the exact thing a client must not be able to influence: the server derives
+ * who may be mentioned from `effective_acl_grants` and never from what the
+ * client sends.
+ *
+ * Zod-canonical: the schema is the source of truth, the type is inferred.
+ *
+ * MIRRORED, NOT INVENTED. Every field below matches the backend route
+ * boundary's response schemas (`src/api/http/routes/comments/comments.schemas.ts`
+ * and `.../company-md/mentionable.schemas.ts`) field-for-field, and therefore
+ * matches the already-generated `components["schemas"]` view in `../api`. Two
+ * descriptions of one wire shape that disagree is worse than one, so where the
+ * backend is looser than looks right — `userId` is `z.string()` and not a uuid,
+ * mention offsets are nullable — this mirrors the backend and says why.
+ */
+import { z } from "zod";
+import { CommentAnchorSchema, CommentAnchorTypeSchema } from "./anchor";
+
+// =============================================================================
+// Vocabulary
+// =============================================================================
+
+/**
+ * A thread is open or resolved. There is no third state and deliberately no
+ * `deleted`: a thread whose comments are all soft-deleted is still a resolvable
+ * thread, and its tombstones keep their place (see `CommentSchema`).
+ */
+export const COMMENT_THREAD_STATUSES = ["open", "resolved"] as const;
+export const CommentThreadStatusSchema = z.enum(COMMENT_THREAD_STATUSES);
+export type CommentThreadStatus = z.infer<typeof CommentThreadStatusSchema>;
+
+/**
+ * What a thread can hang off.
+ *
+ * A CLOSED enum rather than a free string, sized to the ACL entity types that
+ * actually admit comments today. The transport accepts this vocabulary and the
+ * backend's fail-closed subject-policy map decides ADMISSION separately, so a
+ * subject type present here is addressable, not necessarily commentable — which
+ * is why a client must still handle the 404 rather than infer permission from
+ * membership in this list.
+ */
+export const COMMENT_SUBJECT_TYPES = [
+  "company_md",
+  "strategy_doc",
+  "work_item",
+  "meeting_recording",
+] as const;
+export const CommentSubjectTypeSchema = z.enum(COMMENT_SUBJECT_TYPES);
+export type CommentSubjectType = z.infer<typeof CommentSubjectTypeSchema>;
+
+// =============================================================================
+// Mentions
+// =============================================================================
+
+/**
+ * ONE mention on a comment, as the app renders it.
+ *
+ * OFFSETS ARE ZERO-BASED UTF-16 CODE UNITS INTO THE EXACT COMMENT BODY STRING,
+ * WITH `endOffset` EXCLUSIVE — i.e. plain JavaScript string coordinates, the
+ * same ones a `textarea`'s `selectionStart` and CodeMirror report. That is the
+ * whole convention and it is load-bearing in two directions: an emoji or any
+ * other astral character counts as TWO units, not one, so a client that
+ * measures in code POINTS (`[...body].length`, `Intl.Segmenter`) will produce
+ * ranges that slide off the mention by one per preceding emoji. And NO UNICODE
+ * NORMALIZATION happens anywhere on this path (backend ADR slug
+ * comment-mention-identity) — normalising the body before measuring would
+ * change its length and desynchronise every offset after the first composed
+ * character.
+ *
+ * IDENTITY RENDERS FROM THIS ROW, NEVER FROM THE BODY CHARACTERS UNDER THE
+ * RANGE. A stale or forged range can therefore only mis-HIGHLIGHT; it can never
+ * misattribute a mention to the wrong person.
+ *
+ * `startOffset`/`endOffset` are NULLABLE, and null on every row today:
+ * `comment_mentions` has no offset columns yet, so the ranges the server
+ * validates in memory have nowhere to persist. The fields are carried in the
+ * TARGET shape so a client is written against the final contract once — treat
+ * null as "this mention is in the body somewhere, highlight nothing", not as an
+ * error.
+ *
+ * `displayName` is resolved AT READ TIME from the current user record and is
+ * never stored on the mention row: a rename re-renders with no backfill, and an
+ * identity the reader can no longer resolve arrives as a neutral placeholder
+ * rather than failing the whole thread load.
+ *
+ * `userId` is `z.string()` and not `.uuid()` on purpose — it mirrors the
+ * backend boundary exactly. Tightening it here would make this package reject
+ * responses the server considers valid, which is a client-side outage for no
+ * security gain.
+ */
+export const CommentMentionSchema = z.object({
+  userId: z.string(),
+  startOffset: z.number().int().min(0).nullable(),
+  endOffset: z.number().int().min(0).nullable(),
+  displayName: z.string(),
+});
+export type CommentMention = z.infer<typeof CommentMentionSchema>;
+
+// =============================================================================
+// Comments
+// =============================================================================
+
+/**
+ * One comment as the app renders it.
+ *
+ * THE REDACTION INVARIANT: `body` is null EXACTLY WHEN `deletedAt` is set, and a
+ * soft-deleted comment also arrives with `mentions` empty. A deleted comment is
+ * a REDACTED PROJECTION, not a removed row — the tombstone keeps its position in
+ * the (createdAt ASC, id ASC) sequence, so replies above and below it still read
+ * in order, and a thread whose comments were all deleted stays distinguishable
+ * from a thread that never had any.
+ *
+ * The invariant is DOCUMENTED here and enforced by the writer, not by a Zod
+ * refinement. A refinement would make this package refuse a response the server
+ * is willing to emit, and it cannot be expressed in the OpenAPI surface either —
+ * so it would be a third description of the wire shape that the parity guards
+ * cannot check. `./__tests__/schemas.test.ts` pins that the redacted projection
+ * parses.
+ *
+ * `authorUserId` is nullable for the same tombstoning reason: an author whose
+ * user record is gone leaves the comment readable and unattributed.
+ *
+ * The inferred type is `CommentProjection`, not `Comment`, for the reason
+ * `NotificationElement` is not `Element` (`../notifications/content`): `Comment`
+ * is a DOM global, and a bare `Comment` on the root barrel takes it away from
+ * any consumer file that imports it. `CommentProjection` is also the truer name
+ * — the redaction rule above is what makes this a projection rather than a row.
+ */
+export const CommentSchema = z.object({
+  id: z.string(),
+  threadId: z.string(),
+  authorUserId: z.string().nullable(),
+  body: z.string().nullable(),
+  editedAt: z.string().nullable(),
+  deletedAt: z.string().nullable(),
+  createdAt: z.string(),
+  mentions: z.array(CommentMentionSchema),
+});
+export type CommentProjection = z.infer<typeof CommentSchema>;
+
+// =============================================================================
+// Threads
+// =============================================================================
+
+/**
+ * A thread WITHOUT its comments — the shape a resolve/reopen transition returns.
+ *
+ * `anchorType` is the anchor's discriminant, denormalised out of the jsonb by
+ * the server. It is redundant with `anchor.type` and that is the point: a client
+ * can bucket threads into document-level and text-level without parsing every
+ * anchor, and the two are written together so they cannot disagree.
+ */
+export const CommentThreadSummarySchema = z.object({
+  id: z.string(),
+  subjectType: CommentSubjectTypeSchema,
+  subjectId: z.string(),
+  anchorType: CommentAnchorTypeSchema,
+  anchor: CommentAnchorSchema,
+  status: CommentThreadStatusSchema,
+  createdByUserId: z.string().nullable(),
+  resolvedByUserId: z.string().nullable(),
+  resolvedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type CommentThreadSummary = z.infer<typeof CommentThreadSummarySchema>;
+
+/**
+ * A thread with ALL its comments, oldest-first by (createdAt ASC, id ASC).
+ *
+ * Soft-deleted comments appear REDACTED, never filtered out — filtering them
+ * would renumber the conversation under the reader and make "…replying to the
+ * comment above" false.
+ */
+export const CommentThreadSchema = CommentThreadSummarySchema.extend({
+  comments: z.array(CommentSchema),
+});
+export type CommentThread = z.infer<typeof CommentThreadSchema>;
+
+/** `GET /api/comments` — every thread on the subject the caller may see. */
+export const CommentThreadListResponseSchema = z.object({
+  threads: z.array(CommentThreadSchema),
+});
+export type CommentThreadListResponse = z.infer<
+  typeof CommentThreadListResponseSchema
+>;
+
+// =============================================================================
+// The mention picker
+// =============================================================================
+
+/**
+ * One offerable mention target.
+ *
+ * Deliberately NO email and no access level: this is a picker, not an
+ * access-inspection surface, and the candidate set is already the document's
+ * readers — so returning the band each one holds would turn an autocomplete into
+ * a way to enumerate who can do what.
+ *
+ * `userId` is what the mention row will carry; `displayName` is resolved fresh
+ * on every read and never frozen into a stored row, exactly as on
+ * `CommentMentionSchema`.
+ */
+export const MentionableCandidateSchema = z.object({
+  userId: z.string(),
+  displayName: z.string(),
+  avatarUrl: z.string().nullable(),
+});
+export type MentionableCandidate = z.infer<typeof MentionableCandidateSchema>;
+
+/**
+ * `GET /api/company-md/docs/{id}/mentionable`.
+ *
+ * THE CANDIDATES ARE THE DOCUMENT'S READERS, derived server-side from
+ * `effective_acl_grants` — so the picker and the set of people a mention can
+ * actually notify agree by construction, and a client cannot widen it. Ordering
+ * is `(displayName ASC, userId ASC)`; the id tie-break is what makes the page
+ * deterministic when two members share a display name.
+ */
+export const MentionableResponseSchema = z.object({
+  items: z.array(MentionableCandidateSchema),
+});
+export type MentionableResponse = z.infer<typeof MentionableResponseSchema>;

package/src/generated/openapi-routes.ts

@@ -21,6 +21,12 @@ export const openApiRoutes = {
   '/api/chats/{id}/messages': ['POST'],
   '/api/chats/{id}/messages/{messageId}': ['DELETE'],
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
+  '/api/comments': ['GET'],
+  '/api/comments/threads': ['POST'],
+  '/api/comments/threads/{threadId}/comments': ['POST'],
+  '/api/comments/threads/{threadId}/reopen': ['POST'],
+  '/api/comments/threads/{threadId}/resolve': ['POST'],
+  '/api/comments/{commentId}': ['DELETE', 'PATCH'],
   '/api/company-md/access-requests/{id}/approve': ['POST'],
   '/api/company-md/access-requests/{id}/deny': ['POST'],
   '/api/company-md/context-bank': ['POST'],
@@ -40,6 +46,7 @@ export const openApiRoutes = {
   '/api/company-md/docs/{id}/context-bank/upload': ['POST'],
   '/api/company-md/docs/{id}/context-bank/{contextDocId}': ['DELETE'],
   '/api/company-md/docs/{id}/context-bank/{contextDocId}/order': ['PATCH'],
+  '/api/company-md/docs/{id}/mentionable': ['GET'],
   '/api/company-md/docs/{id}/sharing': ['GET'],
   '/api/company-md/docs/{id}/sharing/acl': ['POST'],
   '/api/company-md/docs/{id}/sharing/acl/{aclId}': ['DELETE', 'PUT'],