@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/content/actions/add-content-database-source-field-property.ts

@@ -393,15 +393,23 @@ export default defineAction({
       throw new Error("The title source field is already mapped to Name.");
     }
 
-    let federationRole: string | null = null;
+    let sourceMetadata: {
+      builderSpacePublicKey?: unknown;
+      connectionId?: unknown;
+      federation?: { role?: unknown };
+    } = {};
     try {
-      const parsed = JSON.parse(source.metadataJson ?? "{}") as {
-        federation?: { role?: string };
-      };
-      federationRole = parsed.federation?.role ?? null;
+      const parsed = JSON.parse(source.metadataJson ?? "{}") as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        sourceMetadata = parsed as typeof sourceMetadata;
+      }
     } catch {
-      federationRole = null;
+      sourceMetadata = {};
     }
+    const federationRole =
+      typeof sourceMetadata.federation?.role === "string"
+        ? sourceMetadata.federation.role
+        : null;
     const isSecondary = federationRole === "secondary";
 
     const materializeProperty = (
@@ -676,9 +684,18 @@ export default defineAction({
 
       const builderRead = await readBuilderCmsContentEntries({
         model: source.sourceTable,
+        expectedSourceSpace:
+          typeof sourceMetadata.builderSpacePublicKey === "string"
+            ? sourceMetadata.builderSpacePublicKey
+            : undefined,
+        expectedSourceConnectionId:
+          typeof sourceMetadata.connectionId === "string"
+            ? sourceMetadata.connectionId
+            : undefined,
         fieldPaths: [field.sourceFieldKey],
         limit: Math.max(BUILDER_FIELD_REFRESH_MINIMUM_LIMIT, error.rowCount),
         offset: 0,
+        requireBoundOAuth: true,
       });
       if (builderRead.state !== "live") {
         throw new Error(

package/corpus/templates/content/actions/cancel-prepared-builder-source-update.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 } from "drizzle-orm";
+import { and, eq, inArray, isNull } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
@@ -9,6 +9,7 @@ import type {
   CancelPreparedBuilderSourceUpdateRequest,
   CancelPreparedBuilderSourceUpdateResponse,
 } from "../shared/api.js";
+import { readBuilderExecutionPayload } from "./_builder-cms-blob-custody.js";
 import {
   CANCELLED_BUILDER_EXECUTION_SUMMARY,
   CANCELLED_BUILDER_REVIEW_NOTE_PREFIX,
@@ -45,28 +46,63 @@ function isLocalBlockedDryRun(payload: Record<string, unknown>) {
   );
 }
 
+function isLivePreflightBlocked(payload: Record<string, unknown>) {
+  const preflight = payload.livePreflight;
+  if (!preflight || typeof preflight !== "object" || Array.isArray(preflight)) {
+    return false;
+  }
+  const record = preflight as Record<string, unknown>;
+  return (
+    typeof record.checkedAt === "string" &&
+    typeof record.exists === "boolean" &&
+    (record.lastUpdated === null ||
+      typeof record.lastUpdated === "number" ||
+      typeof record.lastUpdated === "string") &&
+    (record.blocksHash === null || typeof record.blocksHash === "string")
+  );
+}
+
+function isDefinitivelyRejectedWrite(payload: Record<string, unknown>) {
+  const response = payload.response;
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    return false;
+  }
+  const record = response as Record<string, unknown>;
+  return (
+    record.ok === false &&
+    typeof record.status === "number" &&
+    Number.isInteger(record.status) &&
+    record.status >= 400 &&
+    record.status < 500
+  );
+}
+
 function assertProvablyPreDispatch(execution: {
   state: string;
   summary: string;
   payloadJson: string;
   attemptToken: string | null;
 }) {
-  if (!PRE_DISPATCH_STATES.has(execution.state)) {
+  const payload = parseExecutionPayload(execution.payloadJson);
+  const definitiveRejectedWrite =
+    (execution.state === "failed" || execution.state === "blocked") &&
+    isDefinitivelyRejectedWrite(payload);
+  if (!PRE_DISPATCH_STATES.has(execution.state) && !definitiveRejectedWrite) {
     throw new Error(
       `Cannot cancel a Builder execution in state ${execution.state}. Its outcome must be preserved.`,
     );
   }
-  if (execution.attemptToken) {
+  if (execution.attemptToken && !definitiveRejectedWrite) {
     throw new Error(
       "Cannot cancel this Builder update because a dispatch attempt was recorded.",
     );
   }
 
-  const payload = parseExecutionPayload(execution.payloadJson);
   if (
     Object.prototype.hasOwnProperty.call(payload, "response") ||
     Object.prototype.hasOwnProperty.call(payload, "dispatch")
   ) {
+    if (definitiveRejectedWrite) return;
     throw new Error(
       "Cannot cancel this Builder update because dispatch or response evidence was recorded.",
     );
@@ -74,7 +110,8 @@ function assertProvablyPreDispatch(execution: {
   if (
     execution.state === "blocked" &&
     execution.summary !== CANCELLED_BUILDER_EXECUTION_SUMMARY &&
-    !isLocalBlockedDryRun(payload)
+    !isLocalBlockedDryRun(payload) &&
+    !isLivePreflightBlocked(payload)
   ) {
     throw new Error(
       "Cannot cancel this blocked Builder update because it is not provably a local pre-dispatch block.",
@@ -111,7 +148,7 @@ function assertCanonicalClaims(
 
 export default defineAction({
   description:
-    "Cancel one exact prepared Builder update only when every execution is provably pre-dispatch. This never calls Builder or deletes audit history.",
+    "Cancel one exact prepared Builder update only when every execution never dispatched or Builder definitively rejected it. This never calls Builder or deletes audit history.",
   schema: z
     .object({
       databaseId: z.string().optional().describe("Collection ID"),
@@ -167,7 +204,7 @@ export default defineAction({
         .limit(1);
       if (!changeSet) throw new Error("Source change-set not found.");
 
-      const executions = await tx
+      const storedExecutions = await tx
         .select()
         .from(schema.contentDatabaseSourceExecutions)
         .where(
@@ -179,6 +216,24 @@ export default defineAction({
             ),
           ),
         );
+      const executions = await Promise.all(
+        storedExecutions.map(async (execution) => ({
+          ...execution,
+          storedPayloadJson: execution.payloadJson,
+          payloadJson: JSON.stringify(
+            await readBuilderExecutionPayload({
+              payloadJson: execution.payloadJson,
+              binding: {
+                ownerEmail: execution.ownerEmail,
+                sourceId: execution.sourceId,
+                changeSetId: execution.changeSetId,
+                executionId: execution.id,
+                idempotencyKey: execution.idempotencyKey,
+              },
+            }),
+          ),
+        })),
+      );
       executionIds = executions.map((execution) => execution.id);
 
       if (executions.length === 0) {
@@ -253,23 +308,40 @@ export default defineAction({
         );
       }
 
-      await tx
-        .update(schema.contentDatabaseSourceExecutions)
-        .set({
-          state: "blocked",
-          summary: CANCELLED_BUILDER_EXECUTION_SUMMARY,
-          lastError: null,
-          updatedAt: now,
-        })
-        .where(
-          and(
-            eq(schema.contentDatabaseSourceExecutions.sourceId, source.id),
-            eq(
-              schema.contentDatabaseSourceExecutions.changeSetId,
-              changeSet.id,
+      for (const execution of executions) {
+        const [updated] = await tx
+          .update(schema.contentDatabaseSourceExecutions)
+          .set({
+            state: "blocked",
+            summary: CANCELLED_BUILDER_EXECUTION_SUMMARY,
+            attemptToken: null,
+            lastError: null,
+            updatedAt: now,
+          })
+          .where(
+            and(
+              eq(schema.contentDatabaseSourceExecutions.id, execution.id),
+              eq(schema.contentDatabaseSourceExecutions.state, execution.state),
+              eq(
+                schema.contentDatabaseSourceExecutions.payloadJson,
+                execution.storedPayloadJson,
+              ),
+              execution.attemptToken
+                ? eq(
+                    schema.contentDatabaseSourceExecutions.attemptToken,
+                    execution.attemptToken,
+                  )
+                : isNull(schema.contentDatabaseSourceExecutions.attemptToken),
             ),
-          ),
-        );
+          )
+          .returning({ id: schema.contentDatabaseSourceExecutions.id });
+        if (!updated) {
+          fail(
+            "Cannot cancel this Builder update because an execution changed before cancellation committed.",
+            { errorCode: "builder_update_changed", statusCode: 409 },
+          );
+        }
+      }
 
       const noteSuffix = args.note?.trim() ? ` Note: ${args.note.trim()}` : "";
       await tx.insert(schema.contentDatabaseSourceChangeReviews).values({
@@ -284,10 +356,22 @@ export default defineAction({
         note: `${CANCELLED_BUILDER_REVIEW_NOTE_PREFIX} by ${actor} at ${now}.${noteSuffix}`,
         createdAt: now,
       });
-      await tx
+      const [rejectedChangeSet] = await tx
         .update(schema.contentDatabaseSourceChangeSets)
         .set({ state: "rejected", updatedAt: now })
-        .where(eq(schema.contentDatabaseSourceChangeSets.id, changeSet.id));
+        .where(
+          and(
+            eq(schema.contentDatabaseSourceChangeSets.id, changeSet.id),
+            eq(schema.contentDatabaseSourceChangeSets.state, changeSet.state),
+          ),
+        )
+        .returning({ id: schema.contentDatabaseSourceChangeSets.id });
+      if (!rejectedChangeSet) {
+        fail(
+          "Cannot cancel this Builder update because its review state changed before cancellation committed.",
+          { errorCode: "builder_update_changed", statusCode: 409 },
+        );
+      }
       await tx
         .update(schema.contentDatabaseSources)
         .set({ updatedAt: now })

package/corpus/templates/content/actions/change-content-database-source-role.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core/action";
+import { defineAction, fail } from "@agent-native/core/action";
 import { assertAccess } from "@agent-native/core/sharing";
 import { and, asc, eq, inArray, isNull, ne, sql } from "drizzle-orm";
 import { z } from "zod";
@@ -135,6 +135,33 @@ function sourceRole(source: SourceRecord): "primary" | "secondary" | null {
   }
 }
 
+function builderSourceReadBinding(source: SourceRecord) {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source.metadataJson ?? "{}");
+  } catch {
+    fail("Builder source connection metadata is unreadable.", {
+      errorCode: "builder_source_binding_invalid",
+      statusCode: 412,
+    });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    fail("Builder source connection metadata is unreadable.", {
+      errorCode: "builder_source_binding_invalid",
+      statusCode: 412,
+    });
+  }
+  const metadata = parsed as Record<string, unknown>;
+  return {
+    expectedSourceSpace:
+      typeof metadata.builderSpacePublicKey === "string"
+        ? metadata.builderSpacePublicKey
+        : null,
+    expectedSourceConnectionId:
+      typeof metadata.connectionId === "string" ? metadata.connectionId : null,
+  };
+}
+
 async function clearSourceFederation(sourceId: string, now: string) {
   await mutateContentDatabaseSourceMetadata({
     sourceId,
@@ -235,6 +262,8 @@ export async function readBuilderCmsEntriesForRoleChange(
   args: {
     model: string;
     existingFieldPaths?: readonly string[];
+    expectedSourceSpace?: string | null;
+    expectedSourceConnectionId?: string | null;
   },
   dependencies: {
     readModelFields?: typeof readBuilderCmsModelFields;
@@ -247,7 +276,11 @@ export async function readBuilderCmsEntriesForRoleChange(
   let modelFields: BuilderCmsModelFieldSummary[] = [];
   let modelFieldsError: unknown = null;
   try {
-    modelFields = await readModelFields({ model: args.model });
+    modelFields = await readModelFields({
+      model: args.model,
+      expectedSourceSpace: args.expectedSourceSpace,
+      expectedSourceConnectionId: args.expectedSourceConnectionId,
+    });
   } catch (error) {
     modelFieldsError = error;
   }
@@ -257,14 +290,23 @@ export async function readBuilderCmsEntriesForRoleChange(
       ...(args.existingFieldPaths ?? []),
       ...modelFields.map((field) => `data.${field.name}`),
     ],
+    expectedSourceSpace: args.expectedSourceSpace,
+    expectedSourceConnectionId: args.expectedSourceConnectionId,
+    requireBoundOAuth: true,
   });
   if (modelFieldsError) throw modelFieldsError;
+  if (read.state !== "live") {
+    throw new Error(
+      read.message ??
+        "Builder source could not be read for this role change; no source changes were made.",
+    );
+  }
   return { read, modelFields };
 }
 
 async function readSourceEntries(args: {
   sourceType: ContentDatabaseSourceType;
-  sourceTable: string;
+  source: SourceRecord;
   limit: number;
   offset: number;
 }): Promise<{
@@ -276,7 +318,8 @@ async function readSourceEntries(args: {
 }> {
   if (args.sourceType === "builder-cms") {
     const { read, modelFields } = await readBuilderCmsEntriesForRoleChange({
-      model: args.sourceTable,
+      model: args.source.sourceTable,
+      ...builderSourceReadBinding(args.source),
     });
     return {
       entries: read.state === "live" ? read.entries : [],
@@ -288,7 +331,7 @@ async function readSourceEntries(args: {
   }
   if (args.sourceType === "local-table") {
     const { entries, modelFields } = await readLocalTableEntries(
-      args.sourceTable,
+      args.source.sourceTable,
       { limit: args.limit, offset: args.offset },
     );
     return {
@@ -302,7 +345,7 @@ async function readSourceEntries(args: {
   if (args.sourceType === "notion-database") {
     const read = await getContentDatabaseSourceAdapter("notion-database")!.read(
       {
-        sourceTable: args.sourceTable,
+        sourceTable: args.source.sourceTable,
         limit: args.limit,
         offset: args.offset,
       },
@@ -372,7 +415,7 @@ export default defineAction({
 
       const { entries, modelFields } = await readSourceEntries({
         sourceType: normalizedType,
-        sourceTable: source.sourceTable,
+        source,
         limit: args.limit ?? 100,
         offset: args.offset ?? 0,
       });
@@ -433,6 +476,7 @@ export default defineAction({
           existingFieldPaths: existingSourceFields.map(
             (field) => field.sourceFieldKey,
           ),
+          ...builderSourceReadBinding(source),
         });
       const entries = read.state === "live" ? read.entries : [];
       await db

package/corpus/templates/content/actions/create-content-database.ts

@@ -60,6 +60,7 @@ import {
   seedDefaultBlocksField,
   serializeDatabaseViewConfig,
 } from "./_property-utils.js";
+import { lockParentOfNewPage } from "./_row-lock-order.js";
 
 const createContentDatabaseSchema = z
   .object({
@@ -479,6 +480,7 @@ export async function createContentDatabaseRecord(
     const parentId = args.parentId || null;
     let visibility: "private" | "org" | "public" = "private";
     let hideFromSearch = 0;
+    let parentScope: Parameters<typeof lockParentOfNewPage>[2] | null = null;
 
     if (parentId) {
       const parent = await assertDocumentEditorAccess(db, parentId);
@@ -493,6 +495,12 @@ export async function createContentDatabaseRecord(
       }
       visibility = parent.visibility ?? "private";
       hideFromSearch = parent.hideFromSearch ?? 0;
+      parentScope = {
+        ownerEmail: parent.ownerEmail,
+        spaceId: parent.spaceId ?? null,
+        orgId,
+        visibility: parent.visibility,
+      };
       inheritedShares = await db
         .select({
           principalType: schema.documentShares.principalType,
@@ -572,6 +580,9 @@ export async function createContentDatabaseRecord(
         })),
       );
     }
+    if (parentId && parentScope) {
+      await lockParentOfNewPage(db, parentId, parentScope);
+    }
   }
 
   const databaseId = nanoid();

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

@@ -56,11 +56,13 @@ import {
   documentContentHash,
   documentRevisionToken,
 } from "./_document-edit-mutation.js";
+import { NFM_CONTAINER_SYNTAX } from "./_nfm-syntax.js";
 import {
   documentsPositionScope,
   nextAppendPosition,
   withPositionLock,
 } from "./_position-utils.js";
+import { lockParentOfNewPage } from "./_row-lock-order.js";
 
 type CreationTransactionWrite = {
   documentId: string;
@@ -433,7 +435,8 @@ export default defineAction({
       .optional()
       .describe(
         "Initial Markdown body; omit to create an empty document. Plain Markdown, no admonition/callout " +
-          'shorthand like "> [!TIP]" — use <callout icon="💡">...</callout> with the body indented one tab.',
+          'shorthand like "> [!TIP]" — use a <callout icon="💡"> block. ' +
+          NFM_CONTAINER_SYNTAX,
       ),
     preserveLeadingTitleHeading: z
       .boolean()
@@ -864,6 +867,15 @@ export default defineAction({
           if (scoped?.documentId === id) {
             await scoped.write(tx as unknown as ReturnType<typeof getDb>);
           }
+          if (parentId) {
+            // Last, after the import lock the write above can take, which
+            // undo-import holds while it locks pages.
+            await lockParentOfNewPage(
+              tx as unknown as ReturnType<typeof getDb>,
+              parentId,
+              { ownerEmail, spaceId, orgId, visibility },
+            );
+          }
           return true;
         });
         measurement.outcome = insertedDocument ? "written" : "replayed";

package/corpus/templates/content/actions/delete-content-database.ts

@@ -13,8 +13,9 @@ import {
   setupAuditSummary,
 } from "./_database-setup-mutation.js";
 import {
-  lockDatabasesForTrash,
+  lockLifecycleGroup,
   trashDocumentSubtree,
+  type LifecycleGroupLocks,
 } from "./delete-document.js";
 
 export default defineAction({
@@ -60,7 +61,7 @@ export default defineAction({
       const { database } = await assertContentDatabaseLifecycleAccess(
         input.target.databaseId,
       );
-      let lockedIds: ReadonlySet<string> | undefined;
+      let locks: LifecycleGroupLocks | undefined;
       const result = await runDatabaseSetupMutation({
         operation: "delete-content-database",
         input,
@@ -68,11 +69,13 @@ export default defineAction({
         role: "admin",
         includeDeleted: true,
         lock: async (tx) => {
-          lockedIds = await lockDatabasesForTrash(
-            tx,
-            database.documentId,
-            database.ownerEmail,
-          );
+          locks = await lockLifecycleGroup(tx, {
+            operation: "trash",
+            roots: [
+              { id: database.documentId, ownerEmail: database.ownerEmail },
+            ],
+            alsoLockDatabaseIds: [database.id],
+          });
         },
         apply: async (tx, context) => {
           if (context.database.ownerDocumentId)
@@ -90,7 +93,7 @@ export default defineAction({
                 context.database.documentId,
                 context.database.ownerEmail,
                 deletedAt,
-                lockedIds,
+                locks!,
               );
           return {
             outcome: context.database.deletedAt
@@ -120,17 +123,17 @@ export default defineAction({
     const deletedAt = database.deletedAt ?? new Date().toISOString();
     const deletedDocumentIds = await db.transaction(async (tx) => {
       const transactionDb = tx as unknown as ReturnType<typeof getDb>;
-      const lockedDatabaseIds = await lockDatabasesForTrash(
-        transactionDb,
-        database.documentId,
-        database.ownerEmail,
-      );
+      const locks = await lockLifecycleGroup(transactionDb, {
+        operation: "trash",
+        roots: [{ id: database.documentId, ownerEmail: database.ownerEmail }],
+        alsoLockDatabaseIds: [database.id],
+      });
       return trashDocumentSubtree(
         transactionDb,
         database.documentId,
         database.ownerEmail,
         deletedAt,
-        lockedDatabaseIds,
+        locks,
       );
     });
 

package/corpus/templates/content/actions/delete-document-property.ts

@@ -25,6 +25,7 @@ import {
   resolvePropertyDatabaseForDocument,
   serializeDatabaseViewConfig,
 } from "./_property-utils.js";
+import { lockDocumentRows } from "./_row-lock-order.js";
 
 export default defineAction({
   description:
@@ -197,6 +198,10 @@ export default defineAction({
             .map((item) => item.documentId);
           if (documentsWithoutSurvivingPrimary.length > 0) {
             const now = new Date().toISOString();
+            await lockDocumentRows(
+              tx as unknown as ReturnType<typeof getDb>,
+              documentsWithoutSurvivingPrimary,
+            );
             await tx
               .update(schema.documents)
               .set({