@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/content/actions/_document-save-locks.ts

@@ -0,0 +1,54 @@
+import { eq } from "drizzle-orm";
+
+import { schema, type getDb } from "../server/db/index.js";
+import {
+  lockDocumentBodyDatabases,
+  lockDocumentMetadataDatabase,
+} from "../server/lib/document-metadata-updated-at.js";
+import { lockDatabaseMemberships } from "./_database-membership-lock.js";
+import { lockDocumentRows } from "./_row-lock-order.js";
+
+/**
+ * Locks a page for a save in Content's row-lock order (`_row-lock-order.ts`):
+ * the collection the page backs and, for a body write, the inline collections
+ * it owns, in one id-ordered pass; then its memberships; then the page row.
+ * Taking the inline collections in a separate pass would hold one out of
+ * order against the page's own collection.
+ *
+ * Returns the id of the collection the page backs, or null, and every
+ * collection and membership it locked. Pass `lockedDatabaseIds` to the
+ * inline-collection reconcile and `lockedMembershipIds` to
+ * `lockPrimaryBlocksFields` as `heldMembershipIds`: both refuse a row added
+ * after this ran rather than lock it after the page.
+ */
+export async function lockDocumentForSave(
+  db: ReturnType<typeof getDb>,
+  args: { documentId: string; ownerEmail: string; body: boolean },
+): Promise<{
+  databaseId: string | null;
+  lockedDatabaseIds: ReadonlySet<string>;
+  lockedMembershipIds: ReadonlySet<string>;
+}> {
+  const scope = {
+    db,
+    documentId: args.documentId,
+    ownerEmail: args.ownerEmail,
+  };
+  const locked = args.body
+    ? await lockDocumentBodyDatabases(scope)
+    : await lockDocumentMetadataDatabase(scope).then((databaseId) => ({
+        databaseId,
+        lockedDatabaseIds: new Set(databaseId ? [databaseId] : []),
+      }));
+  const membershipIds = args.body
+    ? (
+        await db
+          .select({ id: schema.contentDatabaseItems.id })
+          .from(schema.contentDatabaseItems)
+          .where(eq(schema.contentDatabaseItems.documentId, args.documentId))
+      ).map((membership) => membership.id)
+    : [];
+  await lockDatabaseMemberships(db, membershipIds);
+  await lockDocumentRows(db, [args.documentId]);
+  return { ...locked, lockedMembershipIds: new Set(membershipIds) };
+}

package/corpus/templates/content/actions/_document-save-row.ts

