@actuate-media/cms-core 0.21.0 → 0.22.0

package/dist/api/handlers.js

@@ -11,7 +11,12 @@ import { optimizeImage, formatBytes } from '../media/optimize.js';
 import { generateToken as generateCsrfToken } from '../security/csrf.js';
 import { logEvent } from '../security/audit.js';
 import { applyFieldAccess } from '../security/access.js';
+import { ACTUATE_TAG_ROOT, actuateTag, cachedRead, publicReadCacheControl } from '../cache/http.js';
 import { createPreviewAdapter } from '../preview/index.js';
+import { createPreviewStreamResponse } from '../preview/sse-stream.js';
+import { notifyPreviewUpdate } from '../preview/event-bus.js';
+import { createComment as createCommentService, deleteComment as deleteCommentService, listComments as listCommentsService, reopenComment as reopenCommentService, resolveComment as resolveCommentService, updateComment as updateCommentService, } from '../realtime/comments.js';
+import { createNotification, excerptForNotification, extractMentionedUserIds, listForUser as listNotificationsForUser, markAllRead as markAllNotificationsRead, markRead as markNotificationRead, unreadCount as notificationsUnreadCount, } from '../realtime/notifications.js';
 import { schedulingCronHandler } from '../scheduling/index.js';
 import { isAuthorizedCronRequest, processCleanup, processSeoScan } from '../cron/index.js';
 import { verifyCaptcha, getCaptchaConfig } from '../security/captcha.js';
@@ -92,6 +97,29 @@ function json(data, status = 200) {
         headers: { ...SECURITY_HEADERS },
     });
 }
+/**
+ * Variant of `json()` that emits the Phase-5.5 public-read
+ * `Cache-Control` header when the active CMS config opts in.
+ *
+ * - Session-cookie requests always get `private, no-store`.
+ * - API-key / unauthenticated requests get
+ *   `public, s-maxage=N, stale-while-revalidate=M` when
+ *   `cache.publicReads.enabled` is true.
+ * - Otherwise no `Cache-Control` header is set (i.e. the response is
+ *   uncacheable downstream, matching the pre-5.5 behaviour).
+ *
+ * Use this for the public read endpoints (`/collections/:slug`,
+ * `/collections/:slug/:id`, `/globals/:slug`, `/resolve`). Mutating
+ * endpoints stay on the plain `json()` so the CDN never caches a write
+ * response by accident.
+ */
+function jsonWithCache(data, request, status = 200) {
+    const cacheControl = publicReadCacheControl(request, getActuateConfig()?.cache);
+    const headers = { ...SECURITY_HEADERS };
+    if (cacheControl)
+        headers['Cache-Control'] = cacheControl;
+    return new Response(JSON.stringify(data), { status, headers });
+}
 function errorResponse(message, status) {
     return json({ error: message }, status);
 }
