canopycms 0.12.0 → 0.13.0

package/dist/api/branch-update-from-base.js

@@ -0,0 +1,227 @@
+import { branchParamSchema } from './validators.js';
+import { toBranchListItem } from './branch.js';
+import { defineEndpoint } from './route-builder.js';
+import { canPerformWorkflowAction, getBranchProtection } from '../authorization/index.js';
+import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
+import { clientOperatingStrategy, operatingStrategy } from '../operating-mode/index.js';
+import { enqueueTask, listTasks } from '../task-queue/cms-task-queue.js';
+import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
+import { BASE_UPDATE_GIVE_UP_MS, BASE_UPDATE_REQUEST_INTERVAL_MS, SYNC_BRANCH_ACTION, isBaseUpdatePending, } from '../base-update.js';
+import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
+import { getErrorMessage, redactCredentials } from '../utils/error.js';
+import { baseBranchOf } from '../utils/base-branch.js';
+/**
+ * Ask the worker to bring the base branch into this one now, rather than at its next sync
+ * (base-update.ts). Saved work is committed first, locally: the sync skips a branch with
+ * uncommitted changes, so without the commit the request would do nothing.
+ *
+ * The request is recorded on branch.json, which is what the worker answers, so a lost task or a
+ * worker restart costs only the wait for its next regular cycle. The task only wakes it early.
+ * Where the mode runs no worker loop (operating-mode `baseUpdateRunsInRequest`), a new request runs
+ * the worker's merge itself and is answered before the response; one it joins is answered by the
+ * run that made it.
+ * A request joins the last one, answering with its time: while that is unanswered, under
+ * BASE_UPDATE_GIVE_UP_MS old and either under BASE_UPDATE_REQUEST_INTERVAL_MS old or still queued;
+ * or once it was answered under BASE_UPDATE_REQUEST_INTERVAL_MS ago without failing. Anything
+ * else, a Retry after a failure among them, is a new request.
+ */
+const updateFromBaseHandler = async (gc, ctx, req, _params) => {
+    const { branchContext } = gc;
+    const { config } = ctx.services;
+    const { branch } = branchContext;
+    const runsInRequest = operatingStrategy(config.mode).baseUpdateRunsInRequest();
+    if (!clientOperatingStrategy(config.mode).syncsBranchesWithBase()) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Getting the latest changes needs the CMS worker, which ${config.mode} mode doesn't run.`,
+        };
+    }
+    const { isProtected } = getBranchProtection(config, branch.name, branch.baseBranch);
+    const allowed = canPerformWorkflowAction(branchContext, req.user, config.defaultBranchAccess ?? 'deny', { isProtectedBranch: isProtected });
+    if (!allowed) {
+        return {
+            ok: false,
+            status: 403,
+            error: 'You do not have permission to get the latest changes for this branch.',
+        };
+    }
+    if (isProtected) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'This branch is the one changes come from, so it has no latest changes to get.',
+        };
+    }
+    // Only an editing branch takes the base in; the worker leaves the others as they are.
+    if (branch.status !== 'editing') {
+        return {
+            ok: false,
+            status: 409,
+            error: branch.status === 'submitted' || branch.status === 'approved'
+                ? 'This branch is in review. Withdraw it from review to get the latest changes.'
+                : "This branch can't be edited, so it can't get the latest changes.",
+        };
+    }
+    const base = branch.baseBranch ?? baseBranchOf(config);
+    const { authPlugin } = ctx;
+    try {
+        await ctx.services.commitSavedWork({
+            context: branchContext,
+            message: `Save changes before getting the latest from ${base}`,
+            lookupEditor: authPlugin ? (id) => authPlugin.getUserMetadata(id) : undefined,
+        });
+    }
+    catch (err) {
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? 'This branch is being synced, or a save is in progress. Nothing changed; try again in a moment.'
+                    : "This branch was being synced while your saved work was prepared, so the latest changes weren't requested. Try again.",
+            };
+        }
+        console.error(`CanopyCMS: Could not commit the saved changes of ${branch.name} before getting the latest:`, redactCredentials(getErrorMessage(err)));
+        return {
+            ok: false,
+            status: 500,
+            error: "Your saved changes couldn't be prepared, so the latest changes weren't requested.",
+        };
+    }
+    const taskDir = getTaskQueueDir(config);
+    const queued = !runsInRequest &&
+        (await listTasks(taskDir, 'pending', Number.MAX_SAFE_INTEGER)).some((t) => t.action === SYNC_BRANCH_ACTION && t.payload.branch === branch.name);
+    const now = Date.now();
+    let requestedAt = new Date(now).toISOString();
+    let joined = false;
+    let leftEditing;
+    const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
+    const saved = await meta.update((existing) => {
+        if (existing?.branch.name !== branch.name)
+            return null;
+        // A submit since the guard read: the worker would leave the request standing until a withdraw.
+        if (existing.branch.status !== 'editing') {
+            leftEditing = existing.branch.status;
+            return null;
+        }
+        const last = existing.branch.baseUpdateRequestedAt;
+        const age = last === undefined ? Infinity : now - Date.parse(last);
+        const answer = existing.branch.lastBaseUpdate;
+        const pending = isBaseUpdatePending(existing.branch);
+        // An unanswered request is joined until the editor stops waiting on it. An answer under the
+        // interval old stands for a new click too, except a failure, whose Retry must ask again, and
+        // except where the request runs the merge itself, which costs no worker cycle.
+        const joinsPending = pending && age < BASE_UPDATE_GIVE_UP_MS && (queued || age < BASE_UPDATE_REQUEST_INTERVAL_MS);
+        const answeredRecently = !runsInRequest &&
+            !pending &&
+            answer !== undefined &&
+            answer.outcome !== 'failed' &&
+            now - Date.parse(answer.at) < BASE_UPDATE_REQUEST_INTERVAL_MS;
+        if (last !== undefined && (joinsPending || answeredRecently)) {
+            requestedAt = last;
+            joined = true;
+            return null;
+        }
+        return { branch: { baseUpdateRequestedAt: requestedAt } };
+    }, { keepUpdatedAt: true });
+    if (leftEditing) {
+        return {
+            ok: false,
+            status: 409,
+            error: leftEditing === 'submitted' || leftEditing === 'approved'
+                ? 'This branch is in review. Withdraw it from review to get the latest changes.'
+                : "This branch can't be edited, so it can't get the latest changes.",
+        };
+    }
+    let current = saved ?? (await BranchMetadataFileManager.loadOnly(branchContext.branchRoot));
+    if (current?.branch.name !== branch.name) {
+        return { ok: false, status: 404, error: 'This branch no longer exists.' };
+    }
+    // A joined request is answered by the run that made it.
+    if (runsInRequest && !joined) {
+        // Answered here where the run couldn't, as nothing else would: an open request holds the form
+        // read-only.
+        const answerFailed = () => meta
+            .update((existing) => existing?.branch.name === branch.name &&
+            existing.branch.baseUpdateRequestedAt === requestedAt &&
+            isBaseUpdatePending(existing.branch)
+            ? { branch: { lastBaseUpdate: { at: requestedAt, outcome: 'failed' } } }
+            : null, { keepUpdatedAt: true })
+            .catch(() => undefined);
+        let run;
+        try {
+            run = await ctx.services.runBaseUpdateNow(branchContext);
+        }
+        catch (err) {
+            console.error(`CanopyCMS: Could not bring the latest changes into ${branch.name}:`, redactCredentials(getErrorMessage(err)));
+            await answerFailed();
+            return {
+                ok: false,
+                status: 500,
+                error: "The latest changes couldn't be added. Your work is safe.",
+            };
+        }
+        if (run === 'other-remote') {
+            await answerFailed();
+            return {
+                ok: false,
+                status: 409,
+                error: "This branch uses a git remote other than the local one, so its latest changes can't be brought in here.",
+            };
+        }
+        if (run === 'busy') {
+            return {
+                ok: false,
+                status: 409,
+                error: "This branch is busy with a save or another update, so the latest changes weren't added. Try again in a moment.",
+            };
+        }
+        current = await BranchMetadataFileManager.loadOnly(branchContext.branchRoot);
+        if (current?.branch.name !== branch.name) {
+            return { ok: false, status: 404, error: 'This branch no longer exists.' };
+        }
+    }
+    // A wake-up already queued serves the new request too.
+    if (!runsInRequest && !joined && !queued) {
+        try {
+            await enqueueTask(taskDir, { action: SYNC_BRANCH_ACTION, payload: { branch: branch.name } });
+        }
+        catch (err) {
+            // The worker's next regular sync answers the recorded request anyway, only later.
+            console.warn(`CanopyCMS: Could not queue the request for the latest changes on ${branch.name}:`, getErrorMessage(err));
+        }
+    }
+    return {
+        ok: true,
+        status: 202,
+        data: { requestedAt, branch: toBranchListItem(config, current.branch, req.user) },
+    };
+};
+/** Get the latest changes: bring the base branch into this one at the worker's next chance. */
+export const updateFromBase = defineEndpoint({
+    namespace: 'workflow',
+    name: 'updateFromBase',
+    // Commits saved work on the shared filesystem before answering.
+    clientTimeout: 'long',
+    method: 'POST',
+    path: '/:branch/update-from-base',
+    params: branchParamSchema,
+    responseType: 'UpdateFromBaseResponse',
+    response: {},
+    defaultMockData: {
+        requestedAt: '2024-01-01T00:00:00.000Z',
+        branch: {
+            name: 'test-branch',
+            status: 'editing',
+            access: {},
+            createdBy: 'user-1',
+            createdAt: '2024-01-01',
+            updatedAt: '2024-01-01',
+            baseUpdateRequestedAt: '2024-01-01T00:00:00.000Z',
+        },
+    },
+    // As Withdraw: the handler's canPerformWorkflowAction decides who may ask.
+    guards: ['branch'],
+    handler: updateFromBaseHandler,
+});