@@ -0,0 +1,133 @@
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  documentContentHash,
+  parseDocumentRevisionToken,
+} from "../server/lib/document-revision.js";
+import type { ClaimedEditorSave } from "../shared/editor-save-state.js";
+
+export type DocumentSaveRow = {
+  bodyRevision: number;
+  content: string;
+  title: string;
+  updatedAt: string;
+};
+
+export async function readDocumentSaveRow(
+  documentId: string,
+): Promise<DocumentSaveRow | null> {
+  // guard:allow-unscoped — every barrier caller authorizes the document first and rechecks access before returning the captured content.
+  const [row] = await getDb()
+    .select({
+      bodyRevision: schema.documents.bodyRevision,
+      content: schema.documents.content,
+      title: schema.documents.title,
+      updatedAt: schema.documents.updatedAt,
+    })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, documentId))
+    .limit(1);
+  return row ?? null;
+}
+
+// True only when SQL is at or past the save an editor reports: the same body
+// revision with the same text, or a later one, and the same title or a title
+// another writer saved after it. Anything else, including a claim SQL has not
+// reached yet, means the editor must be asked to save.
+export function editorSaveIsInSql(
+  row: DocumentSaveRow,
+  claim: ClaimedEditorSave,
+  contentHash = documentContentHash(row.content),
+): boolean {
+  const claimed = parseDocumentRevisionToken(claim.revision);
+  if (!claimed || row.bodyRevision < claimed.revision) return false;
+  if (
+    row.bodyRevision === claimed.revision &&
+    contentHash !== claimed.contentHash
+  ) {
+    return false;
+  }
+  if (row.title === claim.title) return true;
+  if (claim.titleUpdatedAt === null) return false;
+  const sqlUpdatedAt = Date.parse(row.updatedAt);
+  const claimUpdatedAt = Date.parse(claim.titleUpdatedAt);
+  return (
+    Number.isFinite(sqlUpdatedAt) &&
+    Number.isFinite(claimUpdatedAt) &&
+    sqlUpdatedAt > claimUpdatedAt
+  );
+}
+
+export type DocumentFlushSnapshot =
+  | (DocumentSaveRow & { kind: "document"; contentHash: string })
+  | {
+      kind: "property";
+      propertyId: string;
+      content: string;
+      title: string;
+      updatedAt: string;
+      contentHash: string;
+    };
+
+export function createDocumentFlushCapture() {
+  const bodies = new Map<number, { content: string; contentHash: string }>();
+  return async (
+    documentId: string,
+    propertyId?: string,
+  ): Promise<DocumentFlushSnapshot | null> => {
+    if (propertyId) {
+      // guard:allow-unscoped — the caller authorizes the exact document/property before the barrier and rechecks access before returning its captured value.
+      const [row] = await getDb()
+        .select({
+          title: schema.documents.title,
+          updatedAt: schema.documents.updatedAt,
+          content: schema.documentBlockFieldContents.content,
+        })
+        .from(schema.documents)
+        .leftJoin(
+          schema.documentBlockFieldContents,
+          and(
+            eq(
+              schema.documentBlockFieldContents.documentId,
+              schema.documents.id,
+            ),
+            eq(schema.documentBlockFieldContents.propertyId, propertyId),
+          ),
+        )
+        .where(eq(schema.documents.id, documentId))
+        .limit(1);
+      if (!row) return null;
+      const content = row.content ?? "";
+      return {
+        ...row,
+        content,
+        kind: "property",
+        propertyId,
+        contentHash: documentContentHash(content),
+      };
+    }
+
+    // guard:allow-unscoped — document access is established by every barrier caller; this metadata read avoids reloading a previously captured immutable body revision.
+    const [metadata] = await getDb()
+      .select({
+        bodyRevision: schema.documents.bodyRevision,
+        title: schema.documents.title,
+        updatedAt: schema.documents.updatedAt,
+      })
+      .from(schema.documents)
+      .where(eq(schema.documents.id, documentId))
+      .limit(1);
+    if (!metadata) return null;
+    const cached = bodies.get(metadata.bodyRevision);
+    if (cached) return { ...metadata, ...cached, kind: "document" };
+    const row = await readDocumentSaveRow(documentId);
+    if (!row) return null;
+    const body = {
+      content: row.content,
+      contentHash: documentContentHash(row.content),
+    };
+    bodies.set(row.bodyRevision, body);
+    return { ...row, kind: "document", contentHash: body.contentHash };
+  };
+}

package/corpus/templates/content/actions/_github-source-freshness.ts

@@ -26,6 +26,12 @@ export const GITHUB_SOURCE_STALE_MS = 60_000;
 const READ_SYNC_BUDGET_MS = 3_000;
 /** One link's share of a background sync, which has 90 seconds in all. */
 const SWEEP_SYNC_BUDGET_MS = 20_000;
+/**
+ * The share of a link partway through a push, like a big folder's first fill.
+ * It stops before the next background sync starts a minute later, so that one
+ * finds the link free and carries the push on.
+ */
+const SWEEP_PUSH_BUDGET_MS = 50_000;
 /** Links the background sync checks at once. */
 const SWEEP_CONCURRENCY = 4;
 /** The background sync skips links a read or another sync checked this recently. */
@@ -274,10 +280,25 @@ export async function runGitHubSourceSweep(context: RecurringSweepContext) {
       asc(sql`coalesce(${schema.contentDatabaseSources.lastRefreshedAt}, '')`),
     )
     .limit(SWEEP_MAX_LINKS);
