canopycms 0.0.68-int.98 → 0.1.0

package/dist/api/comments.js

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 import { CommentStore } from '../comment-store.js';
+import { lookupUserProfiles } from '../auth/user-metadata-lookup.js';
+import { getErrorMessage } from '../utils/error.js';
 import { isReviewer } from '../authorization/index.js';
+import { parseLogicalPath } from '../paths/validation.js';
+import { normalizeFilesystemPath } from '../paths/normalize.js';
 import { defineEndpoint } from './route-builder.js';
+import { isItemKey } from '../item-keys.js';
+import { parseCanopyPath } from '../editor/canopy-path.js';
 import { branchParamSchema, branchNameSchema, logicalPathSchema } from './validators.js';
 // ============================================================================
 // Zod Schemas for Validation
@@ -16,14 +22,76 @@ const addCommentBodySchema = z.object({
     type: z.enum(['field', 'entry', 'branch']),
     entryPath: logicalPathSchema.optional(),
     canopyPath: z.string().optional(), // Canopy field path, not a file path
+    itemKeys: z.array(z.string().refine(isItemKey, 'not an item key')).max(32).optional(),
 });
-const listCommentsHandler = async (gc, _ctx, _req, _params) => {
+/**
+ * Whether `entryPath` is spelled the way path rules expect an entry's logical path: rooted at
+ * the content root, with no empty or `.` segment. Rules are globs over that spelling, so
+ * `secret/plan` (which the content API reads as `content/secret/plan`) and
+ * `content/./secret/plan` both miss a rule written for `content/secret/**`.
+ */
+const isCanonicalEntryPath = (entryPath, contentRoot) => entryPath.startsWith(`${normalizeFilesystemPath(contentRoot)}/`) &&
+    entryPath.split('/').every((segment) => segment !== '' && segment !== '.');
+/**
+ * Whether the user may see a thread: its entry's path rules at `read`, the level a content
+ * read needs, so a thread discloses nothing about an entry its reader could not open. A
+ * field thread is governed by its entry. A thread with no entry path (a branch thread) is
+ * governed by branch access alone, which the `branchAccess` guard has already passed. An
+ * entry path that is not a canonical logical path is denied: comments.json is read without
+ * schema validation.
+ */
+const canReadThreadEntry = (checkAccess, contentRoot, entryPath) => {
+    if (entryPath === undefined)
+        return true;
+    const parsed = parseLogicalPath(entryPath);
+    return (parsed.ok &&
+        isCanonicalEntryPath(parsed.path, contentRoot) &&
+        checkAccess(parsed.path, 'read').allowed);
+};
+/** One checker per request, bound to the content root its paths are canonical against. */
+const createThreadReadCheck = async (ctx, req, branchContext) => {
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    const contentRoot = ctx.services.config.contentRoot || 'content';
+    return (entryPath) => canReadThreadEntry(checkAccess, contentRoot, entryPath);
+};
+/**
+ * The profile of everyone who wrote or resolved one of `threads`, looked up only for threads
+ * already filtered to what the requester may read, so the list names no one the requester could
+ * not see in a thread. A failed lookup costs the names, never the threads.
+ */
+const lookupThreadUsers = async (ctx, threads) => {
+    const authPlugin = ctx.authPlugin;
+    if (!authPlugin)
+        return [];
+    try {
+        const ids = [];
+        for (const thread of threads) {
+            ids.push(thread.authorId, thread.resolvedBy);
+            // comments.json is parsed without validation, so a thread may lack its comment list.
+            if (Array.isArray(thread.comments)) {
+                for (const comment of thread.comments)
+                    ids.push(comment?.userId);
+            }
+        }
+        return await lookupUserProfiles(authPlugin, ids);
+    }
+    catch (error) {
+        console.error('CanopyCMS: Failed to look up comment authors:', getErrorMessage(error));
+        return [];
+    }
+};
+const listCommentsHandler = async (gc, ctx, req, _params) => {
     const { branchContext } = gc;
     const commentStore = new CommentStore(branchContext.branchRoot);
-    const threads = await commentStore.listThreads({ includeResolved: true });
-    return { ok: true, status: 200, data: { threads } };
+    const [allThreads, canRead] = await Promise.all([
+        commentStore.listThreads({ includeResolved: true }),
+        createThreadReadCheck(ctx, req, branchContext),
+    ]);
+    const threads = allThreads.filter((thread) => canRead(thread.entryPath));
+    const users = await lookupThreadUsers(ctx, threads);
+    return { ok: true, status: 200, data: { threads, users } };
 };
-const addCommentHandler = async (gc, _ctx, req, _params, body) => {
+const addCommentHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
     // Validate required fields based on type
     if (body.type === 'field' && !body.canopyPath) {
@@ -33,6 +101,18 @@ const addCommentHandler = async (gc, _ctx, req, _params, body) => {
             error: 'canopyPath required for field comments',
         };
     }
+    // A new field thread inside list items names each item on its path by key, one per list index,
+    // so it follows the item rather than the index. A reply lands on its thread and needs none.
+    const listIndexes = body.type === 'field' && body.canopyPath && !body.threadId
+        ? parseCanopyPath(body.canopyPath).filter((s) => typeof s === 'number').length
+        : 0;
+    if ((body.itemKeys?.length ?? 0) !== listIndexes) {
+        return {
+            ok: false,
+            status: 400,
+            error: 'itemKeys must name one item per list index in a new field comment’s canopyPath',
+        };
+    }
     if ((body.type === 'field' || body.type === 'entry') && !body.entryPath) {
         return {
             ok: false,
@@ -40,22 +120,51 @@ const addCommentHandler = async (gc, _ctx, req, _params, body) => {
             error: 'entryPath required for field/entry comments',
         };
     }
+    // Commenting needs read access to the entry the comment lands on. A reply lands on the
+    // stored thread, so it is checked against that thread's entry path, which never changes
+    // once the thread exists; a reply to a thread the user cannot read answers as missing, as
+    // resolve does.
     const commentStore = new CommentStore(branchContext.branchRoot);
+    const [existing, canRead] = await Promise.all([
+        body.threadId ? commentStore.getThread(body.threadId) : Promise.resolve(null),
+        createThreadReadCheck(ctx, req, branchContext),
+    ]);
+    if (body.threadId) {
+        if (!existing || !canRead(existing.entryPath)) {
+            return { ok: false, status: 404, error: 'Thread not found' };
+        }
+        const reply = await commentStore.addReply({
+            userId: req.user.userId,
+            text: body.text,
+            threadId: body.threadId,
+        });
+        if (!reply) {
+            return { ok: false, status: 404, error: 'Thread not found' };
+        }
+        return { ok: true, status: 201, data: reply };
+    }
+    if (!canRead(body.entryPath)) {
+        return { ok: false, status: 403, error: 'Forbidden' };
+    }
     const result = await commentStore.addComment({
         userId: req.user.userId,
         text: body.text,
-        threadId: body.threadId,
         type: body.type,
         entryPath: body.entryPath,
         canopyPath: body.canopyPath,
+        itemKeys: body.itemKeys,
     });
     return { ok: true, status: 201, data: result };
 };
-const resolveCommentHandler = async (gc, _ctx, req, params) => {
+const resolveCommentHandler = async (gc, ctx, req, params) => {
     const { branchContext } = gc;
     const commentStore = new CommentStore(branchContext.branchRoot);
-    const thread = await commentStore.getThread(params.threadId);
-    if (!thread) {
+    const [thread, canRead] = await Promise.all([
+        commentStore.getThread(params.threadId),
+        createThreadReadCheck(ctx, req, branchContext),
+    ]);
+    // A thread the user cannot read answers as missing, so its id does not confirm it exists.
+    if (!thread || !canRead(thread.entryPath)) {
         return { ok: false, status: 404, error: 'Thread not found' };
     }
     // Check permissions: thread author, reviewer, or admin
@@ -85,7 +194,7 @@ const listComments = defineEndpoint({
     params: branchParamSchema,
     responseType: 'CommentsResponse',
     response: {},
-    defaultMockData: { threads: [] },
+    defaultMockData: { threads: [], users: [] },
     guards: ['branchAccess'],
     handler: listCommentsHandler,
 });

package/dist/api/content.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { EntryValidationIssue } from '../config/index.js';
-import { type Slug } from '../paths/index.js';
+import { type LogicalPath, type Slug } from '../paths/index.js';
 export type ContentReadResponse = ApiResponse<{
     format: string;
     data: Record<string, unknown>;
@@ -41,8 +41,8 @@ export interface WriteContentBody {
     body?: string;
     /**
      * OCC token. A number from a prior read/write response makes this an update,
-     * rejected with 409 if the file's mtime no longer matches (a file deleted
-     * since is written anew). `null` or omitted makes it
+     * rejected with 409 if the file's mtime no longer matches, or with 409 `ENTRY_GONE` if the
+     * file is gone (deleted or moved since the read). `null` or omitted makes it
      * a create, rejected with 409 if the entry already exists. There is no blind
      * write: without a token, "no conflict detection" would be indistinguishable
      * from "lost the token", so an update has to prove which version it read.
@@ -61,7 +61,7 @@ export interface RenameEntryBody {
 export declare const CONTENT_ROUTES: {
     readonly read: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
-        path: z.ZodType<import("../paths/index.js").LogicalPath, z.ZodTypeDef, import("../paths/index.js").LogicalPath>;
+        path: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
     }, "strip", z.ZodTypeAny, {
         path: string & {
             readonly __brand: "LogicalPath";
@@ -79,7 +79,7 @@ export declare const CONTENT_ROUTES: {
     }>, undefined, ContentReadResponse>;
     readonly write: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
-        path: z.ZodType<import("../paths/index.js").LogicalPath, z.ZodTypeDef, import("../paths/index.js").LogicalPath>;
+        path: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
         entryType: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string & {
@@ -104,18 +104,18 @@ export declare const CONTENT_ROUTES: {
         expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
         format: "mdx" | "md" | "json" | "yaml";
+        data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
-        data?: Record<string, unknown> | undefined;
     }, {
         format: "mdx" | "md" | "json" | "yaml";
+        data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
-        data?: Record<string, unknown> | undefined;
     }>, ContentWriteResponse>;
     readonly validateReferences: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
-        path: z.ZodType<import("../paths/index.js").LogicalPath, z.ZodTypeDef, import("../paths/index.js").LogicalPath>;
+        path: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
         entryType: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string & {
@@ -142,7 +142,7 @@ export declare const CONTENT_ROUTES: {
     }>, ReferenceValidationResponse>;
     readonly renameEntry: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
-        path: z.ZodType<import("../paths/index.js").LogicalPath, z.ZodTypeDef, import("../paths/index.js").LogicalPath>;
+        path: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
     }, "strip", z.ZodTypeAny, {
         path: string & {
             readonly __brand: "LogicalPath";

package/dist/api/content.js

@@ -1,13 +1,19 @@
 import { z } from 'zod';
-import { BranchSyncingError, ContentStore, ContentStoreError, ContentConflictError, DuplicateContentIdError, UrlPathConflictError, getDefaultEntryType, } from '../content-store.js';
+import { ENTRY_CHANGED_MESSAGE, ENTRY_GONE_MESSAGE } from './entries-constants.js';
+import { BranchSyncingError, ContentStore, ContentStoreError, ContentConflictError, DuplicateContentIdError, EntryGoneError, UrlPathConflictError, getDefaultEntryType, } from '../content-store.js';
 import { defineEndpoint } from './route-builder.js';
+import { SchemaUnavailableError } from '../schema/schema-unavailable-error.js';
 import { ReferenceValidator } from '../validation/reference-validator.js';
 import { findUnknownKeys, mergeBodyIntoData, normalizeReferenceValues, validateEntryData, } from '../validation/entry-validator.js';
 import { validateEntryLinks } from '../validation/entry-link-validator.js';
+import { findMarkdownSafetyIssues, splitByStored } from '../validation/markdown-safety.js';
+import { collectReferenceIds } from '../validation/field-traversal.js';
 import { branchNameSchema, logicalPathSchema, slugSchema } from './validators.js';
 import { entryLogicalPath, parseSlug } from '../paths/index.js';
 import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { isDataOnlyFormat } from '../utils/format.js';
+import { withItemKeys } from '../item-keys.js';
+import { findBodyFieldName } from '../utils/body-field.js';
 /**
  * Parse an API path into logical path segments, prepending the content root if needed.
  * Shared by all content API handlers.
@@ -110,6 +116,40 @@ const readContentHandler = async (gc, ctx, req, params) => {
         throw err;
     }
 };
+/**
+ * A reference's field and id, positions dropped (`blocks[2].author` → `blocks.author`), so
+ * reordering blocks or list items keeps a match while moving an id to a field of another name
+ * does not.
+ */
+const referenceSite = (fieldPath, id) => `${fieldPath.replace(/\[\d+\]/g, '')}\0${id}`;
+/** Every reference site the stored entry holds, read raw so a missing target still yields its id. */
+const storedReferenceSites = async (store, collectionPath, slug, fields) => {
+    const doc = await store.read(collectionPath, slug, { resolveReferences: false });
+    return new Set(collectReferenceIds(fields, doc.data).map((ref) => referenceSite(ref.path, ref.id)));
+};
+function withoutKey(record, key) {
+    if (!(key in record))
+        return record;
+    const { [key]: _dropped, ...rest } = record;
+    return rest;
+}
+/** The policy's issues in the stored entry, which a save may keep. */
+const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields, siteAllow) => {
+    // A stored file that does not read keeps nothing, so the save's code is refused, not a 500.
+    const doc = await store
+        .read(collectionPath, slug, { resolveReferences: false })
+        .catch(() => undefined);
+    if (doc === undefined)
+        return [];
+    const data = 'body' in doc ? mergeBodyIntoData(fields, doc.data, doc.body) : doc.data;
+    return findMarkdownSafetyIssues(fields, doc.format, data, siteAllow);
+};
+const entryGoneResponse = () => ({
+    ok: false,
+    status: 409,
+    error: ENTRY_GONE_MESSAGE,
+    code: 'ENTRY_GONE',
+});
 const writeContentHandler = async (gc, ctx, req, params, body) => {
     const { branchContext } = gc;
     const flatSchema = branchContext.flatSchema;
@@ -135,15 +175,22 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     if (!access.allowed) {
         return { ok: false, status: 403, error: 'Forbidden' };
     }
+    // Update guard: an update whose entry is gone is refused before anything below judges it,
+    // since its entry type can no longer be read off the file and every check that follows would
+    // treat it as a create. store.write() re-enforces it in-lock (EntryGoneError).
+    const exists = await store.documentExists(schemaItem.logicalPath, slug);
+    if (body.expectedVersion != null && !exists)
+        return entryGoneResponse();
     // Authoritative schema validation at the write boundary (COMPOUND-2): the server re-checks
     // required fields, type/format correctness, and non-empty required references (rules shared
     // with the editor via validation/entry-validator), plus reference EXISTENCE and
     // EntryTypeConfig.maxItems (SCH-H3) — so a direct API call can't bypass what the editor's form
     // enforces client-side.
     //
-    // Carve-out: a create scaffold (target doesn't exist yet, payload is entirely empty `{}`/no
-    // body) skips field validation, since the editor's create flow writes an empty scaffold before
-    // the user fills the form.
+    // Carve-outs for a create (the target doesn't exist yet), because the editor creates an entry
+    // before the user fills its form: an entirely empty payload (`{}`, no body) skips field
+    // validation, and any other create skips only the required-field checks, so a create carrying
+    // just a title lands. Every save after that is checked in full.
     // Resolve the entry-type config the store will write with (mirrors ContentStore.write)
     let entryTypeConfig;
     let fields = [];
@@ -198,20 +245,30 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
         fields = entryTypeConfig?.schema ?? [];
         maxItems = entryTypeConfig?.maxItems;
     }
-    const data = body.data ?? {};
+    // Refused before validation, which an empty `fields` would wave through; mapped to a 503.
+    const resolvedEntryType = schemaItem.type === 'entry-type' ? schemaItem : entryTypeConfig;
+    if (resolvedEntryType?.unavailable) {
+        throw new SchemaUnavailableError(resolvedEntryType.name, resolvedEntryType.unavailable);
+    }
     const isDataOnly = isDataOnlyFormat(body.format);
+    // An md/mdx file's body field is its body, so a frontmatter key of that name is dropped: no
+    // check would see it, and a read or a resolved reference would serve it as the body.
+    const requestData = isDataOnly || body.data === undefined
+        ? body.data
+        : withoutKey(body.data, findBodyFieldName(fields));
+    const data = requestData ?? {};
     // The store's own `undefined` (blind write) is never reachable from here: an omitted token is
     // a create, so an update that lost its token 409s instead of overwriting unchecked.
     const expectedVersion = body.expectedVersion ?? null;
     const createConflictError = body.expectedVersion === null
         ? `An entry with slug "${slug}" already exists`
         : `An entry with slug "${slug}" already exists; an update must send the expectedVersion from its last read`;
+    const keptWarnings = [];
     try {
-        const exists = await store.documentExists(schemaItem.logicalPath, slug);
         // Create guard: a create against a slug that already has content must never silently
         // overwrite it — short-circuit with 409 before field validation runs, so the error names the
         // real problem instead of "field is required" or a bare conflict. store.write() re-enforces
-        // this itself inside its per-entry lock against a fresh stat (the race-safe authoritative
+        // this itself inside its per-entry lock against a fresh open (the race-safe authoritative
         // check); this is just a cheaper fast path for the common case.
         if (expectedVersion === null && exists) {
             return { ok: false, status: 409, error: createConflictError };
@@ -256,7 +313,27 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             // Pure rules (shared with the editor). For md/mdx the body is validated
             // as the schema's isBody field.
             const dataForValidation = isDataOnly ? data : mergeBodyIntoData(fields, data, body.body ?? '');
-            const fieldErrors = validateEntryData(fields, dataForValidation);
+            const fieldErrors = validateEntryData(fields, dataForValidation, '', {
+                required: exists,
+            });
+            // Code in markdown or MDX (validation/markdown-safety.ts). A field the stored entry held
+            // with code is kept, with a warning, when saved unchanged; any other code is refused.
+            const { mdxAllow } = ctx.services.config;
+            const unsafe = findMarkdownSafetyIssues(fields, body.format, dataForValidation, mdxAllow);
+            if (unsafe.length > 0) {
+                const stored = exists
+                    ? await storedMarkdownSafetyIssues(store, schemaItem.logicalPath, slug, fields, mdxAllow)
+                    : [];
+                const { refused, kept } = splitByStored(unsafe, stored);
+                fieldErrors.push(...refused);
+                for (const e of kept) {
+                    keptWarnings.push({
+                        level: 'warning',
+                        fieldPath: e.fieldPath,
+                        message: `holds content this field refuses, kept because the saved entry already had it: ${e.message}. Ask a developer to move it into a component, or to allow it.`,
+                    });
+                }
+            }
             // Reference existence (server-only: reads the content ID index). Editor
             // payloads may still carry resolved `{ id, ... }` objects from a prior
             // read, so collapse them to id strings before checking.
@@ -264,7 +341,25 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                 const idIndex = await store.idIndex();
                 const refValidator = new ReferenceValidator(idIndex, fields, (name) => store.resolveCollectionItem(name)?.logicalPath);
                 const refResult = await refValidator.validate(normalizeReferenceValues(fields, data));
-                fieldErrors.push(...refResult.errors.map((e) => ({ fieldPath: e.fieldPath, message: e.error })));
+                // A dangling id the file already holds in that field is kept with a warning, so an entry
+                // whose target was deleted stays saveable and the id survives; the production build is
+                // what fails on it. A dangling id this save introduces, or moves to a field of another name, is
+                // refused.
+                const storedSites = exists && refResult.errors.some((e) => e.dangling)
+                    ? await storedReferenceSites(store, schemaItem.logicalPath, slug, fields)
+                    : new Set();
+                for (const e of refResult.errors) {
+                    if (e.dangling && storedSites.has(referenceSite(e.fieldPath, e.id))) {
+                        keptWarnings.push({
+                            level: 'warning',
+                            fieldPath: e.fieldPath,
+                            message: `references a missing entry (${e.id}). It is kept as it was; repoint or clear it.`,
+                        });
+                    }
+                    else {
+                        fieldErrors.push({ fieldPath: e.fieldPath, message: e.error });
+                    }
+                }
             }
             if (fieldErrors.length > 0) {
                 return {
@@ -286,7 +381,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // Adopter save-time validation, run BEFORE the file is written: 'error' issues
     // refuse the save (e.g. a body that would break the site's production build),
     // 'warning' issues are returned alongside the successful write.
-    let validationWarnings;
+    let validationWarnings = keptWarnings.length > 0 ? keptWarnings : undefined;
     const validateEntry = ctx.services.config.validateEntry;
     // Collapse resolved reference objects back to bare ID strings before persisting (the reference
     // validator above gets its own copy). The editor's GET resolves references by default, so form
@@ -294,7 +389,13 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // left unnormalized, a save would freeze that snapshot into the file (resolution only
     // re-resolves plain ID strings), permanently severing the reference from its target. Idempotent:
     // a payload that already holds ID strings is unchanged.
-    const normalizedData = body.data === undefined ? undefined : normalizeReferenceValues(fields, body.data);
+    //
+    // Every list item and block leaves a save keyed (`item-keys.ts`). A key sent is kept, so a
+    // thread naming it still finds its item; one missing is filled from the item's content, as a
+    // read fills one.
+    const normalizedData = requestData === undefined
+        ? undefined
+        : withItemKeys(fields, normalizeReferenceValues(fields, requestData), 'content');
     // Computed before the validateEntry hook and the entry-link scan too, not just the write, so
     // every consumer agrees on the same bytes — otherwise an adopter's hook could see a resolved
     // object while the file got an ID string, depending on whether the post came from the editor.
@@ -313,6 +414,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             const overflow = unknownKeys.length - shown.length;
             const list = overflow > 0 ? `${shown.join(', ')} (and ${overflow} more)` : shown.join(', ');
             validationWarnings = [
+                ...(validationWarnings ?? []),
                 {
                     level: 'warning',
                     message: `Saved. ${unknownKeys.length === 1 ? 'One field is' : `${unknownKeys.length} fields are`} ` +
@@ -328,7 +430,9 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             issues = await validateEntry({
                 entryPath: logicalPathSegments.join('/'),
                 branch: params.branch,
-                ...(params.entryType ? { entryType: params.entryType } : {}),
+                // The type the store writes with, so a request that omits `entryType` can't skip a
+                // type-gated rule.
+                ...(entryTypeName ? { entryType: entryTypeName } : {}),
                 format: body.format,
                 data: normalizedData ?? {},
                 body: body.body,
@@ -352,8 +456,8 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                     .join('; '),
             };
         }
-        // Appended, not assigned: the unknown-key scan above may already have found some, and the
-        // editor shows the channel as one notification.
+        // Appended, not assigned: the scans above may already have found some, and the editor shows
+        // the channel as one notification.
         const warnings = issues.filter((issue) => issue.level === 'warning');
         if (warnings.length > 0)
             validationWarnings = [...(validationWarnings ?? []), ...warnings];
@@ -398,7 +502,12 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             // refused outright, but a lock compromised mid-write can still land it — each case carries
             // its own message, so pass `err.message` through rather than the generic conflict below.
             if (err instanceof BranchSyncingError) {
-                return { ok: false, status: 409, error: err.message };
+                return {
+                    ok: false,
+                    status: 409,
+                    error: err.message,
+                    code: err.outcome === 'unknown' ? 'WRITE_OUTCOME_UNKNOWN' : 'BRANCH_SYNCING',
+                };
             }
             // [F1] Also not an editor collision: this content ID is quarantined on two files
             // (ContentIdIndex's duplicate-ID detection). The generic message below would send the
@@ -413,16 +522,15 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             if (err instanceof UrlPathConflictError) {
                 return { ok: false, status: 409, error: err.message };
             }
+            // Gone since the `exists` check above: deleted or moved between it and the in-lock open.
+            if (err instanceof EntryGoneError)
+                return entryGoneResponse();
             // Race-safe fallback: the early `exists` check above catches the common case; this covers a
-            // collision that lands between that check and store.write()'s in-lock stat.
+            // collision that lands between that check and store.write()'s in-lock open.
             if (expectedVersion === null) {
                 return { ok: false, status: 409, error: createConflictError };
             }
-            return {
-                ok: false,
-                status: 409,
-                error: 'Content conflict: entry was modified by another editor',
-            };
+            return { ok: false, status: 409, error: ENTRY_CHANGED_MESSAGE };
         }
         // C2: a ContentStoreError is an expected client fault (bad slug, validation, etc.) and keeps
         // its 400. Anything else — ENOSPC, EACCES, a bug — is a genuine server fault and must not be
@@ -542,7 +650,7 @@ const renameEntryHandler = async (gc, ctx, req, params, body) => {
             return {
                 ok: false,
                 status: 409,
-                error: passThrough ? err.message : 'Content conflict: entry was modified by another editor',
+                error: passThrough ? err.message : ENTRY_CHANGED_MESSAGE,
             };
         }
         // C2: same rule as writeContentHandler's catch above (ContentStoreError -> 400, everything
@@ -598,6 +706,7 @@ const validateReferences = defineEndpoint({
     namespace: 'content',
     name: 'validateReferences',
     method: 'POST',
+    readOnly: true,
     path: '/:branch/validate-references/...path',
     params: validateReferencesParamsSchema,
     body: validateReferencesBodySchema,

package/dist/api/entries-constants.d.ts

@@ -1,7 +1,7 @@
 /**
- * Pagination constants for the entries list endpoint. Kept dependency-free (no server-only
- * imports) so the editor's browser bundle can import the page-size cap without pulling in
- * `entries.ts` and its `node:fs`-backed deps; `entries.ts` re-exports these for API discoverability.
+ * Constants the entries and content endpoints share with the editor. Kept dependency-free (no
+ * server-only imports) so the editor's browser bundle can import them without pulling in
+ * `entries.ts` and its `node:fs`-backed deps.
  */
 /**
  * Maximum entries the list endpoint returns per request; larger `limit` values are clamped to
@@ -10,3 +10,14 @@
 export declare const MAX_ENTRIES_PER_PAGE = 200;
 /** Default page size when a request omits `limit`. */
 export declare const DEFAULT_ENTRIES_LIMIT = 50;
+/**
+ * The generic 409 for a conflicting change to an entry, usually its version moving on since the
+ * caller read it. Shared with the editor, whose own pre-save staleness check reports the same.
+ */
+export declare const ENTRY_CHANGED_MESSAGE = "This entry changed since you opened it. Choose \"Refresh from server\" to see the latest version (your unsaved edits will be lost).";
+/**
+ * The 409 for an update whose entry is gone: deleted or moved since the caller read it (API code
+ * `ENTRY_GONE`). The save is refused rather than re-creating the entry; re-creating it is a create
+ * the caller makes deliberately.
+ */
+export declare const ENTRY_GONE_MESSAGE = "This entry was deleted or moved since you opened it, so your changes were not saved.";

package/dist/api/entries-constants.js

@@ -1,7 +1,7 @@
 /**
- * Pagination constants for the entries list endpoint. Kept dependency-free (no server-only
- * imports) so the editor's browser bundle can import the page-size cap without pulling in
- * `entries.ts` and its `node:fs`-backed deps; `entries.ts` re-exports these for API discoverability.
+ * Constants the entries and content endpoints share with the editor. Kept dependency-free (no
+ * server-only imports) so the editor's browser bundle can import them without pulling in
+ * `entries.ts` and its `node:fs`-backed deps.
  */
 /**
  * Maximum entries the list endpoint returns per request; larger `limit` values are clamped to
@@ -10,3 +10,14 @@
 export const MAX_ENTRIES_PER_PAGE = 200;
 /** Default page size when a request omits `limit`. */
 export const DEFAULT_ENTRIES_LIMIT = 50;
+/**
+ * The generic 409 for a conflicting change to an entry, usually its version moving on since the
+ * caller read it. Shared with the editor, whose own pre-save staleness check reports the same.
+ */
+export const ENTRY_CHANGED_MESSAGE = 'This entry changed since you opened it. Choose "Refresh from server" to see the latest version (your unsaved edits will be lost).';
+/**
+ * The 409 for an update whose entry is gone: deleted or moved since the caller read it (API code
+ * `ENTRY_GONE`). The save is refused rather than re-creating the entry; re-creating it is a create
+ * the caller makes deliberately.
+ */
+export const ENTRY_GONE_MESSAGE = 'This entry was deleted or moved since you opened it, so your changes were not saved.';