package/dist/api/branch.d.ts

@@ -60,6 +60,11 @@ export interface BranchListItem extends Omit<BranchMetadata, 'review' | 'keptOve
         users: number;
         groups: number;
     };
+    /**
+     * The commit a branch in review held when it was listed, which Approve and Request changes send
+     * back to say what the reviewer saw (api/branch-review.ts). Only on a listing.
+     */
+    headSha?: string;
 }
 /**
  * Response type for branch creation and the workflow transitions. Carries the
@@ -82,6 +87,11 @@ export type BranchListResponse = ApiResponse<{
     defaultBranch?: string;
     /** Profiles of the listed branches' creators, in no order; unknown ids are absent. */
     users: UserProfile[];
+    /**
+     * The server's clock as it answered, in ms since the epoch, so the editor times a wait for the
+     * latest changes against the clock that stamped the request rather than the browser's.
+     */
+    serverTime?: number;
 }>;
 /** Response type for branch deletion */
 export type BranchDeleteResponse = ApiResponse<{

package/dist/api/branch.js

@@ -11,7 +11,7 @@ import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { DELETE_NEEDS_ADMIN_REASON } from '../editor/copy.js';
 import { getErrorMessage } from '../utils/error.js';
 import { filePathExists } from '../utils/fs.js';
-import { isNetworkRemoteUrl } from '../utils/git.js';
+import { isNetworkRemoteUrl, readHeadCommitFromFiles } from '../utils/git.js';
 import { parseCreatedBranchName, sanitizeBranchName, isSettingsBranchName } from '../paths/index.js';
 import { GitManager } from '../git-manager.js';
 import { syncDeleteRemoteBranch } from './github-sync.js';
@@ -521,16 +521,42 @@ const branchListResponse = async (ctx, req, branches, defaultBranch) => {
             console.error('CanopyCMS: Failed to look up branch owners:', getErrorMessage(error));
         }
     }
