@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/content/actions/sync-local-folder-source.ts

@@ -24,7 +24,10 @@ import { setFavoriteMembership } from "./_content-favorites.js";
 import { ensureDocumentsFilesMembership } from "./_content-files.js";
 import { resolveContentSpaceAccess } from "./_content-space-access.js";
 import { provisionContentSpaces } from "./_content-spaces.js";
-import { lockDatabaseMemberships } from "./_database-membership-lock.js";
+import {
+  lockDatabaseMemberships,
+  lockExistingDatabaseMemberships,
+} from "./_database-membership-lock.js";
 import {
   LOCAL_FOLDER_SOURCE_TYPE,
   localFolderObservedRevision,
@@ -32,6 +35,7 @@ import {
   localFolderSourceIdentityFromMetadata,
   normalizeLocalFolderSourceIdentity,
 } from "./_local-folder-source.js";
+import { lockDocumentRows } from "./_row-lock-order.js";
 
 const MAX_SOURCE_FILES = 500;
 const MAX_SOURCE_FILE_BYTES = 2 * 1024 * 1024;
@@ -517,6 +521,36 @@ export default defineAction({
           (row) => !currentDocumentIds.has(row.documentId),
         );
         classifyPlans(transactionSnapshot);
+        // The pages' Files memberships, then the pages, each by id, as a save
+        // takes them: the writes below update pages before the memberships.
+        const existingPageIds = plans
+          .filter((plan) => !plan.conflict && plan.existing)
+          .map((plan) => plan.id);
+        const writtenPageIds = [
+          ...existingPageIds,
+          ...missingRows.map((row) => row.documentId),
+        ];
+        // Add a missing Files membership before locking any page. A page has
+        // one per Files database, so once this transaction holds or inserts
+        // it, a concurrent insert waits on this one; if it were added after
+        // the pages, the later membership lock would wait on its writer.
+        await ensureDocumentsFilesMembership(tx, existingPageIds, now);
+        if (writtenPageIds.length > 0) {
+          const memberships = await tx
+            .select({ id: schema.contentDatabaseItems.id })
+            .from(schema.contentDatabaseItems)
+            .where(
+              and(
+                eq(schema.contentDatabaseItems.databaseId, target.database.id),
+                inArray(schema.contentDatabaseItems.documentId, writtenPageIds),
+              ),
+            );
+          await lockExistingDatabaseMemberships(tx, [
+            ...memberships.map((membership: { id: string }) => membership.id),
+            ...missingRows.map((row) => row.databaseItemId),
+          ]);
+          await lockDocumentRows(tx, writtenPageIds);
+        }
         for (const plan of plans) {
           if (plan.conflict) {
             const changeSetId = opaqueId(

package/corpus/templates/content/actions/undo-content-import.ts

@@ -13,10 +13,7 @@ import { importedStateFingerprint } from "../server/lib/content-import.js";
 import { requireDocumentRequestActor } from "../server/lib/document-attribution.js";
 import { flushOpenDocumentEditorToSql } from "./_document-flush.js";
 import { assertDocumentMutationAccess } from "./_document-mutation-access.js";
-import {
-  lockDatabasesForTrash,
-  trashDocumentSubtree,
-} from "./delete-document.js";
+import { lockLifecycleGroup, trashDocumentSubtree } from "./delete-document.js";
 
 export default defineAction({
   description:
@@ -90,6 +87,19 @@ export default defineAction({
         );
       }
       const importedIds = new Set(records.map((record) => record.documentId));
+      // Collections before pages: every imported page and its subtree, in
+      // the one row-lock order Trash and restore use.
+      const owners = await tx
+        .select({
+          id: schema.documents.id,
+          ownerEmail: schema.documents.ownerEmail,
+        })
+        .from(schema.documents)
+        .where(inArray(schema.documents.id, [...importedIds]));
+      const locks = await lockLifecycleGroup(tx, {
+        operation: "trash",
+        roots: owners,
+      });
       const current = await tx
         .select({
           id: schema.documents.id,
@@ -104,8 +114,7 @@ export default defineAction({
           trashedAt: schema.documents.trashedAt,
         })
         .from(schema.documents)
-        .where(inArray(schema.documents.id, [...importedIds]))
-        .for("update");
+        .where(inArray(schema.documents.id, [...importedIds]));
       const collections = await tx
         .select({ documentId: schema.contentDatabases.documentId })
         .from(schema.contentDatabases)
@@ -133,17 +142,12 @@ export default defineAction({
         if (changed.includes(page)) continue;
         // The page's owner now, not at import: moving a page between
         // workspaces makes the mover its owner.
-        const lockedDatabaseIds = await lockDatabasesForTrash(
-          tx,
-          page.id,
-          page.ownerEmail,
-        );
         const subtree = await trashDocumentSubtree(
           tx,
           page.id,
           page.ownerEmail,
           undefined,
-          lockedDatabaseIds,
+          locks,
           ctx?.caller,
         );
         if (!subtree.includes(page.id)) {

package/corpus/templates/content/actions/update-content-database-view.ts

@@ -47,6 +47,8 @@ const filterSchema = z
     value: z.string(),
     filterGroupId: z.string().optional(),
     parentFilterGroupId: z.string().optional(),
+    filterGroupMode: z.enum(["and", "or"]).optional(),
+    parentFilterGroupMode: z.enum(["and", "or"]).optional(),
   })
   .strict();
 

package/corpus/templates/content/actions/update-document.ts

@@ -5,6 +5,7 @@ import { defineAction, type ActionRunContext } from "@agent-native/core/action";
 import { writeAppState } from "@agent-native/core/application-state";
 import { withCommittedActionAudit } from "@agent-native/core/audit";
 import { agentTouchDocument } from "@agent-native/core/collab";
+import { getDbExec } from "@agent-native/core/db";
 import {
   iconValueSchema,
   parseIconValue,
@@ -42,22 +43,27 @@ import {
 } from "../server/lib/document-body-intents.js";
 import { documentChangeResource } from "../server/lib/document-change-resource.js";
 import { recordDocumentHistoryTransition } from "../server/lib/document-history.js";
-import {
-  lockDocumentMetadataDatabase,
-  nextDocumentMetadataUpdatedAt,
-} from "../server/lib/document-metadata-updated-at.js";
+import { nextDocumentMetadataUpdatedAt } from "../server/lib/document-metadata-updated-at.js";
 import { propagateDocumentTitle } from "../server/lib/document-title-propagation.js";
 import { nextDocumentUpdatedAt } from "../server/lib/document-updated-at.js";
 import {
   parseDocumentFavorite,
   parseDocumentHideFromSearch,
 } from "../server/lib/documents.js";
+import {
+  liveBodyWriterGateForRow,
+  liveBodyWriterPageColumns,
+} from "../server/lib/live-body-writer.js";
 import {
   syncPrivateCalloutReferences,
   syncPrivateIconReference,
   verifyPrivateIconAssignment,
 } from "../server/lib/private-icon-references.js";
-import type { DocumentUpdateResponse } from "../shared/api.js";
+import { liveCopyHoldsSave } from "../server/live-copy/holds.js";
+import type {
+  DocumentUpdateResponse,
+  LiveCopyBodySave,
+} from "../shared/api.js";
 import { applyContentPersonalNavigationPatch } from "../shared/content-personal-navigation-patch.js";
 import { mergeDocumentBodyIntents } from "../shared/document-intent-merge.js";
 import { inspectNfmFidelity } from "../shared/nfm.js";
@@ -91,6 +97,7 @@ import {
 import { listContentOrganizationMemberships } from "./_content-space-access.js";
 import { provisionContentSpaces } from "./_content-spaces.js";
 import {
+  assertEditableDocument,
   documentContentHash,
   documentRevisionToken,
   parseDocumentRevisionToken,
@@ -99,6 +106,7 @@ import {
   assertDocumentMutationAccess,
   resolveDocumentAccessForMutation,
 } from "./_document-mutation-access.js";
+import { lockDocumentForSave } from "./_document-save-locks.js";
 import {
   assertSourceAllowsPageEdit,
   serializeDocumentSource,
@@ -207,6 +215,13 @@ function documentUpdateResponse(
     source: serializeDocumentSource(doc),
     softDeletedDatabaseIds,
     ...(browserSaveAttempt ? { browserSaveAttempt } : {}),
+    // Only a save the live copy holds keeps a receipt.
+    ...(browserSaveAttempt?.bodySave
+      ? {
+          bodySave: browserSaveAttempt.bodySave,
+          bodyIntentOutcome: { status: "applied" as const },
+        }
+      : {}),
   };
 }
 
@@ -955,6 +970,7 @@ const updateDocumentAction = defineAction({
           );
         }
       }
+      if (!favoriteOnly) assertEditableDocument(existing);
 
       const normalizeAuthoredContent = (value: string) => {
         if (args.preserveLeadingTitleHeading) return value;
@@ -974,7 +990,7 @@ const updateDocumentAction = defineAction({
         args.authoredCandidateContent === undefined
           ? undefined
           : normalizeAuthoredContent(args.authoredCandidateContent);
-      let browserSaveContentRejected = false;
+      let staleBodySave: "stale_builder_image" | "stale_empty_body" | undefined;
       if (content !== undefined && !args.preserveLeadingTitleHeading) {
         if (
           content.includes('componentName="Image"') &&
@@ -1012,12 +1028,11 @@ const updateDocumentAction = defineAction({
               sourceContent,
             })
           ) {
-            browserSaveContentRejected = true;
-            measurement.reason_code = "stale_builder_image";
-            content = existing.content;
+            staleBodySave = "stale_builder_image";
           }
         }
         if (
+          !staleBodySave &&
           shouldRejectStaleEmptyBodySave({
             incomingContent: content,
             currentContent: existing.content,
@@ -1026,13 +1041,26 @@ const updateDocumentAction = defineAction({
             loadedContentWasEmpty: args.loadedContentWasEmpty,
           })
         ) {
-          browserSaveContentRejected = true;
-          measurement.stale_base = "true";
-          measurement.reason_code = "stale_empty_body";
-          content = existing.content;
+          staleBodySave = "stale_empty_body";
         }
       }
-      if (browserSaveContentRejected && args.browserSaveAttemptId) {
+      // These guard a body write, and a switched page's body may not be
+      // written here at all: the gate, read under the page lock, decides.
+      const staleBodySaveDeferred =
+        ctx?.caller === "frontend" && !!existing.liveBodySwitchedAt;
+      /** Keeps the stored body; true when the save must answer a conflict. */
+      const refuseStaleBodySave = (storedContent: string) => {
+        measurement.reason_code = staleBodySave;
+        if (staleBodySave === "stale_empty_body")
+          measurement.stale_base = "true";
+        content = storedContent;
+        return !!args.browserSaveAttemptId;
+      };
+      if (
+        staleBodySave &&
+        !staleBodySaveDeferred &&
+        refuseStaleBodySave(existing.content)
+      ) {
         measurement.outcome = "conflict";
         return respond(
           documentConflictResponse(existing, access.role, currentFavorite),
@@ -1072,6 +1100,11 @@ const updateDocumentAction = defineAction({
       let browserSaveConfirmation: BrowserSaveAttemptConfirmation | undefined;
       let bodyIntentOutcome: BrowserDocumentUpdateResponse["bodyIntentOutcome"];
       let discardedEditorGeneration: number | undefined;
+      let liveCopyBodySave: LiveCopyBodySave | undefined;
+      // Only a save the live copy already holds settles its draft or keeps a
+      // receipt. A tab whose updates never reached the live copy has nothing
+      // else on the server holding its text.
+      let settlesLiveCopyBody = false;
       let preservationRequired:
         | {
             reason: "structure" | "provenance";
@@ -1117,16 +1150,16 @@ const updateDocumentAction = defineAction({
         const mutate = async (tx: any) => {
           measurement.outcome = "unchanged";
           measurement.history_effect = "none";
-          const lockedDatabaseId = await lockDocumentMetadataDatabase({
-            db: tx as unknown as ReturnType<typeof getDb>,
-            documentId: id,
-            ownerEmail,
-          });
-          await tx
-            .select({ id: schema.documents.id })
-            .from(schema.documents)
-            .where(eq(schema.documents.id, id))
-            .for("update");
+          const mayWriteBody =
+            content !== undefined || authoredCandidateContent !== undefined;
+          const {
+            databaseId: lockedDatabaseId,
+            lockedDatabaseIds,
+            lockedMembershipIds,
+          } = await lockDocumentForSave(
+            tx as unknown as ReturnType<typeof getDb>,
+            { documentId: id, ownerEmail, body: mayWriteBody },
+          );
           access = favoriteOnly
             ? await resolveDocumentAccessForMutation(id, "id")
             : await assertDocumentMutationAccess(id, "editor", "id");
@@ -1164,6 +1197,9 @@ const updateDocumentAction = defineAction({
               return;
             }
           }
+          // After the replay check, so a retried save that already landed
+          // still gets its receipt. The page lock above makes this see Trash.
+          if (!favoriteOnly) assertEditableDocument(existing);
           if (settlesPreviewDraft) {
             await lockPreviewDocumentDraftSettlement({
               db: tx,
@@ -1223,10 +1259,76 @@ const updateDocumentAction = defineAction({
             contentCasConflict = true;
             return;
           }
+          if (ctx?.caller === "frontend" && content !== undefined) {
+            const [page] = await tx
+              .select(liveBodyWriterPageColumns)
+              .from(schema.documents)
+              .where(eq(schema.documents.id, id))
+              .limit(1);
+            const gate = await liveBodyWriterGateForRow(page, {
+              transaction: getDbExec(),
+            });
+            if (gate.writePath === "live_copy") {
+              // The editor's updates reach a live copy over collab, so the
+              // body part of its save is not written here. Comparing it with
+              // the stored body would read every peer's live-copy commit as
+              // an unmerged edit and divert this save to History.
+              const saveBodies = new Set(
+                [
+                  args.content,
+                  args.authoredCandidateContent,
+                  args.editorSnapshotContent,
+                ].filter((body): body is string => body !== undefined),
+              );
+              const matchesLiveCopy = [...saveBodies].every(
+                (body) => body === historyBefore.content,
+              );
+              liveCopyBodySave = {
+                status: "live_copy",
+                matchesLiveCopy,
+                bodyRevision: historyBefore.bodyRevision,
+                collabVersion: page.liveCopyVersion as number,
+              };
+              // A tab's body trails peers' commits it hasn't received, so
+              // most saves from two open tabs match no stored body. Old
+              // editors read an unsettled save as unsaved and send its text
+              // to History when the tab reopens.
+              // A receipt acknowledges the submitted body, authored candidate
+              // and recovery snapshot. SQL strips title headings they retain.
+              settlesLiveCopyBody = true;
+              for (const body of saveBodies) {
+                if (body === historyBefore.content) continue;
+                const hold = authoredBase
+                  ? await liveCopyHoldsSave({
+                      base: args.authoredBaseContent as string,
+                      stored: historyBefore.content,
+                      candidate: body,
+                    })
+                  : undefined;
+                if (hold) measurement.reason_code = `live_copy_save_${hold}`;
+                if (hold !== "held") {
+                  settlesLiveCopyBody = false;
+                  break;
+                }
+              }
+              if (settlesLiveCopyBody) {
+                bodyIntentOutcome = { status: "applied" };
+              }
+              content = undefined;
+            } else if (
+              staleBodySave &&
+              staleBodySaveDeferred &&
+              refuseStaleBodySave(historyBefore.content)
+            ) {
+              contentCasConflict = true;
+              return;
+            }
+          }
           const confirmBrowserSave = async (
             snapshot: { title: string; content: string },
             now: string,
           ) => {
+            if (liveCopyBodySave && !settlesLiveCopyBody) return;
             if (
               settlesPreviewDraft &&
               args.editorSnapshotTitle !== undefined &&
@@ -1258,17 +1360,23 @@ const updateDocumentAction = defineAction({
                   updatedAt: schema.documents.updatedAt,
                 })
                 .from(schema.documents)
-                .where(eq(schema.documents.id, id))
+                .where(
+                  and(
+                    eq(schema.documents.id, id),
+                    eq(schema.documents.ownerEmail, ownerEmail),
+                  ),
+                )
                 .limit(1);
               const confirmation: BrowserSaveAttemptConfirmation = {
                 attemptId: args.browserSaveAttemptId,
-                result: "applied",
+                result: liveCopyBodySave ? "live_copy" : "applied",
                 revision: documentRevisionToken(
                   confirmed.bodyRevision,
                   confirmed.content,
                 ),
                 updatedAt: confirmed.updatedAt,
                 softDeletedDatabaseIds,
+                ...(liveCopyBodySave ? { bodySave: liveCopyBodySave } : {}),
               };
               await tx.insert(schema.documentBrowserSaveAttempts).values({
                 id: randomUUID(),
@@ -1330,7 +1438,11 @@ const updateDocumentAction = defineAction({
               });
             }
           };
-          if (authoredBase && authoredCandidateContent !== undefined) {
+          if (
+            authoredBase &&
+            authoredCandidateContent !== undefined &&
+            !liveCopyBodySave
+          ) {
             const prior = await findDocumentBodyIntent({
               db: tx as ReturnType<typeof getDb>,
               ownerEmail,
@@ -1379,7 +1491,11 @@ const updateDocumentAction = defineAction({
                 { status: "resolved" }
               >
             | undefined;
-          if (authoredBase && authoredCandidateContent !== undefined) {
+          if (
+            authoredBase &&
+            authoredCandidateContent !== undefined &&
+            !liveCopyBodySave
+          ) {
             const priorIntents = await readDocumentBodyIntents({
               db: tx as ReturnType<typeof getDb>,
               ownerEmail,
@@ -1486,6 +1602,7 @@ const updateDocumentAction = defineAction({
             ? await lockPrimaryBlocksFields(
                 tx as unknown as ReturnType<typeof getDb>,
                 id,
+                { heldMembershipIds: lockedMembershipIds },
               )
             : [];
           const applied = await commitCanonicalDocumentBodyMutation({
@@ -1493,7 +1610,10 @@ const updateDocumentAction = defineAction({
               if (
                 intentMerge ||
                 (useBodyRevisionCas && lockedContentChanged) ||
-                useDocumentCas
+                // Peers' live-copy commits move updatedAt, so on a live-copy
+                // save the snapshot guards only the fields it still writes.
+                (useDocumentCas &&
+                  (!liveCopyBodySave || lockedDocumentFieldsChanged))
               ) {
                 const rows = await tx
                   .update(schema.documents)
@@ -1592,11 +1712,13 @@ const updateDocumentAction = defineAction({
             );
           }
           committedContentChanged = lockedContentChanged;
-          measurement.outcome = lockedDocumentFieldsChanged
-            ? intentMerge && bodyBaseStale && lockedContentChanged
-              ? "merged"
-              : "written"
-            : "unchanged";
+          measurement.outcome = liveCopyBodySave
+            ? "live_copy_body"
+            : lockedDocumentFieldsChanged
+              ? intentMerge && bodyBaseStale && lockedContentChanged
+                ? "merged"
+                : "written"
+              : "unchanged";
           committedContentBefore = historyBefore.content;
 
           if (lockedTitleChanged && args.title !== undefined) {
@@ -1698,6 +1820,7 @@ const updateDocumentAction = defineAction({
                 content,
                 ownerEmail,
                 now: updatedAt,
+                lockedDatabaseIds,
               });
           }
           if (
@@ -1919,6 +2042,7 @@ const updateDocumentAction = defineAction({
               browserSaveConfirmation,
             ),
             ...(bodyIntentOutcome ? { bodyIntentOutcome } : {}),
+            ...(liveCopyBodySave ? { bodySave: liveCopyBodySave } : {}),
             ...(creativeContext
               ? {
                   contextMode: creativeContext.contextMode,

package/corpus/templates/content/actions/validate-builder-source-execution.ts

@@ -1,6 +1,6 @@
-import { defineAction } from "@agent-native/core/action";
+import { defineAction, fail } from "@agent-native/core/action";
 import { assertAccess } from "@agent-native/core/sharing";
-import { and, eq } from "drizzle-orm";
+import { and, eq, isNull } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
@@ -8,6 +8,14 @@ import type {
   ContentDatabaseResponse,
   ValidateBuilderSourceExecutionRequest,
 } from "../shared/api.js";
+import {
+  builderExecutionPayloadReference,
+  cleanupBuilderPrivatePayload,
+  enqueueBuilderPrivatePayloadCleanup,
+  readBuilderExecutionPayload,
+  storeBuilderExecutionPayload,
+} from "./_builder-cms-blob-custody.js";
+import { isBuilderExecutionClaimStale } from "./_builder-cms-execution-lease.js";
 import {
   buildBuilderCmsExecutionPlan,
   builderCmsExecutionIdempotencyKey,
@@ -19,17 +27,6 @@ import {
 } from "./_database-source-utils.js";
 import { getContentDatabaseResponse } from "./_database-utils.js";
 
-function parsePayload(value: string) {
-  try {
-    const parsed = JSON.parse(value) as unknown;
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {};
-  } catch {
-    return {};
-  }
-}
-
 export default defineAction({
   description:
     "Validate a prepared Builder CMS execution gate as a local dry run. This rebuilds and compares the write plan, but never calls Builder APIs.",
@@ -117,10 +114,45 @@ export default defineAction({
         "Prepare the Builder execution gate before validating it.",
       );
     }
-
     const now = new Date().toISOString();
+    if (execution.state === "succeeded") {
+      fail("Builder execution already succeeded and cannot be revalidated.", {
+        errorCode: "builder_execution_already_succeeded",
+        statusCode: 409,
+      });
+    }
+    if (
+      execution.state === "response_received" ||
+      execution.state === "reconciliation_required"
+    ) {
+      fail("Builder execution requires reconciliation before validation.", {
+        errorCode: "builder_execution_reconciliation_required",
+        statusCode: 409,
+      });
+    }
+    if (
+      execution.state === "running" &&
+      !isBuilderExecutionClaimStale(execution.updatedAt, now)
+    ) {
+      fail("Builder execution is already running.", {
+        errorCode: "builder_execution_running",
+        statusCode: 409,
+      });
+    }
+
+    const binding = {
+      ownerEmail: execution.ownerEmail,
+      sourceId: execution.sourceId,
+      changeSetId: execution.changeSetId,
+      executionId: execution.id,
+      idempotencyKey: execution.idempotencyKey,
+    };
+    const storedPayload = await readBuilderExecutionPayload({
+      payloadJson: execution.payloadJson,
+      binding,
+    });
     const payload = validateBuilderCmsExecutionDryRun({
-      storedPayload: parsePayload(execution.payloadJson),
+      storedPayload,
       plan,
       now,
     });
@@ -136,17 +168,94 @@ export default defineAction({
           ? `${plan.summary} Dry run validated blockers locally.`
           : `${plan.summary} Dry run found a stale execution gate.${stale}`;
 
-    await db
-      .update(schema.contentDatabaseSourceExecutions)
-      .set({
-        state: dryRun?.status === "stale" ? "blocked" : plan.state,
-        summary,
-        payloadJson: JSON.stringify(payload),
-        lastError:
-          dryRun?.status === "stale" ? dryRun.mismatches[0] : plan.lastError,
-        updatedAt: now,
-      })
-      .where(eq(schema.contentDatabaseSourceExecutions.id, execution.id));
+    const payloadJson = await storeBuilderExecutionPayload({
+      payload,
+      binding,
+    });
+    const nextReference = builderExecutionPayloadReference(payloadJson);
+    const previousReference = builderExecutionPayloadReference(
+      execution.payloadJson,
+    );
+    try {
+      const updatedRows = await db.transaction(async (tx) => {
+        const updated = await tx
+          .update(schema.contentDatabaseSourceExecutions)
+          .set({
+            state: dryRun?.status === "stale" ? "blocked" : plan.state,
+            summary,
+            payloadJson,
+            attemptToken: null,
+            lastError:
+              dryRun?.status === "stale"
+                ? dryRun.mismatches[0]
+                : plan.lastError,
+            updatedAt: now,
+          })
+          .where(
+            and(
+              eq(schema.contentDatabaseSourceExecutions.id, execution.id),
+              eq(
+                schema.contentDatabaseSourceExecutions.payloadJson,
+                execution.payloadJson,
+              ),
+              eq(schema.contentDatabaseSourceExecutions.state, execution.state),
+              execution.attemptToken
+                ? eq(
+                    schema.contentDatabaseSourceExecutions.attemptToken,
+                    execution.attemptToken,
+                  )
+                : isNull(schema.contentDatabaseSourceExecutions.attemptToken),
+            ),
+          )
+          .returning({ id: schema.contentDatabaseSourceExecutions.id });
+        if (
+          updated[0] &&
+          previousReference &&
+          previousReference !== nextReference
+        ) {
+          await enqueueBuilderPrivatePayloadCleanup(
+            tx as unknown as ReturnType<typeof getDb>,
+            previousReference,
+          );
+        }
+        return updated;
+      });
+      const [updated] = updatedRows;
+      if (!updated)
+        fail("Builder execution changed during validation.", {
+          errorCode: "builder_execution_changed",
+          statusCode: 409,
+        });
+    } catch (error) {
+      let currentPayloadJson: string | null | undefined;
+      try {
+        const [current] = await db
+          .select({
+            payloadJson: schema.contentDatabaseSourceExecutions.payloadJson,
+          })
+          .from(schema.contentDatabaseSourceExecutions)
+          .where(eq(schema.contentDatabaseSourceExecutions.id, execution.id))
+          .limit(1);
+        currentPayloadJson = current?.payloadJson;
+      } catch {
+        // Inconclusive readback retains both refs.
+      }
+      if (currentPayloadJson !== payloadJson) {
+        if (currentPayloadJson !== undefined && nextReference) {
+          await cleanupBuilderPrivatePayload(
+            nextReference,
+            "uncommitted validated execution",
+          );
+        }
+        throw error;
+      }
+    }
+    if (previousReference && previousReference !== nextReference) {
+      await cleanupBuilderPrivatePayload(
+        previousReference,
+        "superseded validated execution",
+      );
+    }
 
     await db
       .update(schema.contentDatabaseSources)