@company-semantics/contracts 45.2.0 → 45.3.0

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

@@ -46,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'],

package/src/index.ts

@@ -322,6 +322,48 @@ export type {
   UserNotificationKind,
 } from "./user-notifications/index";
 
+// Comment wire contract — where a thread hangs (the anchor union), what a
+// thread and its comments look like on the wire, and who a comment may name.
+// The anchor is the single most load-bearing shape in this package: the backend
+// validates it and then stores opaque jsonb it never interprets, so app/
+// contracts drift on it has NO server-side tripwire and mis-places comments
+// silently. Response vocabulary only — request bodies stay backend-side.
+// See src/comments/README.md.
+// @see ADR-CONTRACTS-116, ADR-CONT-029
+export {
+  COMMENT_ANCHOR_TYPES,
+  COMMENT_SUBJECT_TYPES,
+  COMMENT_THREAD_STATUSES,
+} from "./comments/index";
+
+export {
+  CommentAnchorSchema,
+  CommentAnchorTypeSchema,
+  CommentMentionSchema,
+  CommentSchema,
+  CommentSubjectTypeSchema,
+  CommentThreadListResponseSchema,
+  CommentThreadSchema,
+  CommentThreadStatusSchema,
+  CommentThreadSummarySchema,
+  MentionableCandidateSchema,
+  MentionableResponseSchema,
+} from "./comments/index";
+
+export type {
+  CommentAnchor,
+  CommentAnchorType,
+  CommentMention,
+  CommentProjection,
+  CommentSubjectType,
+  CommentThread,
+  CommentThreadListResponse,
+  CommentThreadStatus,
+  CommentThreadSummary,
+  MentionableCandidate,
+  MentionableResponse,
+} from "./comments/index";
+
 // Chat domain types
 // @see PRD-00142 for share chat design rationale
 export type {

package/src/notifications/__tests__/__snapshots__/registry.test.ts.snap

@@ -10,6 +10,10 @@ exports[`NOTIFICATION_DEFINITIONS > titles every kind 1`] = `
   "chat.shared · Long title": "A chat has been shared with you",
   "chat.shared · No preview": "A chat has been shared with you",
   "chat.shared · Short": "A chat has been shared with you",
+  "comment.mention · Document-level": "Jordan Lee mentioned you in a comment",
+  "comment.mention · Text-anchored": "Jordan Lee mentioned you in a comment",
+  "comment.reply · Document-level": "Alex Rivera replied in a thread you are part of",
+  "comment.reply · Text-anchored": "Alex Rivera replied in a thread you are part of",
   "companyMd.access_request_approved · Editor": "Your access request was approved",
   "companyMd.access_request_approved · Editor with message": "Your access request was approved",
   "companyMd.access_request_approved · Viewer": "Your access request was approved",