+    const heads = await Promise.all(branches.map((context) => reviewedHead(ctx, context)));
     return {
         ok: true,
         status: 200,
         data: {
-            branches: branches.map((context) => toBranchListItem(ctx.services.config, context.branch, req.user)),
+            branches: branches.map((context, i) => {
+                const item = toBranchListItem(ctx.services.config, context.branch, req.user);
+                const headSha = heads[i];
+                return headSha ? { ...item, headSha } : item;
+            }),
             defaultBranch,
             users,
+            serverTime: Date.now(),
         },
     };
 };
+/**
+ * A branch in review's head commit, from the clone's files, so a listing of many spawns no git;
+ * git reads only a layout the files can't answer. Undefined when unreadable: the editor then has
+ * nothing to send, and the review is refused until a listing reads it.
+ */
+const reviewedHead = async (ctx, { branch, branchRoot }) => {
+    if (branch.status !== 'submitted' && branch.status !== 'approved')
+        return undefined;
+    try {
+        const fromFiles = await readHeadCommitFromFiles(branchRoot);
+        if (fromFiles)
+            return fromFiles;
+        const git = ctx.services.createGitManagerFor(branchRoot, { baseBranch: branch.baseBranch });
+        return await git.headSha();
+    }
+    catch (err) {
+        console.error(`CanopyCMS: Could not read the head of ${branch.name}:`, getErrorMessage(err));
+        return undefined;
+    }
+};
 /** A person's delete, as deletion by age never does, can take commits only the branch still has. */
 const mayHoldLostCommits = (branch) => branch.unpublishedAtMerge === true ||
     (branch.status === 'archived' && branch.rewrittenOnGitHub !== undefined);

