@agent-native/core-corpus 0.216.0 → 0.217.0

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

@@ -36,6 +36,8 @@ export interface BuilderCmsExecutionPayload {
     sourceQualifiedId: string | null;
     documentId: string | null;
     databaseItemId: string | null;
+    /** The entry's lastUpdated when the change was reviewed; execute rejects a live value that differs. */
+    reviewedLastUpdated: string | null;
   };
   request: {
     method: "POST" | "PATCH";
@@ -872,6 +874,14 @@ export function buildBuilderCmsExecutionPlan(args: {
     targetRow,
     request,
   });
+  const reviewedLastUpdated = targetEntryId
+    ? (targetRow?.lastSourceUpdatedAt ?? null)
+    : null;
+  if (targetEntryId && !reviewedLastUpdated?.trim()) {
+    fieldBlockers.push(
+      "Refresh this Builder entry before writing so its last update time can be checked.",
+    );
+  }
   const safety = builderSafetyChecks({
     source: args.source,
     changeSet: args.changeSet,
@@ -934,6 +944,7 @@ export function buildBuilderCmsExecutionPlan(args: {
         sourceQualifiedId: targetSourceQualifiedId,
         documentId: args.changeSet.documentId,
         databaseItemId: args.changeSet.databaseItemId,
+        reviewedLastUpdated,
       },
       pushMode: effectivePushMode,
       request,
@@ -1003,11 +1014,26 @@ export function validateBuilderCmsExecutionDryRun(args: {
       "Stored Builder effect no longer matches the approved write mode.",
     );
   }
+  const { reviewedLastUpdated: storedReviewedLastUpdated, ...storedTarget } =
+    (storedComparable.target ?? {}) as Partial<
+      BuilderCmsExecutionPayload["target"]
+    >;
+  const { reviewedLastUpdated: planReviewedLastUpdated, ...planTarget } =
+    (planComparable.target ?? {}) as Partial<
+      BuilderCmsExecutionPayload["target"]
+    >;
+  if (stableJson(storedTarget) !== stableJson(planTarget)) {
+    mismatches.push(
+      "Stored Builder target no longer matches the current row identity.",
+    );
+  }
+  // A refresh that saw a newer Builder lastUpdated moves the row baseline, so
+  // the value recorded at review is the one the live check must compare.
   if (
-    stableJson(storedComparable.target) !== stableJson(planComparable.target)
+    (storedReviewedLastUpdated ?? null) !== (planReviewedLastUpdated ?? null)
   ) {
     mismatches.push(
-      "Stored Builder target no longer matches the current row identity.",
+      "Builder entry changed since this change was reviewed. Refresh and review it again.",
     );
   }
 

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

@@ -1,4 +1,11 @@
-import { resolveBuilderCredential } from "@agent-native/core/server";
+import { fail, isActionContractError } from "@agent-native/core/action";
+import {
+  BUILDER_CONTENT_WRITE_SCOPE,
+  BUILDER_OAUTH_RESOURCE,
+  resolveBuilderLegacyRequestAuthorization,
+  resolveBuilderRequestAuthorization,
+  type BuilderRequestAuthorization,
+} from "@agent-native/core/server";
 
 export interface BuilderCmsWriteRequest {
   method: "POST" | "PATCH";
@@ -20,7 +27,10 @@ export const DEFAULT_BUILDER_CMS_WRITE_TIMEOUT_MS = 30_000;
 
 type FetchLike = typeof fetch;
 
-function builderWriteApiHost() {
+function builderWriteApiHost(source: BuilderRequestAuthorization["source"]) {
+  // An OAuth bearer goes only to the Builder API resource it was issued for;
+  // the host overrides apply to private keys alone.
+  if (source === "oauth") return BUILDER_OAUTH_RESOURCE;
   return (
     process.env.BUILDER_CONTENT_API_HOST ??
     process.env.BUILDER_CMS_API_HOST ??
@@ -28,11 +38,80 @@ function builderWriteApiHost() {
   ).replace(/\/+$/, "");
 }
 
-async function readBuilderPrivateKey() {
-  return (
-    (await resolveBuilderCredential("BUILDER_PRIVATE_KEY")) ??
-    (await resolveBuilderCredential("BUILDER_CMS_PRIVATE_KEY"))
+const BUILDER_WRITE_LEGACY_CREDENTIAL_KEYS = [
+  "BUILDER_PRIVATE_KEY",
+  "BUILDER_CMS_PRIVATE_KEY",
+] as const;
+
+async function readBuilderWriteAuthorization(sourceBound: boolean) {
+  try {
+    return await resolveBuilderRequestAuthorization({
+      oauthResource: "general",
+      requiredScope: BUILDER_CONTENT_WRITE_SCOPE,
+      legacyCredentialKeys: BUILDER_WRITE_LEGACY_CREDENTIAL_KEYS,
+    });
+  } catch (error) {
+    // The shared resolver throws instead of falling back when a grant predates
+    // builder:content:write. A caller with no Source binding wrote with the
+    // deploy keys before OAuth, so it keeps that path until re-authorizing.
+    if (
+      sourceBound ||
+      !isActionContractError(error) ||
+      error.errorCode !== "builder_oauth_reauthorization_required" ||
+      error.details?.reason !== "missing_scope" ||
+      error.details.scope !== BUILDER_CONTENT_WRITE_SCOPE
+    ) {
+      throw error;
+    }
+    const legacy = await resolveBuilderLegacyRequestAuthorization(
+      BUILDER_WRITE_LEGACY_CREDENTIAL_KEYS,
+    );
+    if (!legacy) throw error;
+    return legacy;
+  }
+}
+
+function assertBuilderWriteSourceBinding(
+  authorization: Awaited<ReturnType<typeof readBuilderWriteAuthorization>>,
+  expectedSourceSpace: string | null | undefined,
+  expectedSourceConnectionId: string | null | undefined,
+  sourceWrite: boolean,
+) {
+  const sourceBound = Boolean(
+    expectedSourceSpace || expectedSourceConnectionId,
   );
+  // An unbound Source keeps writing with its deploy keys, but OAuth may write
+  // only into the space a Source is bound to.
+  if (
+    sourceBound &&
+    (authorization?.source !== "oauth" ||
+      authorization.oauthResource !== "general")
+  ) {
+    fail(
+      "This Builder source's OAuth connection is unavailable. Reconnect the source before writing.",
+      { errorCode: "builder_connection_required", statusCode: 412 },
+    );
+  }
+  if (authorization?.source !== "oauth") return;
+  if (!sourceWrite && !sourceBound) return;
+  if (!expectedSourceSpace || !expectedSourceConnectionId) {
+    fail(
+      "This Builder source is not bound to its connected space. Refresh the source before writing.",
+      { errorCode: "builder_source_unbound", statusCode: 409 },
+    );
+  }
+  if (authorization.oauthSelectedPublicKey !== expectedSourceSpace) {
+    fail(
+      "The connected Builder space does not match this Content source. Reconnect the source's Builder space before writing.",
+      { errorCode: "builder_source_space_mismatch", statusCode: 409 },
+    );
+  }
+  if (authorization.oauthConnectionId !== expectedSourceConnectionId) {
+    fail(
+      "The connected Builder credential does not match this Content source. Reconnect the source before writing.",
+      { errorCode: "builder_source_connection_mismatch", statusCode: 409 },
+    );
+  }
 }
 
 function parseResponseBody(text: string): unknown {
@@ -136,22 +215,41 @@ function buildWriteResult(args: {
 
 export async function executeBuilderCmsWrite(args: {
   request: BuilderCmsWriteRequest;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  requireSourceBinding?: boolean;
+  legacyOnly?: boolean;
   fetchImpl?: FetchLike;
   /** @deprecated Never used: retrying another transport after dispatch is unsafe. */
   nodeRequestImpl?: unknown;
   timeoutMs?: number;
 }): Promise<BuilderCmsWriteResult> {
-  const privateKey = await readBuilderPrivateKey();
-  if (!privateKey) {
+  const authorization = args.legacyOnly
+    ? await resolveBuilderLegacyRequestAuthorization(
+        BUILDER_WRITE_LEGACY_CREDENTIAL_KEYS,
+      )
+    : await readBuilderWriteAuthorization(
+        Boolean(args.expectedSourceSpace || args.expectedSourceConnectionId),
+      );
+  if (!authorization) {
     return {
       ok: false,
       status: 0,
       responseBody: null,
-      error: "Builder private key is not configured.",
+      error: "Builder write access is not connected.",
     };
   }
+  assertBuilderWriteSourceBinding(
+    authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+    args.requireSourceBinding === true,
+  );
 
-  const url = new URL(args.request.path, builderWriteApiHost());
+  const url = new URL(
+    args.request.path,
+    builderWriteApiHost(authorization.source),
+  );
   for (const [key, value] of Object.entries(args.request.query ?? {})) {
     url.searchParams.set(key, value);
   }
@@ -159,7 +257,7 @@ export async function executeBuilderCmsWrite(args: {
   const body = JSON.stringify(args.request.body);
   const headers = {
     accept: "application/json",
-    authorization: `Bearer ${privateKey}`,
+    authorization: authorization.authorization,
     "content-type": "application/json",
   };
 

package/corpus/templates/content/actions/_builder-docs-client.ts

@@ -1105,6 +1105,7 @@ export async function pushBuilderDocsSource(args: {
 
   const writeResult = await executeBuilderCmsWrite({
     request,
+    legacyOnly: true,
     fetchImpl: args.fetchImpl,
   });
   const refreshedDocument =

package/corpus/templates/content/actions/_builder-private-blob.test-fixture.ts

@@ -0,0 +1,90 @@
+import {
+  PrivateBlobError,
+  registerPrivateBlobProvider,
+  unregisterPrivateBlobProvider,
+  type PrivateBlobHandle,
+  type PrivateBlobProvider,
+} from "@agent-native/core/private-blob";
+import { expect } from "vitest";
+
+import {
+  BUILDER_EXECUTION_PAYLOAD_BLOB_KEY,
+  readBuilderExecutionPayload,
+} from "./_builder-cms-blob-custody";
+
+const PROVIDER_ID = "content-test-memory";
+
+export function registerMemoryPrivateBlobProvider() {
+  const blobs = new Map<string, Uint8Array>();
+  let nextId = 0;
+  let putsUnavailable = false;
+  let deletesUnavailable = false;
+  let deleteCalls = 0;
+  const provider: PrivateBlobProvider = {
+    id: PROVIDER_ID,
+    name: "Content test memory",
+    isConfigured: () => true,
+    put: async (input) => {
+      if (putsUnavailable) {
+        throw new PrivateBlobError("store unavailable", "unavailable");
+      }
+      const id = `${PROVIDER_ID}:${++nextId}`;
+      blobs.set(id, new Uint8Array(input.data));
+      return { id, provider: PROVIDER_ID, opaque: true, encrypted: false };
+    },
+    read: async (handle: PrivateBlobHandle) => {
+      const data = blobs.get(handle.id);
+      if (!data) throw new PrivateBlobError("missing", "not_found");
+      return { data, handle };
+    },
+    delete: async (handle: PrivateBlobHandle) => {
+      deleteCalls += 1;
+      return {
+        ...(deletesUnavailable
+          ? { deleted: false, reason: "temporary storage failure" }
+          : { deleted: blobs.delete(handle.id) }),
+        provider: PROVIDER_ID,
+      };
+    },
+  };
+  registerPrivateBlobProvider(provider);
+  return {
+    blobs,
+    setPutsUnavailable: (value: boolean) => {
+      putsUnavailable = value;
+    },
+    setDeletesUnavailable: (value: boolean) => {
+      deletesUnavailable = value;
+    },
+    getDeleteCalls: () => deleteCalls,
+    unregister: () => unregisterPrivateBlobProvider(PROVIDER_ID),
+  };
+}
+
+export async function storedExecutionPayload(execution: {
+  id: string;
+  ownerEmail: string;
+  sourceId: string;
+  changeSetId: string;
+  idempotencyKey: string;
+  payloadJson: string;
+}): Promise<any> {
+  // The reader also accepts legacy inline rows, so assert custody here: SQL
+  // holds only the blob reference and a receipt marker, never the request.
+  const stored = JSON.parse(execution.payloadJson) as Record<string, unknown>;
+  const { [BUILDER_EXECUTION_PAYLOAD_BLOB_KEY]: reference, ...rest } = stored;
+  expect(reference).toBeDefined();
+  expect(rest).toEqual(
+    "response" in rest ? { response: { stored: true } } : {},
+  );
+  return readBuilderExecutionPayload({
+    payloadJson: execution.payloadJson,
+    binding: {
+      ownerEmail: execution.ownerEmail,
+      sourceId: execution.sourceId,
+      changeSetId: execution.changeSetId,
+      executionId: execution.id,
+      idempotencyKey: execution.idempotencyKey,
+    },
+  });
+}

package/corpus/templates/content/actions/_builder-source-execution-guard.ts

@@ -0,0 +1,48 @@
+import { fail } from "@agent-native/core/action";
+import { and, inArray } from "drizzle-orm";
+
+import { getDb, schema } from "../server/db/index.js";
+import { isBuilderExecutionClaimStale } from "./_builder-cms-execution-lease.js";
+
+export async function assertNoActiveBuilderSourceExecutions(
+  tx: ReturnType<typeof getDb>,
+  sourceIds: string[],
+  changeSetIds?: string[],
+) {
+  if (sourceIds.length === 0 || changeSetIds?.length === 0) return;
+
+  const candidates = await tx
+    .select({
+      state: schema.contentDatabaseSourceExecutions.state,
+      updatedAt: schema.contentDatabaseSourceExecutions.updatedAt,
+    })
+    .from(schema.contentDatabaseSourceExecutions)
+    .where(
+      and(
+        inArray(schema.contentDatabaseSourceExecutions.sourceId, sourceIds),
+        changeSetIds
+          ? inArray(
+              schema.contentDatabaseSourceExecutions.changeSetId,
+              changeSetIds,
+            )
+          : undefined,
+        inArray(schema.contentDatabaseSourceExecutions.state, [
+          "running",
+          "response_received",
+          "reconciliation_required",
+        ]),
+      ),
+    );
+  const now = new Date().toISOString();
+  const active = candidates.some(
+    (execution) =>
+      execution.state !== "running" ||
+      !isBuilderExecutionClaimStale(execution.updatedAt, now),
+  );
+  if (active) {
+    fail(
+      "Cannot replace source records while a Builder execution is running or awaiting reconciliation.",
+      { errorCode: "builder_execution_running", statusCode: 409 },
+    );
+  }
+}

package/corpus/templates/content/actions/_content-save-outcomes.ts

@@ -13,6 +13,7 @@ export type ContentSaveOutcome =
   | "preserved_to_history"
   | "merged"
   | "merged_with_displaced_text"
+  | "live_copy_body"
   | "refused"
   | "applied"
   | "displaced_preserved"
@@ -63,6 +64,10 @@ const reasons = new Set([
   "stale_empty_body",
   "stale_builder_image",
   "recovery_base_changed",
+  "live_copy_save_held",
+  "live_copy_save_unheld",
+  "live_copy_save_noncanonical",
+  "live_copy_save_unchecked",
   "title_base_changed",
   "body_base_changed",
   "body_revision_cas_conflict",