@agent-native/core 0.80.5 → 0.80.7

package/corpus/templates/content/actions/_builder-cms-write-adapter.ts

@@ -1,16 +1,17 @@
 import type {
+  BuilderCmsPublicationTransitionIntent,
+  BuilderCmsWriteEffect,
   ContentDatabaseSource,
   ContentDatabaseSourceChangeSet,
   ContentDatabaseSourceExecutionState,
   ContentDatabaseSourcePushMode,
+  ContentDatabaseSourceWriteMode,
 } from "../shared/api.js";
 import { BUILDER_CMS_SAFE_WRITE_MODEL as SAFE_WRITE_MODEL } from "../shared/api.js";
 import { builderCmsSourceRowIdentityState } from "./_builder-cms-source-adapter.js";
+import { builderCmsPushModeForTier } from "./_builder-cms-write-settings.js";
 
-export type BuilderCmsWriteIntent =
-  | "autosave_revision"
-  | "save_draft"
-  | "publish";
+export type { BuilderCmsWriteEffect };
 
 export interface BuilderCmsExecutionOperation {
   sourceFieldKey: string;
@@ -24,7 +25,7 @@ export interface BuilderCmsExecutionPayload {
   sourceTable: string;
   changeSetId: string;
   pushMode: ContentDatabaseSourcePushMode;
-  intent: BuilderCmsWriteIntent;
+  effect: BuilderCmsWriteEffect;
   target: {
     model: string;
     entryId: string | null;
@@ -71,12 +72,107 @@ export function builderCmsExecutionIdempotencyKey(args: {
   return `builder-cms:${args.sourceId}:${args.changeSetId}:${args.pushMode}`;
 }
 
-function builderIntentForPushMode(
-  pushMode: ContentDatabaseSourcePushMode,
-): BuilderCmsWriteIntent {
-  if (pushMode === "draft") return "save_draft";
-  if (pushMode === "publish") return "publish";
-  return "autosave_revision";
+function builderEffectForWrite(args: {
+  pushMode: ContentDatabaseSourcePushMode;
+  writeMode?: ContentDatabaseSourceWriteMode | null;
+  entryId: string | null;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent | null;
+}): BuilderCmsWriteEffect {
+  if (!args.entryId) return "create_draft";
+  if (args.publicationTransition === "publish") return "publish";
+  if (args.publicationTransition === "unpublish") return "unpublish";
+  if (args.writeMode === "stage_only") return "autosave";
+  if (args.writeMode === "publish_updates") return "update_in_place";
+  if (args.pushMode === "autosave") return "autosave";
+  return "update_in_place";
+}
+
+function normalizeSourceWriteMode(
+  value: unknown,
+): ContentDatabaseSourceWriteMode | null {
+  return value === "read_only" ||
+    value === "stage_only" ||
+    value === "publish_updates"
+    ? value
+    : null;
+}
+
+/**
+ * Single source of truth for the push mode that gates an execution. Prepare and
+ * execute MUST resolve this identically, or their idempotency keys diverge and
+ * the gate lookup fails ("Prepare the Builder execution gate before executing
+ * it"). The write tier wins when set, so a change-set's own `pushMode` (e.g. a
+ * local create hardcoded to "autosave") cannot drift from the tier.
+ */
+export function resolveBuilderCmsExecutionPushMode(args: {
+  source: ContentDatabaseSource;
+  changeSet: ContentDatabaseSourceChangeSet;
+}): ContentDatabaseSourcePushMode {
+  const sourceWriteMode = normalizeSourceWriteMode(
+    args.source.metadata.writeMode,
+  );
+  if (sourceWriteMode) {
+    return builderCmsPushModeForTier(sourceWriteMode);
+  }
+  return args.changeSet.pushMode ?? args.source.metadata.pushMode ?? "autosave";
+}
+
+/**
+ * Resolve the Builder entry this change-set targets. A synthetic-fixture row
+ * (sourceRowId `builder-<documentId>`, never matched to a real entry) resolves
+ * to a null entry id, which is what makes the effect a create.
+ */
+export function resolveBuilderCmsWriteTarget(args: {
+  source: ContentDatabaseSource;
+  changeSet: ContentDatabaseSourceChangeSet;
+}) {
+  const targetRow =
+    args.source.rows.find(
+      (row) =>
+        row.documentId === args.changeSet.documentId ||
+        row.databaseItemId === args.changeSet.databaseItemId,
+    ) ?? null;
+  const target = targetRow
+    ? builderCmsSourceRowIdentityState({ row: targetRow })
+    : null;
+  const entryId = target?.isSyntheticFixture
+    ? null
+    : (target?.sourceRowId ?? null);
+  const sourceQualifiedId = target?.isSyntheticFixture
+    ? null
+    : (target?.sourceQualifiedId ?? null);
+  return { targetRow, target, entryId, sourceQualifiedId };
+}
+
+/**
+ * The resolved write effect (create_draft / update_in_place / autosave /
+ * publish / unpublish) for a change-set. Unlike buildBuilderCmsExecutionPlan
+ * this does not require the change-set to be approved, so it is safe to call
+ * while building review payloads for plain-language labels.
+ */
+export function resolveBuilderCmsWriteEffect(args: {
+  source: ContentDatabaseSource;
+  changeSet: ContentDatabaseSourceChangeSet;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent | null;
+}): BuilderCmsWriteEffect {
+  const sourceWriteMode = normalizeSourceWriteMode(
+    args.source.metadata.writeMode,
+  );
+  const pushMode = resolveBuilderCmsExecutionPushMode({
+    source: args.source,
+    changeSet: args.changeSet,
+  });
+  const effectivePushMode = pushMode === "none" ? "autosave" : pushMode;
+  const { entryId } = resolveBuilderCmsWriteTarget({
+    source: args.source,
+    changeSet: args.changeSet,
+  });
+  return builderEffectForWrite({
+    pushMode: effectivePushMode,
+    writeMode: sourceWriteMode,
+    entryId,
+    publicationTransition: args.publicationTransition,
+  });
 }
 
 function nestedBuilderPatch(
@@ -98,15 +194,15 @@ function nestedBuilderPatch(
   return body;
 }
 
-function builderRequestForIntent(args: {
-  intent: BuilderCmsWriteIntent;
+function builderRequestForEffect(args: {
+  effect: BuilderCmsWriteEffect;
   model: string;
   entryId: string | null;
   bodyPatch: Record<string, unknown>;
 }): BuilderCmsExecutionPayload["request"] {
   const entryPath = args.entryId ? `/${encodeURIComponent(args.entryId)}` : "";
   const basePath = `/api/v1/write/${encodeURIComponent(args.model)}${entryPath}`;
-  if (args.intent === "autosave_revision") {
+  if (args.effect === "autosave") {
     return {
       method: "PATCH",
       path: basePath,
@@ -117,12 +213,22 @@ function builderRequestForIntent(args: {
       body: args.bodyPatch,
     };
   }
-  if (args.intent === "publish") {
+  if (args.effect === "update_in_place") {
+    return {
+      method: "PATCH",
+      path: basePath,
+      query: {
+        triggerWebhooks: "true",
+      },
+      body: args.bodyPatch,
+    };
+  }
+  if (args.effect === "publish") {
     return {
       method: args.entryId ? "PATCH" : "POST",
       path: basePath,
       query: {
-        triggerWebhooks: "false",
+        triggerWebhooks: "true",
       },
       body: {
         ...args.bodyPatch,
@@ -130,8 +236,21 @@ function builderRequestForIntent(args: {
       },
     };
   }
+  if (args.effect === "unpublish") {
+    return {
+      method: "PATCH",
+      path: basePath,
+      query: {
+        triggerWebhooks: "true",
+      },
+      body: {
+        ...args.bodyPatch,
+        published: "draft",
+      },
+    };
+  }
   return {
-    method: args.entryId ? "PATCH" : "POST",
+    method: "POST",
     path: basePath,
     query: {
       triggerWebhooks: "false",
@@ -147,7 +266,9 @@ function builderSafetyChecks(args: {
   source: ContentDatabaseSource;
   changeSet: ContentDatabaseSourceChangeSet;
   pushMode: ContentDatabaseSourcePushMode;
-  intent: BuilderCmsWriteIntent;
+  effect: BuilderCmsWriteEffect;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent | null;
+  confirmUnpublish?: boolean;
   entryId: string | null;
   syntheticFixtureTarget: boolean;
   operations: BuilderCmsExecutionOperation[];
@@ -155,7 +276,6 @@ function builderSafetyChecks(args: {
   const checks = [
     "Requires explicit approval before execution.",
     "Uses the stored execution idempotency key.",
-    "Does not run while live Builder writes are disabled.",
   ];
   const blockers: string[] = [];
 
@@ -165,28 +285,45 @@ function builderSafetyChecks(args: {
   if (args.changeSet.bodyChange) {
     blockers.push("Builder body diffs are not executable in this slice.");
   }
-  if (args.intent === "autosave_revision") {
-    checks.push("Autosave keeps published state unchanged.");
+  if (args.effect === "autosave" || args.effect === "update_in_place") {
+    const label = args.effect === "autosave" ? "Autosave" : "Update in place";
+    checks.push(
+      `${label} preserves publication state — no published field is sent.`,
+    );
     if (args.syntheticFixtureTarget) {
       blockers.push(
         "This row is not matched to a Builder entry yet. Refresh or match a Builder row before pushing.",
       );
     } else if (!args.entryId) {
-      blockers.push("Autosave requires an existing Builder entry ID.");
+      blockers.push(`${label} requires an existing Builder entry ID.`);
     }
   }
-  if (args.intent === "save_draft") {
-    checks.push("Draft writes set Builder published state to draft.");
-    if (args.source.metadata.allowDraftWrites !== true) {
-      blockers.push(
-        "Draft writes require explicit adapter opt-in because draft can affect already-live content.",
-      );
+  if (args.effect === "create_draft") {
+    checks.push(
+      "Create draft writes a new Builder entry with published state set to draft.",
+    );
+    // A create_draft target has no Builder entry by definition — that is the
+    // whole point of a create. The unmatched-row blocker only applies to
+    // effects that write to an existing entry (autosave / update_in_place).
+  }
+  if (args.effect === "publish") {
+    checks.push(
+      "Publish transition sets Builder published state to published.",
+    );
+    if (args.publicationTransition !== "publish") {
+      blockers.push("Publish requires an explicit publication transition.");
+    }
+    if (args.source.metadata.allowPublicationTransitions !== true) {
+      blockers.push("Publication transitions are not enabled for this source.");
     }
   }
-  if (args.intent === "publish") {
-    checks.push("Publish writes set Builder published state to published.");
-    if (args.source.metadata.allowPublishWrites !== true) {
-      blockers.push("Publish writes require explicit adapter opt-in.");
+  if (args.effect === "unpublish") {
+    checks.push("Unpublish transition sets Builder published state to draft.");
+    if (args.source.metadata.allowPublicationTransitions !== true) {
+      blockers.push("Publication transitions are not enabled for this source.");
+    }
+    if (args.confirmUnpublish !== true) {
+      blockers.push("Unpublish requires explicit confirmation.");
     }
   }
 
@@ -202,6 +339,18 @@ function builderSafetyChecks(args: {
       `Live Builder writes are only allowed for ${SAFE_WRITE_MODEL}.`,
     );
   }
+  if (args.source.capabilities.liveWritesEnabled !== true) {
+    checks.push("Does not run while live Builder writes are disabled.");
+    if (
+      args.effect === "update_in_place" ||
+      args.effect === "publish" ||
+      args.effect === "unpublish"
+    ) {
+      blockers.push(
+        `${args.effect} requires live Builder writes to be enabled.`,
+      );
+    }
+  }
 
   return { checks, blockers };
 }
@@ -210,6 +359,8 @@ export function buildBuilderCmsExecutionPlan(args: {
   source: ContentDatabaseSource;
   changeSet: ContentDatabaseSourceChangeSet;
   pushModeConfirmation?: ContentDatabaseSourcePushMode | null;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent | null;
+  confirmUnpublish?: boolean;
 }): BuilderCmsExecutionPlan {
   if (args.source.sourceType !== "builder-cms") {
     throw new Error("Builder execution plans require a Builder CMS source.");
@@ -223,45 +374,56 @@ export function buildBuilderCmsExecutionPlan(args: {
     );
   }
 
-  const pushMode =
-    args.changeSet.pushMode ?? args.source.metadata.pushMode ?? "autosave";
+  const sourceWriteMode = normalizeSourceWriteMode(
+    args.source.metadata.writeMode,
+  );
+  const pushMode = resolveBuilderCmsExecutionPushMode({
+    source: args.source,
+    changeSet: args.changeSet,
+  });
+  const effectivePushMode = pushMode === "none" ? "autosave" : pushMode;
   if (pushMode === "none") {
-    throw new Error(
-      "Builder execution requires Autosave, Draft, or Publish push mode.",
-    );
+    if (args.source.capabilities.liveWritesEnabled === true) {
+      throw new Error(
+        "Builder execution requires Autosave, Draft, or Publish push mode.",
+      );
+    }
   }
-  if (args.pushModeConfirmation && args.pushModeConfirmation !== pushMode) {
+  if (
+    pushMode !== "none" &&
+    args.pushModeConfirmation &&
+    args.pushModeConfirmation !== pushMode
+  ) {
     throw new Error(
       `Push mode confirmation did not match approved change set: ${pushMode}.`,
     );
   }
 
-  const intent = builderIntentForPushMode(pushMode);
-  const targetRow =
-    args.source.rows.find(
-      (row) =>
-        row.documentId === args.changeSet.documentId ||
-        row.databaseItemId === args.changeSet.databaseItemId,
-    ) ?? null;
-  const target = targetRow
-    ? builderCmsSourceRowIdentityState({
-        row: targetRow,
-      })
-    : null;
-  const targetEntryId = target?.isSyntheticFixture
-    ? null
-    : (target?.sourceRowId ?? null);
-  const targetSourceQualifiedId = target?.isSyntheticFixture
-    ? null
-    : (target?.sourceQualifiedId ?? null);
+  const {
+    target,
+    entryId: targetEntryId,
+    sourceQualifiedId: targetSourceQualifiedId,
+  } = resolveBuilderCmsWriteTarget({
+    source: args.source,
+    changeSet: args.changeSet,
+  });
+  const effect = builderEffectForWrite({
+    pushMode: effectivePushMode,
+    writeMode: sourceWriteMode,
+    entryId: targetEntryId,
+    publicationTransition: args.publicationTransition,
+  });
   const operations = args.changeSet.fieldChanges.map((field) => ({
     sourceFieldKey: field.sourceFieldKey,
     localFieldKey: field.localFieldKey,
     value: field.proposedValue,
   }));
   const bodyPatch = nestedBuilderPatch(operations);
-  const request = builderRequestForIntent({
-    intent,
+  // State-preserving effects must not include `published` in the body. Builder
+  // PATCH preserves omitted publication state, so only transition/create effects
+  // are allowed to set it.
+  const request = builderRequestForEffect({
+    effect,
     model: args.source.sourceTable,
     entryId: targetEntryId,
     bodyPatch,
@@ -269,8 +431,10 @@ export function buildBuilderCmsExecutionPlan(args: {
   const safety = builderSafetyChecks({
     source: args.source,
     changeSet: args.changeSet,
-    pushMode,
-    intent,
+    pushMode: effectivePushMode,
+    effect,
+    publicationTransition: args.publicationTransition,
+    confirmUnpublish: args.confirmUnpublish,
     entryId: targetEntryId,
     syntheticFixtureTarget:
       args.source.capabilities.liveWritesEnabled === true &&
@@ -284,17 +448,22 @@ export function buildBuilderCmsExecutionPlan(args: {
       : args.source.capabilities.liveWritesEnabled === true
         ? "ready"
         : "write_disabled";
+  // Key on the RAW resolved push mode (which may be "none" for a read-only
+  // tier), not the effective one. Collapsing "none" → "autosave" would let a
+  // read-only gate share a key with a stage-only gate for the same change-set,
+  // so enabling live writes could reuse a gate prepared under read-only.
   const idempotencyKey = builderCmsExecutionIdempotencyKey({
     sourceId: args.source.id,
     changeSetId: args.changeSet.id,
     pushMode,
   });
+  const summaryMode = pushMode === "none" ? "read-only" : pushMode;
   const summary =
     state === "ready"
-      ? `Prepared Builder ${pushMode} execution. Ready to send to Builder.`
+      ? `Prepared Builder ${summaryMode} execution. Ready to send to Builder.`
       : state === "blocked"
-        ? `Prepared Builder ${pushMode} execution, but it is blocked: ${safety.blockers.join(" ")}`
-        : `Prepared Builder ${pushMode} execution, but live writes are disabled.`;
+        ? `Prepared Builder ${summaryMode} execution, but it is blocked: ${safety.blockers.join(" ")}`
+        : `Prepared Builder ${summaryMode} execution, but live writes are disabled.`;
   const lastError =
     state === "ready"
       ? null
@@ -304,7 +473,7 @@ export function buildBuilderCmsExecutionPlan(args: {
 
   return {
     adapter: "builder-cms",
-    pushMode,
+    pushMode: effectivePushMode,
     state,
     idempotencyKey,
     summary,
@@ -313,7 +482,7 @@ export function buildBuilderCmsExecutionPlan(args: {
       databaseId: args.source.databaseId,
       sourceTable: args.source.sourceTable,
       changeSetId: args.changeSet.id,
-      intent,
+      effect,
       target: {
         model: args.source.sourceTable,
         entryId: targetEntryId,
@@ -321,7 +490,7 @@ export function buildBuilderCmsExecutionPlan(args: {
         documentId: args.changeSet.documentId,
         databaseItemId: args.changeSet.databaseItemId,
       },
-      pushMode,
+      pushMode: effectivePushMode,
       request,
       operations,
       safety: {
@@ -384,9 +553,9 @@ export function validateBuilderCmsExecutionDryRun(args: {
       "Stored Builder operations no longer match the approved change.",
     );
   }
-  if (storedComparable.intent !== planComparable.intent) {
+  if (storedComparable.effect !== planComparable.effect) {
     mismatches.push(
-      "Stored Builder intent no longer matches the approved push mode.",
+      "Stored Builder effect no longer matches the approved write mode.",
     );
   }
   if (
@@ -414,7 +583,7 @@ export function validateBuilderCmsExecutionDryRun(args: {
       validatedAt: args.now,
       checks: [
         "Rebuilt execution plan from current source state.",
-        "Compared request, operations, intent, and target against stored gate.",
+        "Compared request, operations, effect, and target against stored gate.",
         "No Builder API call was made.",
       ],
       mismatches,