@@ -286,43 +314,73 @@ function renderOgSvg(opts) {
   <rect x="60" y="560" width="60" height="6" fill="${fg}" rx="3"/>
 </svg>`;
 }
+/**
+ * Log unexpected query failures from the `safe*` wrappers.
+ *
+ * The wrappers exist so an optional Prisma model (e.g. a delegate
+ * that older schemas don't define) doesn't blow up the route — they
+ * return the empty value (`0` / `[]`) when the model isn't available.
+ * That defensive contract historically swallowed *every* error,
+ * including Prisma's "Unknown argument" rejections that flag a real
+ * application bug (see the `relationLoadStrategy` regression
+ * discovered while landing Phase 5.5 #5). Logging the underlying
+ * error preserves the defensive return semantics while making the
+ * actual class of bug visible in Vercel + Sentry logs.
+ *
+ * Kept private to this module — it's a logging contract, not a
+ * public API.
+ */
+function logSafeQueryFailure(scope, err) {
+    // Defensive: never throw from a logger that wraps `safe*` queries
+    // — the whole point of those wrappers is to keep the request hot
+    // path alive.
+    try {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[actuate][cms-api] ${scope} query failed: ${message}`);
+    }
+    catch {
+        /* swallow */
+    }
+}
 async function safeCount(model, where) {
+    if (!model || typeof model !== 'object')
+        return 0;
+    let countFn;
     try {
-        if (!model || typeof model !== 'object')
-            return 0;
-        let countFn;
-        try {
-            countFn = model.count;
-        }
-        catch {
-            return 0;
-        }
-        if (typeof countFn !== 'function')
-            return 0;
-        return await countFn.call(model, where ? { where } : undefined);
+        countFn = model.count;
     }
     catch {
         return 0;
     }
+    if (typeof countFn !== 'function')
+        return 0;
+    try {
+        return await countFn.call(model, where ? { where } : undefined);
+    }
+    catch (err) {
+        logSafeQueryFailure('safeCount', err);
+        return 0;
+    }
 }
 async function safeFindMany(model, args) {
+    if (!model || typeof model !== 'object')
+        return [];
+    let findManyFn;
     try {
-        if (!model || typeof model !== 'object')
-            return [];
-        let findManyFn;
-        try {
-            findManyFn = model.findMany;
-        }
-        catch {
-            return [];
-        }
-        if (typeof findManyFn !== 'function')
-            return [];
-        return await findManyFn.call(model, args);
+        findManyFn = model.findMany;
     }
     catch {
         return [];
     }
+    if (typeof findManyFn !== 'function')
+        return [];
+    try {
+        return await findManyFn.call(model, args);
+    }
+    catch (err) {
+        logSafeQueryFailure('safeFindMany', err);
+        return [];
+    }
 }
 function isAllowedStorageUrl(url) {
     try {
@@ -1451,33 +1509,40 @@ export function registerCMSRoutes(router) {
             const scopeErr = requireCollectionScope(auth.session, params.slug, 'read');
             if (scopeErr)
                 return scopeErr;
-            const url = new URL(request.url);
-            const ctx = buildActionContext(auth.session, db(), url.searchParams.get('locale') ?? undefined);
-            const result = await listDocuments({
-                collection: params.slug,
-                page: Number(url.searchParams.get('page')) || 1,
-                pageSize: clampPageSize(url.searchParams.get('pageSize')),
-                sort: url.searchParams.get('sort') ?? undefined,
-                order: url.searchParams.get('order') ?? undefined,
-                status: url.searchParams.get('status') ?? undefined,
-                locale: url.searchParams.get('locale') ?? undefined,
-                folderId: url.searchParams.get('folderId') ?? undefined,
-            }, ctx);
-            const collectionConfig = getActuateConfig()?.collections?.[params.slug];
-            const fields = collectionConfig?.fields;
-            if (fields && result.docs.length > 0) {
-                const user = { id: auth.session.userId, role: auth.session.role };
-                result.docs = await Promise.all(result.docs.map(async (doc) => {
-                    if (doc.data && typeof doc.data === 'object') {
-                        return {
-                            ...doc,
-                            data: await applyFieldAccess('read', fields, doc.data, user),
-                        };
+            return cachedRead(request, {
+                cache: getActuateConfig()?.cache,
+                tags: [ACTUATE_TAG_ROOT, actuateTag('collection', params.slug)],
+                wrap: jsonWithCache,
+                build: async () => {
+                    const url = new URL(request.url);
+                    const ctx = buildActionContext(auth.session, db(), url.searchParams.get('locale') ?? undefined);
+                    const result = await listDocuments({
+                        collection: params.slug,
+                        page: Number(url.searchParams.get('page')) || 1,
+                        pageSize: clampPageSize(url.searchParams.get('pageSize')),
+                        sort: url.searchParams.get('sort') ?? undefined,
+                        order: url.searchParams.get('order') ?? undefined,
+                        status: url.searchParams.get('status') ?? undefined,
+                        locale: url.searchParams.get('locale') ?? undefined,
+                        folderId: url.searchParams.get('folderId') ?? undefined,
+                    }, ctx);
+                    const collectionConfig = getActuateConfig()?.collections?.[params.slug];
+                    const fields = collectionConfig?.fields;
+                    if (fields && result.docs.length > 0) {
+                        const user = { id: auth.session.userId, role: auth.session.role };
+                        result.docs = await Promise.all(result.docs.map(async (doc) => {
+                            if (doc.data && typeof doc.data === 'object') {
+                                return {
+                                    ...doc,
+                                    data: await applyFieldAccess('read', fields, doc.data, user),
+                                };
+                            }
+                            return doc;
+                        }));
                     }
-                    return doc;
-                }));
-            }
-            return json({ data: result });
+                    return { data: result };
+                },
+            });
         }
         catch (err) {
             return internalError(err);
@@ -1491,22 +1556,36 @@ export function registerCMSRoutes(router) {
             const scopeErr = requireCollectionScope(auth.session, params.slug, 'read');
             if (scopeErr)
                 return scopeErr;
-            const ctx = buildActionContext(auth.session, db());
-            const doc = await getDocument(params.slug, params.id, ctx);
-            if (!doc) {
-                return errorResponse('Document not found', 404);
-            }
-            // `getDocument` already lifts `_layout` / `_pageSettings` to the
-            // top-level page builder envelope and strips internal keys from
-            // `data`. Field-level access has been applied as well — we don't
-            // need to re-apply it here.
-            //
-            // Opt-in relation population: ?populate=author,relatedPosts (or *)
-            // replaces stored IDs with `{ id, title, slug, status, collection }`
-            // summaries. We only run this when the caller asked because it's an
-            // extra DB roundtrip and most internal callers don't need it.
-            const populated = await maybePopulate(request, params.slug, doc, db());
-            return json({ data: populated });
+            return cachedRead(request, {
+                cache: getActuateConfig()?.cache,
+                tags: [
+                    ACTUATE_TAG_ROOT,
+                    actuateTag('collection', params.slug),
+                    actuateTag('doc', params.id),
+                ],
+                wrap: jsonWithCache,
+                build: async () => {
+                    const ctx = buildActionContext(auth.session, db());
+                    const doc = await getDocument(params.slug, params.id, ctx);
+                    if (!doc) {
+                        // Returning a Response short-circuits the cache layer — we
+                        // never cache 404s. The next request gets a fresh DB lookup
+                        // so a doc that's restored from soft-delete is visible
+                        // immediately.
+                        return errorResponse('Document not found', 404);
+                    }
+                    // `getDocument` already lifts `_layout` / `_pageSettings` to
+                    // the top-level page builder envelope and strips internal keys
+                    // from `data`. Field-level access has been applied as well.
+                    //
+                    // Opt-in relation population (?populate=author,relatedPosts |
+                    // *) replaces stored IDs with reference summaries. The
+                    // `?populate=` param is part of the cache key (URL-derived),
+                    // so populated and non-populated reads cache independently.
+                    const populated = await maybePopulate(request, params.slug, doc, db());
+                    return { data: populated };
+                },
+            });
         }
         catch (err) {
             return internalError(err);
@@ -1550,6 +1629,13 @@ export function registerCMSRoutes(router) {
                 userId: auth.session.userId,
                 details: { collection: params.slug, documentId: params.id },
             });
+            // Push to any open live-preview SSE streams. No-op when no admin is
+            // watching the document; the bus drops the call cheaply.
+            notifyPreviewUpdate(params.slug, params.id, {
+                values: doc.data,
+                status: doc.status,
+                updatedAt: doc.updatedAt?.toISOString?.(),
+            });
             return json({ data: doc });
         }
         catch (err) {
@@ -2395,23 +2481,24 @@ export function registerCMSRoutes(router) {
         recentDocuments: [],
     };
     async function safeGroupBy(model, by, where) {
+        if (!model || typeof model !== 'object')
+            return [];
+        let groupByFn;
         try {
-            if (!model || typeof model !== 'object')
-                return [];
-            let groupByFn;
-            try {
-                groupByFn = model.groupBy;
-            }
-            catch {
-                return [];
-            }
-            if (typeof groupByFn !== 'function')
-                return [];
-            return await groupByFn.call(model, { by, where: where ?? {}, _count: { _all: true } });
+            groupByFn = model.groupBy;
         }
         catch {
             return [];
         }
+        if (typeof groupByFn !== 'function')
+            return [];
+        try {
+            return await groupByFn.call(model, { by, where: where ?? {}, _count: { _all: true } });
+        }
+        catch (err) {
+            logSafeQueryFailure('safeGroupBy', err);
+            return [];
+        }
     }
     function computeLightSeoScore(data) {
         let score = 0;
@@ -2444,6 +2531,12 @@ export function registerCMSRoutes(router) {
                 safeCount(d.media),
                 safeCount(d.user),
                 safeFindMany(d.document, {
+                    // Prisma 7's `'join'` strategy folds the User relation into a
+                    // single LATERAL SQL query so the dashboard read costs one
+                    // round-trip instead of two. On the production Vercel Function
+                    // -> Prisma Postgres path that saves ~80 ms (one full network
+                    // RTT) on every dashboard load.
+                    relationLoadStrategy: 'join',
                     where: { deletedAt: null },
                     orderBy: { updatedAt: 'desc' },
                     take: 20,
@@ -4044,6 +4137,12 @@ export function registerCMSRoutes(router) {
             // verify the URL actually points at the document the token was
             // minted for; this prevents using one token to peek at unrelated
             // drafts in the same collection.
+            //
+            // Validation happens BEFORE the runtime-cache lookup so a preview
+            // session can never read from (or write to) the shared cache. The
+            // small price is that every `/resolve?preview=` call runs a JWT
+            // verification even on what would otherwise be a cache hit —
+            // worth it; the alternative is a cache poisoned with draft data.
             const previewToken = url.searchParams.get('preview');
             let previewSession = null;
             if (previewToken) {
@@ -4063,112 +4162,135 @@ export function registerCMSRoutes(router) {
                 }
             }
             const isRootPath = segments.length === 0;
-            const slugFilter = {
-                OR: isRootPath
-                    ? [
-                        { data: { path: ['slug'], equals: 'home' } },
-                        { data: { path: ['slug'], equals: 'index' } },
-                        { slug: 'home' },
-                        { slug: 'index' },
-                    ]
-                    : [{ data: { path: ['slug'], equals: docSlug } }, { slug: docSlug }],
-            };
-            const doc = previewSession
-                ? await db().document.findFirst({
-                    where: {
-                        collection: matchedCollection,
-                        deletedAt: null,
-                        ...slugFilter,
-                    },
-                })
-                : await db().document.findFirst({
-                    where: {
-                        collection: matchedCollection,
-                        deletedAt: null,
-                        status: 'PUBLISHED',
-                        ...slugFilter,
-                    },
-                });
-            if (!doc) {
-                return errorResponse('Document not found', 404);
-            }
-            // Enforce the token ↔ document binding. A leaked or copied token can
-            // only unlock the exact document it was issued for.
-            if (previewSession &&
-                (previewSession.documentId !== doc.id || previewSession.collection !== matchedCollection)) {
-                return errorResponse('Preview token does not match this URL', 403);
-            }
-            let docData = doc.data && typeof doc.data === 'object' ? doc.data : {};
-            // Opt-in: ?populate=author,relatedPosts (or *) — expand relation IDs
-            // into `{ id, title, slug, status, collection }` summaries so the
-            // frontend renders authors / related case studies without a second
-            // request per reference. `resolve` is the highest-leverage place to
-            // do this because it's what marketing pages call from SSR.
-            const populateOpts = parsePopulateParam(new URL(request.url).searchParams.get('populate'));
-            if (populateOpts) {
-                const fields = getActuateConfig()?.collections?.[matchedCollection]?.fields;
-                if (fields) {
-                    try {
-                        docData = await populateRelations(fields, docData, buildRelationLookup(db()), populateOpts);
-                    }
-                    catch (err) {
-                        console.error('[actuate][api] resolve populate failed:', err);
-                    }
-                }
-            }
-            const layout = await resolveLayout(pathParam, docData, matchedCollection);
-            const { _layout: _omit, ...cleanData } = docData;
-            // Compose page meta + JSON-LD up front so client renderers (Next.js
-            // generateMetadata, plain SSR, MCP agents) don't have to re-derive
-            // schema, OG tags, and canonical URLs from raw doc data. Reads the
-            // collection's SEO config and the site-wide SEO defaults — with
-            // DB overrides from /seo/config applied on top of the static config.
-            const cfg = await loadEffectiveConfig();
-            const collectionDef = cfg?.collections?.[matchedCollection] ?? null;
-            const { composePageMeta } = await import('../seo/page-meta.js');
-            const composed = composePageMeta({
-                doc: {
-                    id: doc.id,
-                    collection: doc.collection,
-                    slug: doc.slug ?? cleanData.slug ?? null,
-                    data: cleanData,
-                    publishedAt: doc.publishedAt,
-                    updatedAt: doc.updatedAt,
-                    structuredData: doc.structuredData ?? null,
-                    pageSettings: cleanData.pageSettings ?? null,
-                },
-                collection: collectionDef,
-                config: cfg ?? null,
-                siteUrl: siteUrlFromRequest(request, cfg),
-            });
-            return json({
-                data: {
-                    id: doc.id,
-                    collection: doc.collection,
-                    data: cleanData,
-                    status: doc.status,
-                    publishedAt: doc.publishedAt,
-                    structuredData: composed.jsonLd ?? doc.structuredData,
-                },
-                meta: {
-                    title: composed.title,
-                    description: composed.description,
-                    canonical: composed.canonical,
-                    url: composed.url,
-                    tags: composed.meta,
-                    html: composed.metaHtml,
-                },
-                jsonLd: composed.jsonLd,
-                jsonLdHtml: composed.jsonLdHtml,
-                ...(Object.keys(layout).length > 0 ? { layout } : {}),
-                ...(previewSession
-                    ? {
-                        preview: {
-                            active: true,
-                            expiresAt: previewSession.expiresAt.toISOString(),
+            // Heavy compute (doc lookup → populate → meta composition) lives in
+            // a closure so the optional runtime-cache layer can short-circuit
+            // it on a hit. The cache layer is bypassed entirely when a preview
+            // session is active — a draft must never enter the shared cache.
+            const buildResolveBody = async () => {
+                const slugFilter = {
+                    OR: isRootPath
+                        ? [
+                            { data: { path: ['slug'], equals: 'home' } },
+                            { data: { path: ['slug'], equals: 'index' } },
+                            { slug: 'home' },
+                            { slug: 'index' },
+                        ]
+                        : [{ data: { path: ['slug'], equals: docSlug } }, { slug: docSlug }],
+                };
+                const doc = previewSession
+                    ? await db().document.findFirst({
+                        where: {
+                            collection: matchedCollection,
+                            deletedAt: null,
+                            ...slugFilter,
                         },
+                    })
+                    : await db().document.findFirst({
+                        where: {
+                            collection: matchedCollection,
+                            deletedAt: null,
+                            status: 'PUBLISHED',
+                            ...slugFilter,
+                        },
+                    });
+                if (!doc) {
+                    return errorResponse('Document not found', 404);
+                }
+                // Enforce the token ↔ document binding. A leaked or copied token can
+                // only unlock the exact document it was issued for.
+                if (previewSession &&
+                    (previewSession.documentId !== doc.id || previewSession.collection !== matchedCollection)) {
+                    return errorResponse('Preview token does not match this URL', 403);
+                }
+                let docData = doc.data && typeof doc.data === 'object' ? doc.data : {};
+                // Opt-in: ?populate=author,relatedPosts (or *) — expand relation IDs
+                // into `{ id, title, slug, status, collection }` summaries so the
+                // frontend renders authors / related case studies without a second
+                // request per reference. `resolve` is the highest-leverage place to
+                // do this because it's what marketing pages call from SSR.
+                const populateOpts = parsePopulateParam(new URL(request.url).searchParams.get('populate'));
+                if (populateOpts) {
+                    const fields = getActuateConfig()?.collections?.[matchedCollection]?.fields;
+                    if (fields) {
+                        try {
+                            docData = await populateRelations(fields, docData, buildRelationLookup(db()), populateOpts);
+                        }
+                        catch (err) {
+                            console.error('[actuate][api] resolve populate failed:', err);
+                        }
                     }
-                    : {}),
+                }
+                const layout = await resolveLayout(pathParam, docData, matchedCollection);
+                const { _layout: _omit, ...cleanData } = docData;
+                // Compose page meta + JSON-LD up front so client renderers (Next.js
+                // generateMetadata, plain SSR, MCP agents) don't have to re-derive
+                // schema, OG tags, and canonical URLs from raw doc data. Reads the
+                // collection's SEO config and the site-wide SEO defaults — with
+                // DB overrides from /seo/config applied on top of the static config.
+                const cfg = await loadEffectiveConfig();
+                const collectionDef = cfg?.collections?.[matchedCollection] ?? null;
+                const { composePageMeta } = await import('../seo/page-meta.js');
+                const composed = composePageMeta({
+                    doc: {
+                        id: doc.id,
+                        collection: doc.collection,
+                        slug: doc.slug ?? cleanData.slug ?? null,
+                        data: cleanData,
+                        publishedAt: doc.publishedAt,
+                        updatedAt: doc.updatedAt,
+                        structuredData: doc.structuredData ?? null,
+                        pageSettings: cleanData.pageSettings ?? null,
+                    },
+                    collection: collectionDef,
+                    config: cfg ?? null,
+                    siteUrl: siteUrlFromRequest(request, cfg),
+                });
+                return {
+                    data: {
+                        id: doc.id,
+                        collection: doc.collection,
+                        data: cleanData,
+                        status: doc.status,
+                        publishedAt: doc.publishedAt,
+                        structuredData: composed.jsonLd ?? doc.structuredData,
+                    },
+                    meta: {
+                        title: composed.title,
+                        description: composed.description,
+                        canonical: composed.canonical,
+                        url: composed.url,
+                        tags: composed.meta,
+                        html: composed.metaHtml,
+                    },
+                    jsonLd: composed.jsonLd,
+                    jsonLdHtml: composed.jsonLdHtml,
+                    ...(Object.keys(layout).length > 0 ? { layout } : {}),
+                    ...(previewSession
+                        ? {
+                            preview: {
+                                active: true,
+                                expiresAt: previewSession.expiresAt.toISOString(),
+                            },
+                        }
+                        : {}),
+                };
+            };
+            // Preview-token requests bypass the cache (CDN + Runtime) so a
+            // leaked cached preview can never show up for anonymous traffic.
+            // Anonymous reads flow through cachedRead — coarse tags (the
+            // wholesale `actuate` tag + a path tag) so every write drains
+            // every cached resolve entry. Per-doc tagging would require
+            // resolving the doc id BEFORE the cache lookup, which defeats
+            // the purpose of caching at all.
+            if (previewSession) {
+                const body = await buildResolveBody();
+                return body instanceof Response ? body : json(body);
+            }
+            return cachedRead(request, {
+                cache: getActuateConfig()?.cache,
+                tags: [ACTUATE_TAG_ROOT, actuateTag('path', pathParam)],
+                wrap: jsonWithCache,
+                build: buildResolveBody,
             });
         }
         catch (err) {
@@ -4433,6 +4555,418 @@ export function registerCMSRoutes(router) {
             return internalError(err, 'fetch preview data');
         }
     });
+    /**
+     * Server-Sent Events stream for live preview. The admin's `LivePreview`
+     * panel opens an `EventSource('/api/cms/preview/stream?token=...')` and
+     * relays every `event: update` frame to the previewed iframe through
+     * `postMessage`. Token-based auth (instead of cookies) because
+     * `EventSource` cannot send arbitrary headers.
+     *
+     * Emits:
+     *   - `event: ready` once on connection (handshake).
+     *   - `event: update` whenever the underlying draft document is updated
+     *     (see `PUT /collections/:slug/:id` for the emit site).
+     *   - `: heartbeat\n\n` keepalive comments every 25 s so proxies don't
+     *     reap idle connections.
+     *
+     * Closes cleanly after 4 minutes so platform idle caps don't terminate
+     * the connection mid-event; EventSource will auto-reconnect.
+     */
+    router.get('/preview/stream', async (request) => {
+        try {
+            const url = new URL(request.url);
+            const token = url.searchParams.get('token');
+            if (!token)
+                return errorResponse('Preview token required', 401);
+            const preview = createPreviewAdapter(getSessionSecret(), db());
+            const session = await preview.validatePreviewToken(token);
+            if (!session)
+                return errorResponse('Invalid or expired preview token', 401);
+            return createPreviewStreamResponse(session);
+        }
+        catch (err) {
+            return internalError(err, 'open preview stream');
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Comments — Phase 3 / slice 4
+    //
+    // Threaded, anchored discussion attached to documents. The Yjs gateway
+    // already lives on `/realtime/sync`; comments are *not* sent over that
+    // wire — they're plain REST so plugins, mobile clients, and notification
+    // workers can consume them without speaking the CRDT protocol.
+    //
+    // Routes (all rewritten paths, no `/api/cms` prefix):
+    //   POST   /documents/:documentId/comments      — create top-level / reply
+    //   GET    /documents/:documentId/comments      — list (filters: resolved, deleted, pageSize)
+    //   PATCH  /comments/:id                        — edit body (author / admin)
+    //   POST   /comments/:id/resolve                — resolve thread (write-role / author)
+    //   POST   /comments/:id/reopen                 — re-open a resolved thread
+    //   DELETE /comments/:id                        — soft-delete (author / admin)
+    //
+    // The service module in `realtime/comments.ts` owns validation +
+    // permissions; these handlers are thin envelopes that map auth → service
+    // call → JSON response.
+    // ---------------------------------------------------------------------------
+    function mapCommentsErrorStatus(error) {
+        switch (error.code) {
+            case 'validation':
+                return 400;
+            case 'not_found':
+                return 404;
+            case 'forbidden':
+                return 403;
+            case 'conflict':
+                return 409;
+        }
+    }
+    function respondCommentsError(error) {
+        return errorResponse(error.message, mapCommentsErrorStatus(error));
+    }
+    function commentsDb() {
+        return db();
+    }
+    function notificationsDb() {
+        return db();
+    }
+    function mapNotificationsErrorStatus(error) {
+        if (error.code === 'validation')
+            return 400;
+        if (error.code === 'forbidden')
+            return 403;
+        if (error.code === 'not_found')
+            return 404;
+        return 500;
+    }
+    function respondNotificationsError(error) {
+        return errorResponse(error.message, mapNotificationsErrorStatus(error));
+    }
+    /**
+     * Lookup helper used by the notification triggers below. We need the
+     * comment's `userId` (and, for replies, the *parent* comment's userId)
+     * so we can decide who to notify. The lookup is best-effort: if the
+     * row is missing (e.g. the comment was deleted between create and
+     * trigger), we silently skip the notification.
+     */
+    async function findCommentRecipient(commentId) {
+        try {
+            const client = db();
+            if (!client.documentComment)
+                return null;
+            return await client.documentComment.findUnique({ where: { id: commentId } });
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Issue notifications for a new comment. Two paths:
+     *
+     * - **Reply** — the actor replied to someone else's thread → notify
+     *   the root comment's author with kind `comment_reply`.
+     * - **Mentions** — any `@<userId>` token in the body → notify each
+     *   mentioned user (other than the actor) with kind `comment_mention`.
+     */
+    async function notifyOnCommentCreated(opts) {
+        const ndb = notificationsDb();
+        if (opts.parentId) {
+            const root = await findCommentRecipient(opts.parentId);
+            if (root && root.userId && root.userId !== opts.actorId) {
+                await createNotification(ndb, {
+                    userId: root.userId,
+                    documentId: opts.documentId,
+                    commentId: opts.commentId,
+                    payload: {
+                        kind: 'comment_reply',
+                        actorId: opts.actorId,
+                        actorName: opts.actorName,
+                        excerpt: excerptForNotification(opts.body),
+                    },
+                });
+            }
+        }
+        for (const userId of extractMentionedUserIds(opts.body)) {
+            if (userId === opts.actorId)
+                continue;
+            await createNotification(ndb, {
+                userId,
+                documentId: opts.documentId,
+                commentId: opts.commentId,
+                payload: {
+                    kind: 'comment_mention',
+                    actorId: opts.actorId,
+                    actorName: opts.actorName,
+                    excerpt: excerptForNotification(opts.body),
+                },
+            });
+        }
+    }
+    /** Notify the comment's author when someone else resolves their thread. */
+    async function notifyOnCommentResolved(opts) {
+        const comment = await findCommentRecipient(opts.commentId);
+        if (!comment || !comment.userId || comment.userId === opts.actorId)
+            return;
+        await createNotification(notificationsDb(), {
+            userId: comment.userId,
+            commentId: opts.commentId,
+            payload: {
+                kind: 'comment_resolved',
+                actorId: opts.actorId,
+                actorName: opts.actorName,
+                rootExcerpt: excerptForNotification(comment.body),
+            },
+        });
+    }
+    router.post('/documents/:documentId/comments', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            // Posting a comment requires at least write access; comments mutate
+            // collaborative state and we don't want anonymous read-only tokens
+            // (API keys without write scope) leaving discussion behind.
+            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
+            if (roleErr)
+                return roleErr;
+            const body = (await request.json());
+            const result = await createCommentService(commentsDb(), {
+                documentId: params.documentId,
+                userId: auth.session.userId,
+                body: typeof body.body === 'string' ? body.body : '',
+                anchor: body.anchor,
+                parentId: typeof body.parentId === 'string' ? body.parentId : null,
+            });
+            if (!result.ok)
+                return respondCommentsError(result.error);
+            await logEvent({
+                event: 'comment_created',
+                userId: auth.session.userId,
+                details: {
+                    documentId: params.documentId,
+                    commentId: result.value.id,
+                    parentId: result.value.parentId,
+                },
+            });
+            // Fire-and-forget — a notification failure should never block the
+            // comment from being saved. Errors surface via logEvent (TODO:
+            // wire a dedicated audit channel once the realtime SSE feed is up).
+            void notifyOnCommentCreated({
+                commentId: result.value.id,
+                body: result.value.body,
+                parentId: result.value.parentId,
+                documentId: result.value.documentId,
+                actorId: auth.session.userId,
+                actorName: null,
+            }).catch(() => undefined);
+            return json({ data: result.value }, 201);
+        }
+        catch (err) {
+            return internalError(err, 'create comment');
+        }
+    });
+    router.get('/documents/:documentId/comments', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            // Reading comments piggy-backs on the same scope as reading the
+            // document. There is no comment-specific API-key scope today; we
+            // re-use document-read so external integrations can fetch a thread
+            // without granting them write access.
+            const url = new URL(request.url);
+            const includeResolved = url.searchParams.get('includeResolved') === 'true';
+            const includeDeleted = url.searchParams.get('includeDeleted') === 'true';
+            const pageSizeRaw = url.searchParams.get('pageSize');
+            const pageSize = pageSizeRaw === null ? undefined : Number(pageSizeRaw);
+            // Soft-deleted comments are admin-only — they hold moderation history
+            // that should not leak via a query parameter to a regular editor.
+            if (includeDeleted && !ADMIN_ROLES.has(auth.session.role)) {
+                return errorResponse('includeDeleted requires admin role', 403);
+            }
+            const result = await listCommentsService(commentsDb(), {
+                documentId: params.documentId,
+                includeResolved,
+                includeDeleted,
+                pageSize,
+            });
+            if (!result.ok)
+                return respondCommentsError(result.error);
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'list comments');
+        }
+    });
+    router.patch('/comments/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const body = (await request.json());
+            const result = await updateCommentService(commentsDb(), params.id, { body: typeof body.body === 'string' ? body.body : '' }, { userId: auth.session.userId, isAdmin: ADMIN_ROLES.has(auth.session.role) });
+            if (!result.ok)
+                return respondCommentsError(result.error);
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'update comment');
+        }
+    });
+    router.post('/comments/:id/resolve', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const result = await resolveCommentService(commentsDb(), params.id, {
+                userId: auth.session.userId,
+                canResolve: WRITE_ROLES.has(auth.session.role),
+            });
+            if (!result.ok)
+                return respondCommentsError(result.error);
+            await logEvent({
+                event: 'comment_resolved',
+                userId: auth.session.userId,
+                details: { commentId: params.id },
+            });
+            void notifyOnCommentResolved({
+                commentId: params.id,
+                actorId: auth.session.userId,
+                actorName: null,
+            }).catch(() => undefined);
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'resolve comment');
+        }
+    });
+    router.post('/comments/:id/reopen', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const result = await reopenCommentService(commentsDb(), params.id, {
+                userId: auth.session.userId,
+                canResolve: WRITE_ROLES.has(auth.session.role),
+            });
+            if (!result.ok)
+                return respondCommentsError(result.error);
+            await logEvent({
+                event: 'comment_reopened',
+                userId: auth.session.userId,
+                details: { commentId: params.id },
+            });
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'reopen comment');
+        }
+    });
+    router.delete('/comments/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const result = await deleteCommentService(commentsDb(), params.id, {
+                userId: auth.session.userId,
+                isAdmin: ADMIN_ROLES.has(auth.session.role),
+            });
+            if (!result.ok)
+                return respondCommentsError(result.error);
+            await logEvent({
+                event: 'comment_deleted',
+                userId: auth.session.userId,
+                details: { commentId: params.id },
+            });
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'delete comment');
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Notifications — Phase 3 / slice 6
+    //
+    // Notifications are the read-side of the collaboration event stream:
+    // when a comment lifecycle action affects another user (reply,
+    // mention, resolve-of-yours) we record a row in `DocumentNotification`
+    // and the bell in the admin polls / streams it.
+    //
+    // Routes:
+    //
+    //   GET    /notifications              — list current user's feed
+    //   GET    /notifications/unread-count — badge counter
+    //   POST   /notifications/:id/read     — mark a single notification read
+    //   POST   /notifications/read-all     — clear the bell
+    //
+    // Auth: every route is scoped to `auth.session.userId`; there is no
+    // admin override (notifications are personal and never moderated).
+    // ---------------------------------------------------------------------------
+    router.get('/notifications', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const url = new URL(request.url);
+            const includeRead = url.searchParams.get('includeRead') === 'true';
+            const pageSizeRaw = url.searchParams.get('pageSize');
+            const pageSize = pageSizeRaw === null ? undefined : Number(pageSizeRaw);
+            const result = await listNotificationsForUser(notificationsDb(), {
+                userId: auth.session.userId,
+                includeRead,
+                pageSize,
+            });
+            if (!result.ok)
+                return respondNotificationsError(result.error);
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'list notifications');
+        }
+    });
+    router.get('/notifications/unread-count', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const result = await notificationsUnreadCount(notificationsDb(), auth.session.userId);
+            if (!result.ok)
+                return respondNotificationsError(result.error);
+            return json({ data: { count: result.value } });
+        }
+        catch (err) {
+            return internalError(err, 'notifications unread count');
+        }
+    });
+    router.post('/notifications/:id/read', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const result = await markNotificationRead(notificationsDb(), params.id, {
+                userId: auth.session.userId,
+            });
+            if (!result.ok)
+                return respondNotificationsError(result.error);
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'mark notification read');
+        }
+    });
+    router.post('/notifications/read-all', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const result = await markAllNotificationsRead(notificationsDb(), auth.session.userId);
+            if (!result.ok)
+                return respondNotificationsError(result.error);
+            return json({ data: result.value });
+        }
+        catch (err) {
+            return internalError(err, 'mark all notifications read');
+        }
+    });
     // ---------------------------------------------------------------------------
     // Workflow routes
     // ---------------------------------------------------------------------------