package/dist/api/client.d.ts

@@ -11,7 +11,8 @@ import type { OperatingMode } from '../operating-mode/types.js';
 import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
 import type { BranchChangesResponse } from './branch-changes.js';
 import type { BranchEntryChangeResponse, RestoreEntryBody, RestoreEntryResponse } from './branch-entry-changes.js';
-import type { BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse } from './branch-status.js';
+import type { EntryConflictResponse, MergeConflictsResponse, ReleaseConflictsHoldResponse, ResolveEntryConflictBody, ResolveEntryConflictResponse } from './merge-conflicts.js';
+import type { ApproveBody, BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse, UpdateFromBaseResponse } from './branch-status.js';
 import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, DeleteArchivedBranchesBody, DeleteArchivedBranchesResponse, DismissUnpublishedResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
 import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResponse, RenameEntryBody, RenameEntryResponse, ValidateReferencesBody, WriteContentBody } from './content.js';
@@ -95,13 +96,25 @@ export declare class CanopyApiClient {
         /** POST /:branch/restore-entry/...entryPath */
         restore: (params: Record<string, string>, body: RestoreEntryBody, options?: RequestOptions) => Promise<RestoreEntryResponse>;
     };
+    readonly conflicts: {
+        /** GET /:branch/conflicts */
+        list: (params: Record<string, string>, options?: RequestOptions) => Promise<MergeConflictsResponse>;
+        /** GET /:branch/conflicts/...entryPath */
+        entry: (params: Record<string, string>, options?: RequestOptions) => Promise<EntryConflictResponse>;
+        /** POST /:branch/resolve-entry/...entryPath */
+        resolveEntry: (params: Record<string, string>, body: ResolveEntryConflictBody, options?: RequestOptions) => Promise<ResolveEntryConflictResponse>;
+        /** POST /:branch/conflicts/release-hold */
+        releaseHold: (params: Record<string, string>, options?: RequestOptions) => Promise<ReleaseConflictsHoldResponse>;
+    };
     readonly workflow: {
         /** POST /:branch/withdraw */
         withdraw: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
+        /** POST /:branch/update-from-base */
+        updateFromBase: (params: Record<string, string>, options?: RequestOptions) => Promise<UpdateFromBaseResponse>;
         /** POST /:branch/request-changes */
         requestChanges: (params: Record<string, string>, body: RequestChangesBody, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/approve */
-        approve: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
+        approve: (params: Record<string, string>, body: ApproveBody, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/mark-merged */
         markMerged: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchMergeResponse>;
         /** POST /:branch/archive */

package/dist/api/client.js

@@ -55,18 +55,40 @@ export class CanopyApiClient {
                 return this.request('POST', this.buildPath('/:branch/restore-entry/...entryPath', params), body, 'standard', options);
             },
         };
+        this.conflicts = {
+            /** GET /:branch/conflicts */
+            list: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/conflicts', params), undefined, 'standard', options);
+            },
+            /** GET /:branch/conflicts/...entryPath */
+            entry: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/conflicts/...entryPath', params), undefined, 'standard', options);
+            },
+            /** POST /:branch/resolve-entry/...entryPath */
+            resolveEntry: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/resolve-entry/...entryPath', params), body, 'standard', options);
+            },
+            /** POST /:branch/conflicts/release-hold */
+            releaseHold: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/conflicts/release-hold', params), undefined, 'standard', options);
+            },
+        };
         this.workflow = {
             /** POST /:branch/withdraw */
             withdraw: (params, options) => {
                 return this.request('POST', this.buildPath('/:branch/withdraw', params), undefined, 'standard', options);
             },
+            /** POST /:branch/update-from-base */
+            updateFromBase: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/update-from-base', params), undefined, 'long', options);
+            },
             /** POST /:branch/request-changes */
             requestChanges: (params, body, options) => {
                 return this.request('POST', this.buildPath('/:branch/request-changes', params), body, 'standard', options);
             },
             /** POST /:branch/approve */
