@actuate-media/cms-core 0.21.0 → 0.22.0

package/dist/realtime/notifications.js

@@ -0,0 +1,209 @@
+/**
+ * Per-user notifications driven by collaboration events.
+ *
+ * Owns the pure notification logic: kind discriminator, payload validation,
+ * permission gates, and a storage-agnostic CRUD surface. The HTTP layer
+ * (in `api/handlers.ts`) is a thin wrapper that handles auth + JSON
+ * envelope; the comments hook layer (slice 6, `notification-triggers.ts`)
+ * calls these helpers when a comment lifecycle event fires.
+ *
+ * Storage shape — see `packages/cms-core/prisma/cms-schema.prisma`, model
+ * `DocumentNotification`. We require only a minimal Prisma surface so the
+ * helpers can be tested against an in-memory fake.
+ *
+ * ## Discriminated payloads
+ *
+ * The `payload` Json column varies by `kind`. The TypeScript types here
+ * are the source of truth for each variant; the service helpers narrow
+ * by `kind` so callers can't accidentally insert a malformed payload.
+ *
+ * ## Mentions
+ *
+ * Slice 6 ships a deliberately simple mention parser: `@<userId>` tokens
+ * in a comment body trigger a `comment_mention` notification. A richer
+ * `@username` parser that resolves against the user table is a Phase 4
+ * follow-up — the storage shape already supports it.
+ */
+/** Hard cap on returned notifications per `listForUser` call. */
+export const MAX_NOTIFICATION_LIST_PAGE_SIZE = 200;
+/** Default page size when the caller does not request one. */
+export const DEFAULT_NOTIFICATION_LIST_PAGE_SIZE = 50;
+export function toNotificationDTO(row) {
+    // The payload comes back as `unknown` from Prisma's Json column; we
+    // re-tag it with the `kind` discriminator so the DTO is strictly typed
+    // on the way out. Storage-level validation in `createNotification`
+    // guarantees the payload matches the kind.
+    const payload = {
+        kind: row.kind,
+        ...(row.payload ?? {}),
+    };
+    return {
+        id: row.id,
+        userId: row.userId,
+        kind: row.kind,
+        documentId: row.documentId,
+        commentId: row.commentId,
+        payload,
+        readAt: row.readAt ? row.readAt.toISOString() : null,
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+const KIND_GUARDS = {
+    comment_reply: true,
+    comment_resolved: true,
+    comment_mention: true,
+};
+export function isNotificationKind(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(KIND_GUARDS, value);
+}
+function validatePayload(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return { code: 'validation', message: 'payload must be an object' };
+    }
+    if (!isNotificationKind(payload.kind)) {
+        return { code: 'validation', message: `unknown kind "${String(payload.kind)}"` };
+    }
+    if (payload.kind === 'comment_reply' || payload.kind === 'comment_mention') {
+        if (typeof payload.excerpt !== 'string') {
+            return { code: 'validation', message: 'excerpt is required' };
+        }
+    }
+    if (payload.kind === 'comment_resolved') {
+        if (typeof payload.rootExcerpt !== 'string') {
+            return { code: 'validation', message: 'rootExcerpt is required' };
+        }
+    }
+    return null;
+}
+/**
+ * Insert a new notification. The payload's `kind` field is the source
+ * of truth; `kind` on the DB row is derived from it so callers can't
+ * drift them apart.
+ */
+export async function createNotification(db, input) {
+    if (!input.userId || typeof input.userId !== 'string') {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const validationError = validatePayload(input.payload);
+    if (validationError)
+        return { ok: false, error: validationError };
+    // Strip the kind tag from the stored JSON — it's already in the
+    // dedicated column.
+    const { kind, ...rest } = input.payload;
+    const row = await db.documentNotification.create({
+        data: {
+            userId: input.userId,
+            kind,
+            documentId: input.documentId ?? null,
+            commentId: input.commentId ?? null,
+            payload: rest,
+            readAt: null,
+        },
+    });
+    return { ok: true, value: toNotificationDTO(row) };
+}
+/** Resolve a notification by id, only if it belongs to `userId`. */
+async function loadOwned(db, id, userId) {
+    const row = await db.documentNotification.findUnique({ where: { id } });
+    if (!row)
+        return { ok: false, error: { code: 'not_found', message: 'Notification not found' } };
+    if (row.userId !== userId) {
+        return { ok: false, error: { code: 'forbidden', message: 'Not your notification' } };
+    }
+    return { ok: true, value: row };
+}
+/**
+ * List notifications for a user, newest first. By default returns only
+ * unread; pass `includeRead: true` for the full feed (the bell dropdown
+ * uses both depending on the tab the user is on).
+ */
+export async function listForUser(db, filter) {
+    if (!filter.userId) {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const take = clampPageSize(filter.pageSize);
+    const where = { userId: filter.userId };
+    if (!filter.includeRead)
+        where.readAt = null;
+    const rows = await db.documentNotification.findMany({
+        where,
+        orderBy: { createdAt: 'desc' },
+        take,
+    });
+    return { ok: true, value: rows.map(toNotificationDTO) };
+}
+/** Count unread notifications for the bell badge. */
+export async function unreadCount(db, userId) {
+    if (!userId) {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const count = await db.documentNotification.count({
+        where: { userId, readAt: null },
+    });
+    return { ok: true, value: count };
+}
+/** Mark a single notification read (idempotent). */
+export async function markRead(db, id, actor) {
+    if (!id) {
+        return { ok: false, error: { code: 'validation', message: 'id is required' } };
+    }
+    const loaded = await loadOwned(db, id, actor.userId);
+    if (!loaded.ok)
+        return loaded;
+    if (loaded.value.readAt) {
+        return { ok: true, value: toNotificationDTO(loaded.value) };
+    }
+    const updated = await db.documentNotification.update({
+        where: { id },
+        data: { readAt: new Date() },
+    });
+    return { ok: true, value: toNotificationDTO(updated) };
+}
+/** Mark every unread notification for the user as read. */
+export async function markAllRead(db, userId) {
+    if (!userId) {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const out = await db.documentNotification.updateMany({
+        where: { userId, readAt: null },
+        data: { readAt: new Date() },
+    });
+    return { ok: true, value: { count: out.count } };
+}
+function clampPageSize(requested) {
+    if (typeof requested !== 'number' || !Number.isFinite(requested) || requested <= 0) {
+        return DEFAULT_NOTIFICATION_LIST_PAGE_SIZE;
+    }
+    return Math.min(Math.max(1, Math.floor(requested)), MAX_NOTIFICATION_LIST_PAGE_SIZE);
+}
+/**
+ * Cheap excerpt builder for notification payloads. Markdown is kept as-is;
+ * we just trim whitespace and clip to 120 chars so the bell can render
+ * a single-line preview.
+ */
+export function excerptForNotification(body, max = 120) {
+    const cleaned = body.replace(/\s+/g, ' ').trim();
+    if (cleaned.length <= max)
+        return cleaned;
+    return `${cleaned.slice(0, max - 1)}…`;
+}
+/**
+ * Extract `@<userId>` mentions from a comment body. We intentionally
+ * match the *user id* form here (`@user_abc123`) — a slice-7 follow-up
+ * can wire up `@username` resolution against the User table.
+ *
+ * Returns a deduplicated array of mentioned user ids; the caller filters
+ * out the actor before issuing notifications.
+ */
+export function extractMentionedUserIds(body) {
+    if (typeof body !== 'string' || body.length === 0)
+        return [];
+    const seen = new Set();
+    const re = /@([a-zA-Z0-9_-]{3,64})\b/g;
+    let match;
+    while ((match = re.exec(body)) !== null) {
+        seen.add(match[1]);
+    }
+    return Array.from(seen);
+}
+//# sourceMappingURL=notifications.js.map

package/dist/realtime/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/realtime/notifications.ts"],"names":[],"mappings":"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"}

package/dist/realtime/persistence.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Prisma-backed `DocumentPersistence` for `@actuate-media/realtime`.
+ *
+ * Reads and writes the `DocumentCRDT` table (see
+ * `prisma/cms-schema.prisma`). The adapter is intentionally narrow — it only
+ * implements the two methods declared by the realtime package, so it can be
+ * swapped for an S3 / Redis / Postgres-LO adapter without touching the
+ * gateway code.
+ *
+ * The `save` path also keeps the `stateVector` column in sync so future
+ * versions of the gateway can answer `SyncStep1` without ever booting a
+ * `Y.Doc` (a future optimisation for hot-path late joins).
+ */
+import type { DocumentPersistence } from '@actuate-media/realtime';
+/** Minimal subset of the Prisma client the persistence adapter needs. */
+export interface PrismaDocumentCRDTClient {
+    documentCRDT: {
+        findUnique(args: {
+            where: {
+                documentId: string;
+            };
+            select?: {
+                state?: boolean;
+                stateVector?: boolean;
+                version?: boolean;
+            };
+        }): Promise<{
+            state: Uint8Array;
+            stateVector?: Uint8Array;
+            version?: number;
+        } | null>;
+        upsert(args: {
+            where: {
+                documentId: string;
+            };
+            create: {
+                documentId: string;
+                state: Uint8Array;
+                stateVector: Uint8Array;
+                version: number;
+                lastUpdatedById?: string | null;
+            };
+            update: {
+                state: Uint8Array;
+                stateVector: Uint8Array;
+                version: {
+                    increment: number;
+                };
+                lastUpdatedById?: string | null;
+            };
+        }): Promise<{
+            documentId: string;
+            version: number;
+        }>;
+    };
+}
+export interface PrismaDocumentPersistenceOptions {
+    /**
+     * Optional default editor id used for `lastUpdatedById` when the gateway
+     * does not supply one. In production the gateway derives this from the
+     * authenticated session per save.
+     */
+    lastUpdatedById?: string | null;
+}
+/**
+ * Create a `DocumentPersistence` backed by a `DocumentCRDT` Prisma table.
+ *
+ * The returned object satisfies the realtime package's contract so it can
+ * be passed straight to `bindPersistence(room, persistence)`.
+ */
+export declare function createPrismaDocumentPersistence(db: PrismaDocumentCRDTClient, options?: PrismaDocumentPersistenceOptions): DocumentPersistence;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/realtime/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/realtime/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAGlE,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE;QACZ,UAAU,CAAC,IAAI,EAAE;YACf,KAAK,EAAE;gBAAE,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;YAC7B,MAAM,CAAC,EAAE;gBAAE,KAAK,CAAC,EAAE,OAAO,CAAC;gBAAC,WAAW,CAAC,EAAE,OAAO,CAAC;gBAAC,OAAO,CAAC,EAAE,OAAO,CAAA;aAAE,CAAA;SACvE,GAAG,OAAO,CAAC;YAAE,KAAK,EAAE,UAAU,CAAC;YAAC,WAAW,CAAC,EAAE,UAAU,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC,CAAA;QACrF,MAAM,CAAC,IAAI,EAAE;YACX,KAAK,EAAE;gBAAE,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;YAC7B,MAAM,EAAE;gBACN,UAAU,EAAE,MAAM,CAAA;gBAClB,KAAK,EAAE,UAAU,CAAA;gBACjB,WAAW,EAAE,UAAU,CAAA;gBACvB,OAAO,EAAE,MAAM,CAAA;gBACf,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;aAChC,CAAA;YACD,MAAM,EAAE;gBACN,KAAK,EAAE,UAAU,CAAA;gBACjB,WAAW,EAAE,UAAU,CAAA;gBACvB,OAAO,EAAE;oBAAE,SAAS,EAAE,MAAM,CAAA;iBAAE,CAAA;gBAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;aAChC,CAAA;SACF,GAAG,OAAO,CAAC;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACrD,CAAA;CACF;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,wBAAwB,EAC5B,OAAO,GAAE,gCAAqC,GAC7C,mBAAmB,CAwCrB"}

package/dist/realtime/persistence.js

@@ -0,0 +1,53 @@
+import * as Y from 'yjs';
+/**
+ * Create a `DocumentPersistence` backed by a `DocumentCRDT` Prisma table.
+ *
+ * The returned object satisfies the realtime package's contract so it can
+ * be passed straight to `bindPersistence(room, persistence)`.
+ */
+export function createPrismaDocumentPersistence(db, options = {}) {
+    return {
+        async load(documentId) {
+            const row = await db.documentCRDT.findUnique({
+                where: { documentId },
+                select: { state: true },
+            });
+            if (!row)
+                return null;
+            // Defensive copy: callers may mutate the buffer once we return it
+            // (Prisma typically gives back a fresh Uint8Array, but we don't want
+            // to rely on internal guarantees here).
+            return copyBytes(row.state);
+        },
+        async save(documentId, state) {
+            // Compute the new state vector from the encoded state. Cheap — Yjs
+            // decodes the update structure but skips construction of clients.
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, state);
+            const stateVector = Y.encodeStateVector(doc);
+            doc.destroy();
+            await db.documentCRDT.upsert({
+                where: { documentId },
+                create: {
+                    documentId,
+                    state: copyBytes(state),
+                    stateVector,
+                    version: 1,
+                    lastUpdatedById: options.lastUpdatedById ?? null,
+                },
+                update: {
+                    state: copyBytes(state),
+                    stateVector,
+                    version: { increment: 1 },
+                    lastUpdatedById: options.lastUpdatedById ?? null,
+                },
+            });
+        },
+    };
+}
+function copyBytes(src) {
+    const dst = new Uint8Array(src.length);
+    dst.set(src);
+    return dst;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/realtime/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/realtime/persistence.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAqCxB;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAC7C,EAA4B,EAC5B,UAA4C,EAAE;IAE9C,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,UAAU;YACnB,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC;gBAC3C,KAAK,EAAE,EAAE,UAAU,EAAE;gBACrB,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;aACxB,CAAC,CAAA;YACF,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAA;YACrB,kEAAkE;YAClE,qEAAqE;YACrE,wCAAwC;YACxC,OAAO,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC7B,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK;YAC1B,mEAAmE;YACnE,kEAAkE;YAClE,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAA;YACvB,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACzB,MAAM,WAAW,GAAG,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAA;YAC5C,GAAG,CAAC,OAAO,EAAE,CAAA;YAEb,MAAM,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC;gBAC3B,KAAK,EAAE,EAAE,UAAU,EAAE;gBACrB,MAAM,EAAE;oBACN,UAAU;oBACV,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC;oBACvB,WAAW;oBACX,OAAO,EAAE,CAAC;oBACV,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,IAAI;iBACjD;gBACD,MAAM,EAAE;oBACN,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC;oBACvB,WAAW;oBACX,OAAO,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE;oBACzB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,IAAI;iBACjD;aACF,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,SAAS,CAAC,GAAe;IAChC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACtC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACZ,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cms-core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/actuate-media/actuatecms.git",
@@ -59,6 +59,11 @@
       "import": "./dist/page-builder/index.js",
       "default": "./dist/page-builder/index.js"
     },
+    "./realtime": {
+      "types": "./dist/realtime/index.d.ts",
+      "import": "./dist/realtime/index.js",
+      "default": "./dist/realtime/index.js"
+    },
     "./generated/client": {
       "types": "./generated/client.d.ts",
       "import": "./generated/client.js",
@@ -74,18 +79,22 @@
     "graphql-yoga": "^5.19.0",
     "jose": "^6.0.0",
     "pg": "^8.20.0",
-    "sanitize-html": "^2.17.3",
+    "sanitize-html": "^2.17.4",
     "sharp": "^0.34.5",
-    "zod": "^3.23.0"
+    "yjs": "^13.6.0",
+    "zod": "^3.23.0",
+    "@actuate-media/realtime": "0.1.0"
   },
   "devDependencies": {
     "@types/sanitize-html": "^2.16.1",
     "@types/sharp": "^0.32.0",
+    "@types/ws": "^8.5.10",
     "dotenv": "^17.3.1",
     "prisma": "^7.8.0",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "ws": "^8.18.0"
   },
   "files": [
     "dist",

package/prisma/cms-schema.prisma

@@ -60,12 +60,14 @@ model User {
   updatedAt     DateTime  @updatedAt
 
   sessions          Session[]
-  documentsCreated  Document[] @relation("DocumentCreatedBy")
-  documentsUpdated  Document[] @relation("DocumentUpdatedBy")
-  documentsReviewed Document[] @relation("DocumentReviewer")
+  documentsCreated  Document[]             @relation("DocumentCreatedBy")
+  documentsUpdated  Document[]             @relation("DocumentUpdatedBy")
+  documentsReviewed Document[]             @relation("DocumentReviewer")
   versions          Version[]
-  mediaUploaded     Media[]    @relation("MediaUploadedBy")
+  mediaUploaded     Media[]                @relation("MediaUploadedBy")
   auditLogs         AuditLog[]
+  comments          DocumentComment[]
+  notifications     DocumentNotification[]
 
   @@index([role])
   @@index([isActive])
@@ -304,3 +306,132 @@ model SavedSection {
 
   @@index([category])
 }
+
+/// Persisted Yjs state for a document, used by `@actuate-media/realtime`.
+///
+/// Each row holds the encoded Yjs document (`Y.encodeStateAsUpdate`) plus a
+/// version vector so consumers can serve incremental sync to late joiners
+/// without replaying full history. There is at most one row per `documentId`;
+/// it is upserted on every persistence flush from a live collaboration room.
+///
+/// The model is *optional*: an Actuate deployment that does not use the
+/// realtime collaboration features can leave this table empty. Cms-core only
+/// touches it when the `/realtime/sync` endpoint is hit.
+model DocumentCRDT {
+  /// References `Document.id`. We don't declare a Prisma relation here so
+  /// the realtime stack stays decoupled from the `Document` schema; the
+  /// constraint is enforced at the application layer.
+  documentId    String   @id
+  /// Yjs `encodeStateAsUpdate` bytes. Use bytea on Postgres.
+  state         Bytes
+  /// Yjs `encodeStateVector` bytes — lets us reply to a `SyncStep1` without
+  /// decoding the full doc when persistence is hot but the room is cold.
+  stateVector   Bytes
+  /// Monotonic counter for optimistic locking (incremented on every save).
+  version       Int      @default(0)
+  /// Wall-clock of the most recent flush.
+  lastUpdatedAt DateTime @default(now()) @updatedAt
+  /// User id of the most recent editor, if known.
+  lastUpdatedById String?
+  createdAt     DateTime @default(now())
+
+  @@index([lastUpdatedAt])
+}
+
+/// Threaded inline comment anchored to a Yjs document range.
+///
+/// Comments survive concurrent edits because the `anchor` field stores Yjs
+/// *relative positions* (the binary blob you get from
+/// `Y.createRelativePositionFromTypeIndex` followed by
+/// `Y.encodeRelativePosition`) rather than absolute offsets. Slice 5 binds
+/// these back to live ranges in the TipTap document.
+///
+/// Threading is single-level: a top-level comment has `parentId == null`,
+/// replies set `parentId` to the root comment's id. Deletes cascade so a
+/// resolved or removed thread cleans up its replies.
+///
+/// The model is *optional*. Deployments that don't enable Phase 3 simply
+/// leave the table empty; the cms-core API stays serviceable without it.
+model DocumentComment {
+  id           String   @id @default(cuid())
+  /// References `Document.id`. Like `DocumentCRDT`, we keep the foreign
+  /// constraint at the application layer so the realtime stack stays
+  /// decoupled from the core `Document` schema.
+  documentId   String
+  /// `null` for top-level comments; the root comment's id for replies.
+  /// Replies cannot themselves be parents — slice 5 enforces this in the
+  /// API handler.
+  parentId     String?
+  parent       DocumentComment?  @relation("CommentThread", fields: [parentId], references: [id], onDelete: Cascade)
+  replies      DocumentComment[] @relation("CommentThread")
+  /// Author of the comment. We don't cascade on user deletion so an
+  /// orphaned comment is preserved with a null `userId`; the UI can then
+  /// render "deleted user" without losing thread history.
+  userId       String?
+  user         User?    @relation(fields: [userId], references: [id], onDelete: SetNull)
+  /// Markdown body (sanitized server-side before render).
+  body         String   @db.Text
+  /// Yjs relative-position JSON: `{ from: number[]; to: number[] }` where
+  /// each entry is the Base64-encoded `encodeRelativePosition` bytes.
+  /// Stored as JSON (not Bytes) so the API can return it without an
+  /// extra encoding hop. May be null for document-level (un-anchored)
+  /// comments.
+  anchor       Json?
+  /// When set, the thread is resolved. UI hides resolved threads by
+  /// default but they remain in the table for audit.
+  resolvedAt   DateTime?
+  /// User that resolved the thread, if any.
+  resolvedById String?
+  /// Soft delete for moderation; row is preserved so replies don't lose
+  /// their parent.
+  deletedAt    DateTime?
+  createdAt    DateTime @default(now())
+  updatedAt    DateTime @updatedAt
+
+  @@index([documentId])
+  @@index([documentId, resolvedAt])
+  @@index([parentId])
+  @@index([userId])
+  @@index([createdAt])
+}
+
+// ─── Notifications (slice 6 — Phase 3) ─────────────────────────────────────────
+//
+// Per-user notification feed driven by collaboration events. Slice 6 wires
+// the comment lifecycle (reply, resolve, mention) into this table so editors
+// see "someone replied to your thread" without polling the comments API.
+//
+// The model is intentionally generic — the `kind` discriminator + `payload`
+// JSON blob keeps the schema stable while future slices add new notification
+// types (e.g. publish workflow transitions, document share invites).
+
+model DocumentNotification {
+  id          String   @id @default(cuid())
+  /// Recipient. Cascade-deletes on user removal — we don't want orphan
+  /// notifications pointing at gone-users in the dropdown.
+  userId      String
+  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  /// Discriminator. Slice 6 ships:
+  ///   - "comment_reply"   — someone replied to a thread you authored
+  ///   - "comment_resolved" — your thread was resolved by another user
+  ///   - "comment_mention" — your @handle was mentioned in a comment body
+  /// Future slices can extend this without a migration.
+  kind        String
+  /// Optional document scope so the bell can group / link notifications.
+  documentId  String?
+  /// Optional comment scope (the comment that triggered the notification).
+  commentId   String?
+  /// `{ actorId, actorName, excerpt?, ... }`. Shape depends on `kind`;
+  /// the service module documents each variant.
+  payload     Json
+  /// `null` until the user marks the notification read. We keep read rows
+  /// in the table so the dropdown can show recent activity, but the bell
+  /// counts only `readAt = null` rows.
+  readAt      DateTime?
+  createdAt   DateTime @default(now())
+
+  @@index([userId, readAt])
+  @@index([userId, createdAt])
+  @@index([documentId])
+  @@index([commentId])
+}

package/prisma/schema.prisma

@@ -1,7 +1,21 @@
 generator client {
-  provider        = "prisma-client"
-  output          = "../generated"
-  previewFeatures = ["fullTextSearchPostgres"]
+  provider = "prisma-client"
+  output   = "../generated"
+  // `relationJoins` is the Preview-feature flag that makes
+  // `relationLoadStrategy: 'join'` a recognised argument on
+  // findUnique / findMany / findFirst. Without it the option is
+  // silently rejected as an "Unknown argument" by Prisma — which
+  // is how the optimisation in PR #132 (dashboard recent-docs +
+  // versions list + bench `doc_get`) went unnoticed in production:
+  // `safeFindMany` swallowed the rejection and returned `[]`, the
+  // versions endpoint returned 500, and the bench reported "100/100
+  // errors" with no attached cause. Phase 5.5 #5 surfaced the
+  // failure once the bench harness started recording the first
+  // error message.
+  //
+  // The feature has been Preview since Prisma 5.7 and is documented
+  // at https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries#relation-load-strategies
+  previewFeatures = ["fullTextSearchPostgres", "relationJoins"]
 }
 
 datasource db {