@@ -4495,6 +5029,11 @@ export function registerCMSRoutes(router) {
                 return errorResponse('Document not found', 404);
             const [versions, total] = await Promise.all([
                 db().version.findMany({
+                    // See dashboard `recent docs` query for the rationale: `'join'`
+                    // folds the User include into one round-trip, halving the cost
+                    // of the versions list on a cross-region Function -> Postgres
+                    // path.
+                    relationLoadStrategy: 'join',
                     where: { documentId: params.id },
                     orderBy: { createdAt: 'desc' },
                     skip,
@@ -4808,12 +5347,19 @@ export function registerCMSRoutes(router) {
             const scopeErr = requireGlobalScope(auth.session, params.slug);
             if (scopeErr)
                 return scopeErr;
-            const ctx = buildActionContext(auth.session, db());
-            const global = await getGlobal(params.slug, ctx);
-            if (!global) {
-                return errorResponse('Global not found', 404);
-            }
-            return json({ data: global });
+            return cachedRead(request, {
+                cache: getActuateConfig()?.cache,
+                tags: [ACTUATE_TAG_ROOT, actuateTag('global', params.slug)],
+                wrap: jsonWithCache,
+                build: async () => {
+                    const ctx = buildActionContext(auth.session, db());
+                    const global = await getGlobal(params.slug, ctx);
+                    if (!global) {
+                        return errorResponse('Global not found', 404);
+                    }
+                    return { data: global };
+                },
+            });
         }
         catch (err) {
             return internalError(err);