-            approve: (params, options) => {
-                return this.request('POST', this.buildPath('/:branch/approve', params), undefined, 'standard', options);
+            approve: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/approve', params), body, 'standard', options);
             },
             /** POST /:branch/mark-merged */
             markMerged: (params, options) => {

package/dist/api/comments.d.ts

@@ -60,16 +60,16 @@ export declare const COMMENT_ROUTES: {
     }, "strip", z.ZodTypeAny, {
         type: "branch" | "entry" | "field";
         text: string;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         itemKeys?: string[] | undefined;
-        entryPath?: LogicalPath | undefined;
         canopyPath?: string | undefined;
     }, {
         type: "branch" | "entry" | "field";
         text: string;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         itemKeys?: string[] | undefined;
-        entryPath?: LogicalPath | undefined;
         canopyPath?: string | undefined;
     }>, AddCommentResponse>;
     readonly resolve: import("./route-builder.js").RouteDefinition<z.ZodObject<{

package/dist/api/content.d.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-import type { EntryValidationIssue } from '../config/index.js';
+import type { ContentFormat, EntrySchema, EntryValidationIssue } from '../config/index.js';
 import { type LogicalPath, type Slug } from '../paths/index.js';
+import type { ResolvedFieldConflict } from '../merge-conflicts.js';
 export type ContentReadResponse = ApiResponse<{
     format: string;
     data: Record<string, unknown>;
@@ -22,6 +23,11 @@ export type ContentWriteResponse = ApiResponse<{
      * editor has exactly one save-warnings notification to render (useEntryManager.ts).
      */
     validationWarnings?: EntryValidationIssue[];
+    /**
+     * Of the `resolvedConflicts` sent with an update, the ones this save cleared: one sent but not
+     * here was stale, unless a warning says the choice wasn't recorded.
+     */
+    resolvedConflicts?: ResolvedFieldConflict[];
 }>;
 export type ReferenceValidationResponse = ApiResponse<{
     valid: boolean;
@@ -48,6 +54,13 @@ export interface WriteContentBody {
      * from "lost the token", so an update has to prove which version it read.
      */
     expectedVersion?: number | null;
+    /**
+     * Field conflicts a merge left on this entry that the saved values resolve, each named as
+     * `GET /:branch/conflicts/...entryPath` names it. Cleared once the entry is written, under the
+     * save's locks; a pair the record no longer holds is ignored. A save that leaves a conflicting
+     * field out leaves its conflict open.
+     */
+    resolvedConflicts?: ResolvedFieldConflict[];
 }
 export interface ValidateReferencesBody {
     data: Record<string, unknown>;
@@ -55,6 +68,12 @@ export interface ValidateReferencesBody {
 export interface RenameEntryBody {
     newSlug: string;
 }
+/**
+ * What a save writes for `data`, an entry's form data: an md/mdx file's body-field key dropped
+ * (that field is the file's body), references collapsed to IDs, and every list item and block
+ * keyed. `backfill-item-keys` writes through this too, so its files are a save's.
+ */
+export declare function entryDataAsSaved(fields: EntrySchema, format: ContentFormat, data: Record<string, unknown>): Record<string, unknown>;
 /**
  * Exported routes for router registration
  */
@@ -102,16 +121,34 @@ export declare const CONTENT_ROUTES: {
         data: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>;
         body: z.ZodOptional<z.ZodString>;
         expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        resolvedConflicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            mergeSha: z.ZodString;
+            key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            key: string;
+            mergeSha: string;
+        }, {
+            key: string;
+            mergeSha: string;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         format: "md" | "mdx" | "json" | "yaml";
         data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
+        resolvedConflicts?: {
+            key: string;
+            mergeSha: string;
+        }[] | undefined;
     }, {
         format: "md" | "mdx" | "json" | "yaml";
         data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
+        resolvedConflicts?: {
+            key: string;
+            mergeSha: string;
+        }[] | 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>;

package/dist/api/content.js

@@ -14,6 +14,8 @@ import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils
 import { isDataOnlyFormat } from '../utils/format.js';
 import { withItemKeys } from '../item-keys.js';
 import { findBodyFieldName } from '../utils/body-field.js';
+import { canopyLogWarn } from '../utils/logger.js';
+import { clearFieldConflicts, resolvedConflictsSchema } from './merge-conflicts.js';
 /**
  * Parse an API path into logical path segments, prepending the content root if needed.
  * Shared by all content API handlers.
@@ -60,6 +62,7 @@ const writeContentBodySchema = z.object({
     body: z.string().max(MAX_CONTENT_BODY_CHARS).optional(),
     // null or omitted = create ("must not already exist"); see WriteContentBody.
     expectedVersion: z.number().nullish(),
+    resolvedConflicts: resolvedConflictsSchema.optional(),
 });
 const validateReferencesParamsSchema = z.object({
     branch: branchNameSchema,
@@ -133,6 +136,15 @@ function withoutKey(record, key) {
     const { [key]: _dropped, ...rest } = record;
     return rest;
 }
+/**
+ * What a save writes for `data`, an entry's form data: an md/mdx file's body-field key dropped
+ * (that field is the file's body), references collapsed to IDs, and every list item and block
+ * keyed. `backfill-item-keys` writes through this too, so its files are a save's.
+ */
+export function entryDataAsSaved(fields, format, data) {
+    const own = isDataOnlyFormat(format) ? data : withoutKey(data, findBodyFieldName(fields));
+    return withItemKeys(fields, normalizeReferenceValues(fields, own), 'content');
+}
 /** 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.
@@ -393,9 +405,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // 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');
+    const normalizedData = requestData === undefined ? undefined : entryDataAsSaved(fields, body.format, requestData);
     // 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.
@@ -475,10 +485,32 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                 body: body.body ?? '',
                 expectedVersion,
             };
+        // Under the write's own locks, so no merge records a conflict between the value written and
+        // the record cleared. A failure to clear keeps the save: the conflict stays open, and says so.
+        let resolvedConflicts;
+        const resolving = expectedVersion === null ? [] : (body.resolvedConflicts ?? []);
+        const afterWrite = async ({ id }) => {
+            if (!id || resolving.length === 0)
+                return;
+            try {
+                resolvedConflicts = await clearFieldConflicts(ctx.services.config, branchContext, id, resolving);
+            }
+            catch (err) {
+                canopyLogWarn(`CanopyCMS: saved ${logicalPathSegments.join('/')} but couldn't mark its conflicts resolved:`, getErrorMessage(err));
+                resolvedConflicts = [];
+                validationWarnings = [
+                    ...(validationWarnings ?? []),
+                    {
+                        level: 'warning',
+                        message: 'Saved, but your choice for its conflicting changes wasn’t recorded. Choose again, then save.',
+                    },
+                ];
+            }
+        };
         // Pass the resolved entryTypeName (not the raw, possibly-omitted
         // params.entryType) so the store's own format check agrees with the type
         // we just validated against.
-        const result = await store.write(schemaItem.logicalPath, slug, writeInput, entryTypeName);
+        const result = await store.write(schemaItem.logicalPath, slug, writeInput, entryTypeName, undefined, { afterWrite });
         // Validate entry links in body content (warnings only, don't block save).
         // Reuses the entry-type fields resolved above for schema validation. Folded into
         // `validationWarnings` (not a separate `entryLinkWarnings` field) so the editor's one
@@ -494,7 +526,11 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             }));
             validationWarnings = [...(validationWarnings ?? []), ...linkWarnings];
         }
-        return { ok: true, status: 200, data: { ...result, validationWarnings } };
+        return {
+            ok: true,
+            status: 200,
+            data: { ...result, validationWarnings, ...(resolvedConflicts && { resolvedConflicts }) },
+        };
     }
     catch (err) {
         if (err instanceof ContentConflictError) {