+  // A link partway through a push goes after the rest, so a big folder's
+  // first fill doesn't hold up a push to a small one. Those links take turns
+  // by when a run last moved their push, oldest first. The query's order
+  // can't do that: a run partway through isn't a check, so it leaves
+  // lastRefreshedAt as it was, and the same link would go first every time.
+  const carrying = new Set(
+    due
+      .map((link) => ({ link, state: linkState(link.metadataJson) }))
+      .filter(({ state }) => state?.pendingCommitSha)
+      .sort((a, b) =>
+        (a.state?.checkedAt ?? "").localeCompare(b.state?.checkedAt ?? ""),
+      )
+      .map(({ link }) => link),
+  );
+  const order = [...due.filter((link) => !carrying.has(link)), ...carrying];
   let next = 0;
   const worker = async () => {
-    while (next < due.length) {
-      const link = due[next++]!;
+    while (next < order.length) {
+      const link = order[next++]!;
       const remaining = context.deadlineAt - Date.now();
       if (context.signal?.aborted || remaining < 2_000) return;
       const owner = linkedBy(link);
@@ -288,7 +309,12 @@ export async function runGitHubSourceSweep(context: RecurringSweepContext) {
           () =>
             syncGitHubSource({
               sourceId: link.sourceId,
-              budgetMs: Math.min(SWEEP_SYNC_BUDGET_MS, remaining - 1_000),
+              budgetMs: Math.min(
+                carrying.has(link)
+                  ? SWEEP_PUSH_BUDGET_MS
+                  : SWEEP_SYNC_BUDGET_MS,
+                remaining - 1_000,
+              ),
               signal: context.signal,
             }),
         );
@@ -303,6 +329,6 @@ export async function runGitHubSourceSweep(context: RecurringSweepContext) {
     }
   };
   await Promise.all(
-    Array.from({ length: Math.min(SWEEP_CONCURRENCY, due.length) }, worker),
+    Array.from({ length: Math.min(SWEEP_CONCURRENCY, order.length) }, worker),
   );
 }

package/corpus/templates/content/actions/_github-source.ts

@@ -90,7 +90,7 @@ import {
   withPositionLock,
 } from "./_position-utils.js";
 import { nanoid } from "./_property-utils.js";
-import { trashDocumentSubtree } from "./delete-document.js";
+import { lockLifecycleGroup, trashDocumentSubtree } from "./delete-document.js";
 
 type Db = ReturnType<typeof getDb>;
 type DatabaseRow = typeof schema.contentDatabases.$inferSelect;
@@ -1542,23 +1542,33 @@ async function recordStillLinked(tx: Db, row: SourceRow) {
  */
 async function trashRow(run: SyncRun, row: SourceRow): Promise<boolean> {
   return run.db.transaction(async (tx: Db) => {
+    const { ownerEmail } = run.database;
+    // The page's other collections may sort before this one, so the whole
+    // group is locked in order before the link check takes this collection.
+    const locks = await lockLifecycleGroup(tx, {
+      operation: "trash",
+      roots: [{ id: row.documentId, ownerEmail }],
+      alsoLockDatabaseIds: [run.database.id],
+    });
     await lockLinkedCollection(tx, run);
     if (!(await recordStillLinked(tx, row))) return false;
     const [document] = await tx
-      .select({
-        ownerEmail: schema.documents.ownerEmail,
-        trashedAt: schema.documents.trashedAt,
-      })
+      .select({ trashedAt: schema.documents.trashedAt })
       .from(schema.documents)
-      .where(eq(schema.documents.id, row.documentId));
+      .where(
+        and(
+          eq(schema.documents.id, row.documentId),
+          eq(schema.documents.ownerEmail, ownerEmail),
+        ),
+      );
     let moved = false;
     if (document && !document.trashedAt) {
       await trashDocumentSubtree(
         tx,
         row.documentId,
-        document.ownerEmail,
+        ownerEmail,
         run.now,
-        undefined,
+        locks,
         "github",
       );
       moved = true;

package/corpus/templates/content/actions/_move-page-to-space.ts

@@ -6,6 +6,7 @@ import { getDb, schema } from "../server/db/index.js";
 import { blocksFieldId } from "../shared/blocks-field-identity.js";
 import { reconcileDocuments } from "./_content-files.js";
 import { resolveContentSpaceTarget } from "./_content-space-target.js";
+import { lockDatabaseMemberships } from "./_database-membership-lock.js";
 import { assertDocumentMutationAccess } from "./_document-mutation-access.js";
 import {
   assertSubtreeCanChangeSpace,
@@ -17,6 +18,11 @@ import {
   nextAppendPosition,
   withPositionLock,
 } from "./_position-utils.js";
+import {
+  lockDocumentRows,
+  lockOwnerPageTree,
+  sortRowIds,
+} from "./_row-lock-order.js";
 
 type ContentDb = ReturnType<typeof getDb>;
 type ContentTx = Parameters<Parameters<ContentDb["transaction"]>[0]>[0];
@@ -85,6 +91,152 @@ async function rekeyPrimaryBlocksFields(args: {
   }
 }
 
+async function membershipIdsOf(tx: ContentDb, documentIds: string[]) {
+  const membershipIds: string[] = [];
+  for (const idGroup of groups(documentIds)) {
+    const memberships: Array<{ id: string }> = await tx
+      .select({ id: schema.contentDatabaseItems.id })
+      .from(schema.contentDatabaseItems)
+      .where(inArray(schema.contentDatabaseItems.documentId, idGroup));
+    membershipIds.push(...memberships.map((membership) => membership.id));
+  }
+  return membershipIds;
+}
+
+async function readLockedPages(tx: ContentDb, ids: string[]) {
+  const pages: PageSubtreeDocument[] = [];
+  for (const idGroup of groups(ids)) {
+    // guard:allow-unscoped — re-reads pages the move already access-checked and holds locked.
+    pages.push(
+      ...(await tx
+        .select()
+        .from(schema.documents)
+        .where(inArray(schema.documents.id, idGroup))),
+    );
+  }
+  return pages;
+}
+
+/** A page read under the root that has since left it would move with it. */
+function pagesLeftSubtree(
+  lockedPages: PageSubtreeDocument[],
+  rootId: string,
+  ids: string[],
+) {
+  const idSet = new Set(ids);
+  const pages = new Map(lockedPages.map((page) => [page.id, page]));
+  return ids.some((id) => {
+    if (id === rootId) return false;
+    const page = pages.get(id);
+    return (
+      !page ||
+      !(
+        (page.parentId && idSet.has(page.parentId)) ||
+        (page.trashParentId && idSet.has(page.trashParentId))
+      )
+    );
+  });
+}
+
+/**
+ * Locks a move between spaces in the global order and re-checks what the move
+ * read before it. The pages leave their owner's tree for the mover's, so a
+ * move the other way could close a cycle through either tree. Edits lock a
+ * page's Files membership before the page, and this move deletes it.
+ */
+async function lockMoveBetweenSpaces(args: {
+  tx: ContentDb;
+  root: PageSubtreeDocument;
+  ids: string[];
+  spaceId: string;
+  parentId: string | null;
+  userEmail: string;
+}) {
+  const { tx, root, ids, spaceId, parentId, userEmail } = args;
+  for (const ownerEmail of sortRowIds([root.ownerEmail as string, userEmail])) {
+    await lockOwnerPageTree(tx, ownerEmail);
+  }
+  const membershipIds = await membershipIdsOf(tx, ids);
+  await lockDatabaseMemberships(tx, membershipIds);
+  await lockDocumentRows(tx, parentId ? [...ids, parentId] : ids);
+  const lockedMembershipIds = new Set(membershipIds);
+  const lockedPages = await readLockedPages(tx, ids);
+  if (
+    (await membershipIdsOf(tx, ids)).some(
+      (id) => !lockedMembershipIds.has(id),
+    ) ||
+    pagesLeftSubtree(lockedPages, root.id, ids)
+  ) {
+    throw contractError(
+      "This page changed while it was being moved. Try again.",
+      "PAGE_SUBTREE_CHANGED",
+    );
+  }
+  // A page turned into a collection while the move waited would leave the
+  // collection behind in the old space.
+  await assertSubtreeCanChangeSpace(tx, lockedPages);
+
+  const [current] = await tx
+    .select({
+      spaceId: schema.documents.spaceId,
+      ownerEmail: schema.documents.ownerEmail,
+      trashedAt: schema.documents.trashedAt,
+    })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, root.id));
+  if (!current || current.trashedAt) {
+    throw contractError("Document not found.", "DOCUMENT_NOT_FOUND", 404);
+  }
+  if (
+    current.spaceId !== root.spaceId ||
+    current.ownerEmail !== root.ownerEmail
+  ) {
+    throw contractError(
+      "The document's move scope changed. Read it again and retry.",
+      "DOCUMENT_MOVE_SCOPE_CHANGED",
+    );
+  }
+  // The move gives every page to the mover and drops its shares, which a
+  // revoke's own access check reads, so access is read again under the locks.
+  // A page the mover owns skips it: the check returns owner before reading
+  // any share, and only a write that waits on this page's lock changes owner.
+  const moverEmail = getRequestUserEmail()?.trim().toLowerCase();
+  const pages = new Map(lockedPages.map((page) => [page.id, page]));
+  for (const id of ids) {
+    const ownerEmail = pages.get(id)?.ownerEmail?.trim().toLowerCase();
+    if (moverEmail && ownerEmail === moverEmail) continue;
+    await assertDocumentMutationAccess(id, "editor", "id");
+  }
+  if (!parentId) return null;
+  const [parent] = await tx
+    .select({
+      spaceId: schema.documents.spaceId,
+      ownerEmail: schema.documents.ownerEmail,
+      trashedAt: schema.documents.trashedAt,
+      orgId: schema.documents.orgId,
+      visibility: schema.documents.visibility,
+    })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, parentId));
+  if (!parent) {
+    throw contractError(
+      "Parent document not found.",
+      "DOCUMENT_NOT_FOUND",
+      404,
+    );
+  }
+  if (parent.trashedAt) {
+    throw contractError("Parent document is in Trash", "PARENT_TRASHED");
+  }
+  if (parent.spaceId !== spaceId || parent.ownerEmail !== userEmail) {
+    throw contractError(
+      "The document's move scope changed. Read it again and retry.",
+      "DOCUMENT_MOVE_SCOPE_CHANGED",
+    );
+  }
+  return parent;
+}
+
 export async function movePageToSpace(args: {
   root: PageSubtreeDocument;
   spaceId: string;
@@ -150,12 +302,6 @@ export async function movePageToSpace(args: {
     if (parent.trashedAt) {
       throw contractError("Parent document is in Trash", "PARENT_TRASHED");
     }
-    orgId = parent.orgId ?? null;
-    visibility = parent.visibility as typeof visibility;
-    parentShares = await db
-      .select()
-      .from(schema.documentShares)
-      .where(eq(schema.documentShares.resourceId, parentId));
   }
 
   const filesDatabases = await db
@@ -222,26 +368,44 @@ export async function movePageToSpace(args: {
   await withPositionLock(
     documentsPositionScope(userEmail, parentId),
     async () => {
-      const [maxPosition] = await db
-        .select({ max: sql<unknown>`COALESCE(MAX(position), -1)` })
-        .from(schema.documents)
-        .where(
-          parentId
-            ? and(
-                eq(schema.documents.ownerEmail, userEmail),
-                eq(schema.documents.parentId, parentId),
-              )
-            : and(
-                eq(schema.documents.ownerEmail, userEmail),
-                eq(schema.documents.visibility, visibility),
-                orgId
-                  ? eq(schema.documents.orgId, orgId)
-                  : isNull(schema.documents.orgId),
-                isNull(schema.documents.parentId),
-              ),
-        );
-
       await db.transaction(async (tx) => {
+        const parent = await lockMoveBetweenSpaces({
+          tx: tx as unknown as ContentDb,
+          root,
+          ids,
+          spaceId,
+          parentId,
+          userEmail,
+        });
+        // Read under the parent's lock: the subtree takes the parent's access.
+        if (parent && parentId) {
+          orgId = parent.orgId ?? null;
+          visibility = parent.visibility as typeof visibility;
+          parentShares = await tx
+            .select()
+            .from(schema.documentShares)
+            .where(eq(schema.documentShares.resourceId, parentId));
+        }
+        // Under the mover's page-tree lock, which every move into the
+        // mover's pages takes, so two appends can't take one position.
+        const [maxPosition] = await tx
+          .select({ max: sql<unknown>`COALESCE(MAX(position), -1)` })
+          .from(schema.documents)
+          .where(
+            parentId
+              ? and(
+                  eq(schema.documents.ownerEmail, userEmail),
+                  eq(schema.documents.parentId, parentId),
+                )
+              : and(
+                  eq(schema.documents.ownerEmail, userEmail),
+                  eq(schema.documents.visibility, visibility),
+                  orgId
+                    ? eq(schema.documents.orgId, orgId)
+                    : isNull(schema.documents.orgId),
+                  isNull(schema.documents.parentId),
+                ),
+          );
         const idSet = new Set(ids);
         for (const idGroup of groups(ids)) {
           const children: Array<{ id: string }> = await tx

package/corpus/templates/content/actions/_nfm-syntax.ts

@@ -0,0 +1,2 @@
+export const NFM_CONTAINER_SYNTAX =
+  'Children of <callout>, <details>, <columns>, <column>, and <synced_block> sit one tab deeper than their tags, as in <callout icon="💡">\n\tText\n</callout>; a <details> keeps its <summary> line at the tags\' indent.';

package/corpus/templates/content/actions/_row-lock-order.ts

@@ -0,0 +1,115 @@
+import { ActionContractError } from "@agent-native/core/action";
+import { eq, inArray, sql } from "drizzle-orm";
+
+import { getDb, schema } from "../server/db/index.js";
+import { chunks } from "./_batch-utils.js";
+
+/**
+ * Content locks rows in one order: collections, then memberships, then pages,
+ * each by id in byte order. Two transactions that both follow it never wait on
+ * each other in a cycle, so PostgreSQL never aborts one with 40P01. A write
+ * that locks a row implicitly (an UPDATE) counts: lock the row in order first.
+ *
+ * Byte order, not the database collation: JavaScript sorts and
+ * `COLLATE "C"` agree on it, so ids sorted here lock in the same sequence as
+ * ids sorted by PostgreSQL.
+ */
+export function compareRowIds(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+
+export function sortRowIds(ids: Iterable<string>): string[] {
+  return [...new Set(ids)].sort(compareRowIds);
+}
+
+/**
+ * Serializes reparents within one owner's page tree. A move checks that its new
+ * parent is not under the moved page, but two moves whose row locks don't
+ * overlap (P under S while R under Q, where Q is under P and S under R) would
+ * each pass that check before the other commits, and together make a cycle.
+ * Take it before any row lock; nothing that holds a row lock waits on it.
+ */
+export async function lockOwnerPageTree(
+  db: ReturnType<typeof getDb>,
+  ownerEmail: string,
+) {
+  await db.execute(
+    sql`SELECT pg_advisory_xact_lock(hashtextextended(${`content-page-tree:${ownerEmail}`}, 0::bigint))`,
+  );
+}
+
+/**
+ * Re-reads a new page's parent with a share lock, and refuses when the parent
+ * moved to Trash or changed owner, space, org or visibility since the page
+ * copied them. A move or Trash of the parent holds its row until it commits,
+ * so this reads the result. A Trash or a move to another space that locks the
+ * parent after this sees the new page when it re-reads the parent's children
+ * under its locks. Take it last in the creating transaction.
+ */
+export async function lockParentOfNewPage(
+  db: ReturnType<typeof getDb>,
+  parentId: string,
+  expected: {
+    ownerEmail: string;
+    spaceId: string | null;
+    orgId: string | null;
+    visibility: string;
+  },
+) {
+  // guard:allow-unscoped — re-reads the parent the caller already access-checked, to refuse a create it moved away from.
+  const [parent] = await db
+    .select({
+      ownerEmail: schema.documents.ownerEmail,
+      spaceId: schema.documents.spaceId,
+      orgId: schema.documents.orgId,
+      visibility: schema.documents.visibility,
+      trashedAt: schema.documents.trashedAt,
+    })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, parentId))
+    .for("share");
+  if (!parent) {
+    throw new ActionContractError("Parent document not found.", {
+      errorCode: "DOCUMENT_NOT_FOUND",
+      statusCode: 404,
+    });
+  }
+  if (parent.trashedAt) {
+    throw new ActionContractError("Parent document is in Trash", {
+      errorCode: "PARENT_TRASHED",
+      statusCode: 409,
+    });
+  }
+  if (
+    parent.ownerEmail !== expected.ownerEmail ||
+    (parent.spaceId ?? null) !== expected.spaceId ||
+    (parent.orgId ?? null) !== expected.orgId ||
+    parent.visibility !== expected.visibility
+  ) {
+    throw new ActionContractError(
+      "The parent page moved or changed access while this page was being created. Read it again and retry.",
+      { errorCode: "PARENT_SCOPE_CHANGED", statusCode: 409 },
+    );
+  }
+}
+
+const LOCK_BATCH_SIZE = 90;
+
+/** Locks the page rows that exist, in id order, and returns their ids. */
+export async function lockDocumentRows(
+  db: ReturnType<typeof getDb>,
+  documentIds: Iterable<string>,
+): Promise<string[]> {
+  const locked: string[] = [];
+  for (const batch of chunks(sortRowIds(documentIds), LOCK_BATCH_SIZE)) {
+    // guard:allow-unscoped — takes row locks on ids the caller already resolved under its access check and returns only those ids.
+    const rows = await db
+      .select({ id: schema.documents.id })
+      .from(schema.documents)
+      .where(inArray(schema.documents.id, batch))
+      .orderBy(sql`${schema.documents.id} COLLATE "C"`)
+      .for("update");
+    locked.push(...rows.map((row) => row.id));
+  }
+  return locked;
+}