@agent-native/core-corpus 0.216.0 → 0.217.0

package/corpus/templates/content/actions/prepare-builder-source-review.ts

@@ -1,7 +1,7 @@
-import { defineAction } from "@agent-native/core/action";
+import { defineAction, fail } from "@agent-native/core/action";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { assertAccess } from "@agent-native/core/sharing";
-import { and, eq, inArray, or } from "drizzle-orm";
+import { and, eq, inArray, isNull, or } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
@@ -16,6 +16,13 @@ import type {
   PrepareBuilderSourceReviewRequest,
   PrepareBuilderSourceReviewResponse,
 } from "../shared/api.js";
+import {
+  builderExecutionPayloadReference,
+  cleanupBuilderPrivatePayload,
+  enqueueBuilderPrivatePayloadCleanup,
+  readBuilderExecutionPayload,
+  storeBuilderExecutionPayload,
+} from "./_builder-cms-blob-custody.js";
 import {
   buildBuilderCmsExecutionPlan,
   resolveBuilderCmsWriteEffect,
@@ -25,7 +32,6 @@ import { claimBuilderSourceExecutionGate } from "./_builder-source-execution-cla
 import { shouldPreserveBuilderExecution } from "./_builder-source-execution-preservation.js";
 import { createBuilderSourceTiming } from "./_builder-source-timings.js";
 import {
-  canRefreshLocallyBlockedBuilderReview,
   findOpenSourceChangeSet,
   getContentDatabaseSourceSnapshotForReview,
   getContentDatabaseSourceSnapshotForWrite,
@@ -140,17 +146,6 @@ export function reviewPreparePriority(
   return statePriority + effectPriority;
 }
 
-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 {};
-  }
-}
-
 function dryRunStatus(execution: ContentDatabaseSourceExecution | null) {
   const dryRun =
     execution?.payload.dryRun &&
@@ -188,10 +183,18 @@ export function buildBuilderSourceReviewPayload(args: {
     const changedTitle =
       changeSet.fieldChanges.find((field) => field.localFieldKey === "title")
         ?.proposedValue ?? null;
-    const effect = resolveBuilderCmsWriteEffect({
-      source: args.source,
-      changeSet,
-    });
+    const plannedEffect = latestExecution?.payload.effect;
+    const effect =
+      plannedEffect === "autosave" ||
+      plannedEffect === "update_in_place" ||
+      plannedEffect === "create_draft" ||
+      plannedEffect === "publish" ||
+      plannedEffect === "unpublish"
+        ? plannedEffect
+        : resolveBuilderCmsWriteEffect({
+            source: args.source,
+            changeSet,
+          });
 
     return {
       changeSetId: changeSet.id,
@@ -221,9 +224,10 @@ export function buildBuilderSourceReviewPayload(args: {
     .filter(Boolean);
   const hasExecutionEvidence =
     statuses.length > 0 || executionStates.length > 0;
-  const resultStatus =
-    executionStates.length > 0 &&
-    executionStates.every((state) => state === "succeeded")
+  const resultStatus = rows.some((row) => row.execution?.payloadUnavailable)
+    ? "blocked"
+    : executionStates.length > 0 &&
+        executionStates.every((state) => state === "succeeded")
       ? "succeeded"
       : executionStates.includes("reconciliation_required") ||
           executionStates.includes("response_received")
@@ -275,7 +279,9 @@ export function buildBuilderSourceReviewPayload(args: {
                     : "Ready to send to Builder."
                   : "Push checked successfully. Nothing was sent to Builder."
                 : resultStatus === "blocked"
-                  ? "Push needs attention before anything can be sent to Builder."
+                  ? rows.some((row) => row.execution?.payloadUnavailable)
+                    ? "A prepared Builder payload is unavailable. Retry loading the review before anything can be sent."
+                    : "Push needs attention before anything can be sent to Builder."
                   : resultStatus === "stale"
                     ? "Push needs a fresh review because the plan changed."
                     : "Builder writes are off in this local build. Push will check the update only.",
@@ -346,23 +352,11 @@ async function approveChangeSetForReview(args: {
         : null);
 
   if (existing) {
-    const existingExecutions = await db
-      .select({
-        state: schema.contentDatabaseSourceExecutions.state,
-        payloadJson: schema.contentDatabaseSourceExecutions.payloadJson,
-        attemptToken: schema.contentDatabaseSourceExecutions.attemptToken,
-      })
-      .from(schema.contentDatabaseSourceExecutions)
-      .where(
-        and(
-          eq(schema.contentDatabaseSourceExecutions.sourceId, args.sourceId),
-          eq(schema.contentDatabaseSourceExecutions.changeSetId, existing.id),
-        ),
-      );
-    const mayRefreshApprovedPayload =
-      canRefreshLocallyBlockedBuilderReview(existingExecutions);
-
-    if (existing.state === "approved" && !mayRefreshApprovedPayload) {
+    // An approved payload is immutable execution evidence. Even a locally
+    // blocked gate can be claimed after this read, so a materially changed
+    // proposal always receives a new revision identity instead of rewriting
+    // the proposal beneath an in-flight execution.
+    if (existing.state === "approved") {
       if (existingPayloadMatches(existing)) {
         return {
           id: existing.id,
@@ -382,11 +376,9 @@ async function approveChangeSetForReview(args: {
           },
         };
       }
-      // A failed, dispatched, or otherwise non-refreshable gate owns its exact
-      // approved payload forever. A materially different local edit must fall
-      // through to a new revision identity instead of aliasing that evidence.
+      // Fall through to a revision-bound change-set ID below.
     } else {
-      await db
+      const [updated] = await db
         .update(schema.contentDatabaseSourceChangeSets)
         .set({
           direction: "outbound",
@@ -400,7 +392,29 @@ async function approveChangeSetForReview(args: {
             : null,
           updatedAt: args.now,
         })
-        .where(eq(schema.contentDatabaseSourceChangeSets.id, existing.id));
+        .where(
+          and(
+            eq(schema.contentDatabaseSourceChangeSets.id, existing.id),
+            eq(schema.contentDatabaseSourceChangeSets.state, existing.state),
+            eq(
+              schema.contentDatabaseSourceChangeSets.fieldChangesJson,
+              existing.fieldChangesJson,
+            ),
+            existing.bodyChangeJson === null
+              ? isNull(schema.contentDatabaseSourceChangeSets.bodyChangeJson)
+              : eq(
+                  schema.contentDatabaseSourceChangeSets.bodyChangeJson,
+                  existing.bodyChangeJson,
+                ),
+          ),
+        )
+        .returning({ id: schema.contentDatabaseSourceChangeSets.id });
+      if (!updated) {
+        fail("Builder change set changed during approval.", {
+          errorCode: "builder_change_set_changed",
+          statusCode: 409,
+        });
+      }
       if (existing.state !== "approved") {
         await db.insert(schema.contentDatabaseSourceChangeReviews).values({
           id: crypto.randomUUID(),
@@ -504,18 +518,114 @@ async function upsertExecutionGate(args: {
     return;
   }
   if (existing) {
-    await db
-      .update(schema.contentDatabaseSourceExecutions)
-      .set({
-        state: plan.state,
-        summary: plan.summary,
-        payloadJson: JSON.stringify(plan.payload),
-        lastError: plan.lastError,
-        updatedAt: args.now,
-      })
-      .where(eq(schema.contentDatabaseSourceExecutions.id, existing.id));
+    const payloadJson = await storeBuilderExecutionPayload({
+      payload: plan.payload as unknown as Record<string, unknown>,
+      binding: {
+        ownerEmail: args.ownerEmail,
+        sourceId: args.source.id,
+        changeSetId: args.changeSet.id,
+        executionId: existing.id,
+        idempotencyKey: plan.idempotencyKey,
+      },
+    });
+    const nextReference = builderExecutionPayloadReference(payloadJson);
+    const previousReference = builderExecutionPayloadReference(
+      existing.payloadJson,
+    );
+    try {
+      const updatedRows = await db.transaction(async (tx) => {
+        const updated = await tx
+          .update(schema.contentDatabaseSourceExecutions)
+          .set({
+            state: plan.state,
+            summary: plan.summary,
+            payloadJson,
+            lastError: plan.lastError,
+            updatedAt: args.now,
+          })
+          .where(
+            and(
+              eq(schema.contentDatabaseSourceExecutions.id, existing.id),
+              eq(
+                schema.contentDatabaseSourceExecutions.payloadJson,
+                existing.payloadJson,
+              ),
+              eq(schema.contentDatabaseSourceExecutions.state, existing.state),
+              existing.attemptToken
+                ? eq(
+                    schema.contentDatabaseSourceExecutions.attemptToken,
+                    existing.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 prepare.", {
+          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, existing.id))
+          .limit(1);
+        currentPayloadJson = current?.payloadJson;
+      } catch {
+        // Inconclusive readback retains both refs.
+      }
+      if (currentPayloadJson === payloadJson) {
+        // The replacement committed despite an ambiguous acknowledgement.
+      } else {
+        if (currentPayloadJson !== undefined && nextReference) {
+          await cleanupBuilderPrivatePayload(
+            nextReference,
+            "uncommitted prepared execution",
+          );
+        }
+        throw error;
+      }
+    }
+    if (previousReference && previousReference !== nextReference) {
+      await cleanupBuilderPrivatePayload(
+        previousReference,
+        "superseded prepared execution",
+      );
+    }
   } else {
+    let insertedReference: string | null = null;
+    let insertedPayloadJson: string | null = null;
     try {
+      const payloadJson = await storeBuilderExecutionPayload({
+        payload: plan.payload as unknown as Record<string, unknown>,
+        binding: {
+          ownerEmail: args.ownerEmail,
+          sourceId: args.source.id,
+          changeSetId: args.changeSet.id,
+          executionId,
+          idempotencyKey: plan.idempotencyKey,
+        },
+      });
+      insertedReference = builderExecutionPayloadReference(payloadJson);
+      insertedPayloadJson = payloadJson;
       await db.insert(schema.contentDatabaseSourceExecutions).values({
         id: executionId,
         ownerEmail: args.ownerEmail,
@@ -526,18 +636,44 @@ async function upsertExecutionGate(args: {
         state: plan.state,
         idempotencyKey: plan.idempotencyKey,
         summary: plan.summary,
-        payloadJson: JSON.stringify(plan.payload),
+        payloadJson,
         lastError: plan.lastError,
         createdAt: args.now,
         updatedAt: args.now,
       });
     } catch (error) {
-      const [winner] = await db
-        .select()
-        .from(schema.contentDatabaseSourceExecutions)
-        .where(eq(schema.contentDatabaseSourceExecutions.id, executionId))
-        .limit(1);
-      if (!winner) throw error;
+      let winner:
+        | typeof schema.contentDatabaseSourceExecutions.$inferSelect
+        | null
+        | undefined;
+      let readbackCompleted = false;
+      try {
+        [winner] = await db
+          .select()
+          .from(schema.contentDatabaseSourceExecutions)
+          .where(eq(schema.contentDatabaseSourceExecutions.id, executionId))
+          .limit(1);
+        readbackCompleted = true;
+      } catch {
+        // Inconclusive readback retains the new ref.
+      }
+      if (!winner) {
+        if (readbackCompleted && insertedReference) {
+          await cleanupBuilderPrivatePayload(
+            insertedReference,
+            "uncommitted prepared execution",
+          );
+        }
+        throw error;
+      }
+      if (winner.payloadJson === insertedPayloadJson) {
+        // The insert committed despite an ambiguous acknowledgement.
+      } else if (insertedReference) {
+        await cleanupBuilderPrivatePayload(
+          insertedReference,
+          "uncommitted prepared execution",
+        );
+      }
       if (
         shouldPreserveBuilderExecution({
           state: winner.state,
@@ -558,8 +694,18 @@ async function upsertExecutionGate(args: {
     .where(eq(schema.contentDatabaseSourceExecutions.id, executionId));
   if (!execution) return;
 
+  const storedPayload = await readBuilderExecutionPayload({
+    payloadJson: execution.payloadJson,
+    binding: {
+      ownerEmail: execution.ownerEmail,
+      sourceId: execution.sourceId,
+      changeSetId: execution.changeSetId,
+      executionId: execution.id,
+      idempotencyKey: execution.idempotencyKey,
+    },
+  });
   const payload = validateBuilderCmsExecutionDryRun({
-    storedPayload: parsePayload(execution.payloadJson),
+    storedPayload,
     plan,
     now: args.now,
   });
@@ -571,17 +717,97 @@ async function upsertExecutionGate(args: {
         ? `${plan.summary} Dry run validated blockers locally.`
         : `${plan.summary} Dry run found a stale execution gate.`;
 
-  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: args.now,
-    })
-    .where(eq(schema.contentDatabaseSourceExecutions.id, executionId));
+  const payloadJson = await storeBuilderExecutionPayload({
+    payload,
+    binding: {
+      ownerEmail: execution.ownerEmail,
+      sourceId: execution.sourceId,
+      changeSetId: execution.changeSetId,
+      executionId: execution.id,
+      idempotencyKey: execution.idempotencyKey,
+    },
+  });
+  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,
+          lastError:
+            dryRun?.status === "stale" ? dryRun.mismatches[0] : plan.lastError,
+          updatedAt: args.now,
+        })
+        .where(
+          and(
+            eq(schema.contentDatabaseSourceExecutions.id, executionId),
+            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, executionId))
+        .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",
+    );
+  }
 }
 
 export default defineAction({

package/corpus/templates/content/actions/set-live-body-switch.ts

@@ -0,0 +1,45 @@
+import { ActionContractError } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { LiveBodyConversionError } from "../server/live-copy/persist.js";
+import {
+  switchPageToLegacy,
+  switchPageToLiveCopy,
+} from "../server/live-copy/switch.js";
+import { assertDocumentMutationAccess } from "./_document-mutation-access.js";
+
+export default defineAction({
+  description:
+    "Switch one page's body writes to its live copy, or back to the legacy writer, for the live-copy rollout.",
+  uiOnly: true,
+  agentTool: false,
+  toolCallable: false,
+  mcpTool: false,
+  schema: z.object({
+    id: z.string().min(1).describe("Document ID"),
+    switched: z
+      .boolean()
+      .describe("true writes through the live copy; false goes back"),
+  }),
+  run: async (args, ctx) => {
+    await assertDocumentMutationAccess(args.id, "editor", "id");
+    try {
+      const gate = args.switched
+        ? await switchPageToLiveCopy(args.id, { ctx })
+        : await switchPageToLegacy(args.id);
+      return { id: args.id, ...gate };
+    } catch (error) {
+      if (error instanceof LiveBodyConversionError) {
+        throw new ActionContractError(error.message, {
+          errorCode:
+            error.code === "flag_off"
+              ? "LIVE_BODY_WRITER_OFF"
+              : "LIVE_BODY_SWITCH_CONFLICT",
+          statusCode: 409,
+        });
+      }
+      throw error;
+    }
+  },
+});