@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/content/actions/_blocks-field-identity.ts

@@ -1,3 +1,4 @@
+import { ActionContractError } from "@agent-native/core";
 import { and, asc, eq, inArray } from "drizzle-orm";
 
 import { getDb, schema } from "../server/db/index.js";
@@ -70,17 +71,28 @@ function groups<T>(values: T[], size: number): T[][] {
 export async function lockPrimaryBlocksFields(
   db: ContentDb,
   documentId: string,
+  options: LockPrimaryBlocksFieldsOptions = {},
 ): Promise<PrimaryBlocksField[]> {
   return (
-    (await lockPrimaryBlocksFieldsForDocuments(db, [documentId])).get(
+    (await lockPrimaryBlocksFieldsForDocuments(db, [documentId], options)).get(
       documentId,
     ) ?? []
   );
 }
 
+interface LockPrimaryBlocksFieldsOptions {
+  /**
+   * Memberships the caller locked before the page. Any other membership was
+   * added since, and locking it after the page deadlocks against an edit or
+   * restore that locks memberships first, so it is refused instead.
+   */
+  heldMembershipIds?: ReadonlySet<string>;
+}
+
 export async function lockPrimaryBlocksFieldsForDocuments(
   db: ContentDb,
   documentIds: string[],
+  options: LockPrimaryBlocksFieldsOptions = {},
 ): Promise<Map<string, PrimaryBlocksField[]>> {
   const uniqueDocumentIds = [...new Set(documentIds)];
   const memberships: Array<{
@@ -101,6 +113,13 @@ export async function lockPrimaryBlocksFieldsForDocuments(
     );
   }
   const membershipIds = memberships.map((membership) => membership.id);
+  const held = options.heldMembershipIds;
+  if (held && membershipIds.some((membershipId) => !held.has(membershipId))) {
+    throw new ActionContractError(
+      "The document was added to a collection while it saved. Read the document again and retry.",
+      { errorCode: "DOCUMENT_METADATA_SCOPE_CHANGED", statusCode: 409 },
+    );
+  }
   await lockDatabaseMemberships(db, membershipIds);
   if (membershipIds.length === 0) return new Map();
 
@@ -285,6 +304,11 @@ export async function persistBlocksFieldIdentity(args: {
   propertyId: string;
   previousMarkdown: string;
   markdown: string;
+  /**
+   * Markdown between previousMarkdown and markdown, in order. Block IDs follow
+   * each one in turn, as if each had been saved.
+   */
+  intermediateMarkdown?: readonly string[];
   expectedRevision?: number;
   preferredIdsByPath?: Readonly<Record<string, string>>;
   rejectCrossFieldIdRemapping?: boolean;
@@ -320,6 +344,16 @@ export async function persistBlocksFieldIdentity(args: {
     });
   }
 
+  for (const markdown of args.intermediateMarkdown ?? []) {
+    previous = reconcileBlocksFieldIdentity({
+      documentId: args.documentId,
+      propertyId: args.propertyId,
+      previous,
+      markdown,
+      createId: () => `block_${nanoid(16)}`,
+    });
+  }
+
   let next = reconcileBlocksFieldIdentity({
     documentId: args.documentId,
     propertyId: args.propertyId,

package/corpus/templates/content/actions/_content-database-lifecycle.ts

@@ -1,3 +1,4 @@
+import { ActionContractError } from "@agent-native/core";
 import { assertAccess, resolveAccess } from "@agent-native/core/sharing";
 import { and, eq, inArray, isNull } from "drizzle-orm";
 
@@ -126,23 +127,14 @@ export async function collectInlineDatabaseOwnerBlockIds(
   return { ok: true, ownerBlockIds };
 }
 
-export async function reconcileInlineDatabasesForDocument(
-  documentId: string,
-  content: string,
-): Promise<string[]> {
-  return reconcileInlineDatabasesForDocumentWithDb({
-    db: getDb(),
-    documentId,
-    content,
-  });
-}
-
 export async function reconcileInlineDatabasesForDocumentWithDb(args: {
   db: ReturnType<typeof getDb>;
   documentId: string;
   content: string;
   ownerEmail?: string;
   now?: string;
+  /** The collections `lockDocumentForSave` locked before the page. */
+  lockedDatabaseIds: ReadonlySet<string>;
 }): Promise<string[]> {
   const parsed = await collectInlineDatabaseOwnerBlockIds(args.content);
   if (!parsed.ok) return [];
@@ -177,6 +169,14 @@ export async function reconcileInlineDatabasesForDocumentWithDb(args: {
     );
 
   if (missing.length === 0) return [];
+  // Created after the caller locked its collections. Locking it now, after the
+  // page, deadlocks against a Trash of the page, which locks it first.
+  if (missing.some((database) => !args.lockedDatabaseIds.has(database.id))) {
+    throw new ActionContractError(
+      "An inline collection was added to the document while it saved. Read the document again and retry.",
+      { errorCode: "DOCUMENT_METADATA_SCOPE_CHANGED", statusCode: 409 },
+    );
+  }
 
   const now = args.now ?? new Date().toISOString();
   const ids = missing.map((database) => database.id);

package/corpus/templates/content/actions/_content-database-personal-view.ts

@@ -30,6 +30,8 @@ export const filterSchema = z.object({
   value: z.string(),
   filterGroupId: z.string().optional(),
   parentFilterGroupId: z.string().optional(),
+  filterGroupMode: z.enum(["and", "or"]).optional(),
+  parentFilterGroupMode: z.enum(["and", "or"]).optional(),
 });
 
 const sidebarOrderItemIdSchema = z.string().min(1).max(256);

package/corpus/templates/content/actions/_content-favorites.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 
+import { ActionContractError } from "@agent-native/core/action";
 import { and, eq, inArray, sql } from "drizzle-orm";
 
 import { schema } from "../server/db/index.js";
@@ -46,6 +47,24 @@ export async function favoriteDocumentIds(
   return new Set(rows.map((row: { documentId: string }) => row.documentId));
 }
 
+export async function favoriteMembershipIds(
+  db: Db,
+  userEmail: string,
+  documentId: string,
+): Promise<string[]> {
+  const favoritesDatabaseId = favoritesSystemIds(userEmail).databaseId;
+  const rows = await db
+    .select({ id: schema.contentDatabaseItems.id })
+    .from(schema.contentDatabaseItems)
+    .where(
+      and(
+        eq(schema.contentDatabaseItems.databaseId, favoritesDatabaseId),
+        eq(schema.contentDatabaseItems.documentId, documentId),
+      ),
+    );
+  return rows.map((row: { id: string }) => row.id);
+}
+
 export async function setFavoriteMembership(args: {
   db: Db;
   userEmail: string;
@@ -92,6 +111,24 @@ export async function setFavoriteMembership(args: {
       previous: existing,
     };
 
+  // Trash, restore and permanent delete read and rewrite a page's
+  // memberships while they hold its row, and nothing else stops a favorite
+  // being added meanwhile: no collection lock covers Favorites. Outside a
+  // transaction this lock ends before the insert, so callers run this in one.
+  // A save locks the membership before the page, so a removal must not take
+  // this lock, and a caller holding the page locks the membership first.
+  // guard:allow-unscoped — the caller already access-checked the page; this waits out its lifecycle writes.
+  const [page] = await args.db
+    .select({ id: schema.documents.id })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, args.documentId))
+    .for("share");
+  if (!page) {
+    throw new ActionContractError("Document not found.", {
+      errorCode: "DOCUMENT_NOT_FOUND",
+      statusCode: 404,
+    });
+  }
   const [position] = await args.db
     .select({ max: sql<unknown>`COALESCE(MAX(position), -1)` })
     .from(schema.contentDatabaseItems)

package/corpus/templates/content/actions/_database-membership-lock.ts

@@ -1,25 +1,56 @@
+import { ActionContractError } from "@agent-native/core/action";
 import { inArray, sql } from "drizzle-orm";
 
 import { schema } from "../server/db/index.js";
 import { chunks } from "./_batch-utils.js";
+import { sortRowIds } from "./_row-lock-order.js";
 
 export async function lockDatabaseMemberships(db: any, itemIds: string[]) {
-  const uniqueItemIds = [...new Set(itemIds)].sort();
-  if (uniqueItemIds.length === 0) return;
+  const uniqueItemIds = sortRowIds(itemIds);
+  const lockedIds = await lockExistingDatabaseMemberships(db, uniqueItemIds);
+  if (lockedIds.size !== uniqueItemIds.length) {
+    throw new ActionContractError(
+      "Database memberships changed before the operation completed.",
+      { errorCode: "DATABASE_MEMBERSHIPS_CHANGED", statusCode: 409 },
+    );
+  }
+}
+
+/**
+ * For writers that report a missing membership themselves: locks those that
+ * still exist, in the same order, and returns their ids.
+ */
+export async function lockExistingDatabaseMemberships(
+  db: any,
+  itemIds: string[],
+): Promise<Set<string>> {
+  const uniqueItemIds = sortRowIds(itemIds);
   const lockedIds = new Set<string>();
   for (const itemIdChunk of chunks(uniqueItemIds, 90)) {
+    // The sub-select takes the row locks in id order; an UPDATE alone would
+    // take them in whatever order its scan visits the rows. It stays an
+    // UPDATE for its ROW EXCLUSIVE table lock: suggestion acceptance locks a
+    // page, then refuses with `LOCK TABLE ... SHARE ROW EXCLUSIVE NOWAIT`
+    // while anyone may hold a membership, and a locking SELECT's ROW SHARE
+    // doesn't conflict with that.
     const lockedRows = await db
       .update(schema.contentDatabaseItems)
       .set({
         updatedAt: sql`${schema.contentDatabaseItems.updatedAt}`,
       })
-      .where(inArray(schema.contentDatabaseItems.id, itemIdChunk))
+      .where(
+        inArray(
+          schema.contentDatabaseItems.id,
+          db
+            .select({ id: schema.contentDatabaseItems.id })
+            .from(schema.contentDatabaseItems)
+            .where(inArray(schema.contentDatabaseItems.id, itemIdChunk))
+            .orderBy(sql`${schema.contentDatabaseItems.id} COLLATE "C"`)
+            .for("no key update"),
+        ),
+      )
       .returning({ id: schema.contentDatabaseItems.id });
     for (const row of lockedRows) lockedIds.add(row.id);
   }
-  if (lockedIds.size !== uniqueItemIds.length) {
-    throw new Error(
-      "Database memberships changed before the operation completed.",
-    );
-  }
+  return lockedIds;
 }

package/corpus/templates/content/actions/_database-navigation.ts

@@ -29,7 +29,11 @@ import type {
   ContentDatabaseNavigationSort,
   ContentDatabasePersonalViewOverrides,
 } from "../shared/api.js";
-import { contentDatabaseFilterOperatorNeedsValue } from "../shared/database-query.js";
+import {
+  contentDatabaseFilterOperatorNeedsValue,
+  contentDatabaseFilterTree,
+  reduceContentDatabaseFilterTree,
+} from "../shared/database-query.js";
 import { favoritesSystemIds } from "./_content-favorites.js";
 import { softDeletedDatabaseDocumentExclusions } from "./_document-discovery-query.js";
 import { parseDatabaseViewConfig } from "./_property-utils.js";
@@ -201,11 +205,10 @@ function navigationFilterSql(args: {
     updatedAt: SQL<string>;
   };
 }) {
-  const filters = args.filters.filter(activeNavigationFilter);
-  if (filters.length === 0) return undefined;
+  if (!args.filters.some(activeNavigationFilter)) return undefined;
   const definitionById = args.definitionById;
 
-  const leaves = filters.map((filter) => {
+  const leaf = (filter: ContentDatabaseFilter): SQL => {
     let predicate: SQL | undefined;
     if (filter.key === "name") {
       predicate = textFilterSql(args.document.title, filter);
@@ -282,23 +285,18 @@ function navigationFilterSql(args: {
         },
       );
     }
-    return { filter, predicate };
-  });
-  const roots = leaves.filter(({ filter }) => !filter.parentFilterGroupId);
-  const groups = new Map<string, SQL[]>();
-  for (const { filter, predicate } of leaves) {
-    if (!filter.parentFilterGroupId || !filter.filterGroupId) continue;
-    groups.set(filter.filterGroupId, [
-      ...(groups.get(filter.filterGroupId) ?? []),
-      predicate,
-    ]);
-  }
-  const combine = (values: SQL[]): SQL =>
-    (args.filterMode === "or" ? or(...values) : and(...values)) ?? sql`true`;
-  return combine([
-    ...roots.map(({ predicate }) => predicate),
-    ...[...groups.values()].map(combine),
-  ]);
+    return predicate;
+  };
+  return reduceContentDatabaseFilterTree(
+    contentDatabaseFilterTree(
+      args.filters,
+      args.filterMode,
+      activeNavigationFilter,
+    ),
+    leaf,
+    (mode, values): SQL =>
+      (mode === "or" ? or(...values) : and(...values)) ?? sql`true`,
+  );
 }
 
 type NavigationRevision = { count: number; checksum: bigint };

package/corpus/templates/content/actions/_database-row-batch.ts

@@ -1,7 +1,10 @@
+import { ActionContractError } from "@agent-native/core/action";
 import { and, asc, eq, inArray, isNull, or, sql } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import { lockDatabaseMemberships } from "./_database-membership-lock.js";
+import { lockDocumentRows } from "./_row-lock-order.js";
 
 export const DATABASE_ROW_BATCH_LIMIT = 100;
 
@@ -184,32 +187,58 @@ export async function resolveDatabaseRowsForBatch(
   };
 }
 
+/**
+ * Pass `heldMembershipIds` when the caller locked the collection's
+ * memberships before any page: a membership outside that set was added since,
+ * and locking it now would come after pages the caller holds.
+ */
 export async function renumberDatabaseRows(
   db: ReturnType<typeof getDb>,
   database: typeof schema.contentDatabases.$inferSelect,
   now: string,
+  heldMembershipIds?: ReadonlySet<string>,
 ) {
+  // Trashed rows keep their slot: renumbering only the visible rows lets a
+  // visible row take a trashed row's number, and the restored row then sorts
+  // after it. The tiebreaks match the collection read's.
   const rows = await db
     .select({
       id: schema.contentDatabaseItems.id,
       documentId: schema.contentDatabaseItems.documentId,
     })
     .from(schema.contentDatabaseItems)
-    .innerJoin(
-      schema.documents,
-      eq(schema.documents.id, schema.contentDatabaseItems.documentId),
-    )
-    .where(
-      and(
-        eq(schema.contentDatabaseItems.databaseId, database.id),
-        isNull(schema.documents.trashedAt),
-      ),
-    )
-    .orderBy(asc(schema.contentDatabaseItems.position));
+    .where(eq(schema.contentDatabaseItems.databaseId, database.id))
+    .orderBy(
+      asc(schema.contentDatabaseItems.position),
+      asc(schema.contentDatabaseItems.createdAt),
+      asc(schema.contentDatabaseItems.id),
+    );
   if (rows.length === 0) return;
+  if (heldMembershipIds && rows.some((row) => !heldMembershipIds.has(row.id)))
+    throw new ActionContractError(
+      "Database memberships changed before the operation completed.",
+      { errorCode: "DATABASE_MEMBERSHIPS_CHANGED", statusCode: 409 },
+    );
 
   const itemIds = rows.map((row) => row.id);
   const documentIds = rows.map((row) => row.documentId);
+  const renumberedPages = and(
+    eq(schema.documents.ownerEmail, database.ownerEmail),
+    eq(schema.documents.parentId, database.documentId),
+    inArray(schema.documents.id, documentIds),
+  );
+  // An UPDATE locks rows in scan order. Take them in Content's row-lock order
+  // first; callers already hold the collection.
+  await lockDatabaseMemberships(db, itemIds);
+  await lockDocumentRows(
+    db,
+    (
+      await db
+        .select({ id: schema.documents.id })
+        .from(schema.documents)
+        .where(renumberedPages)
+    ).map((page) => page.id),
+  );
   await db
     .update(schema.contentDatabaseItems)
     .set({
@@ -237,11 +266,5 @@ export async function renumberDatabaseRows(
       ),
       updatedAt: now,
     })
-    .where(
-      and(
-        eq(schema.documents.ownerEmail, database.ownerEmail),
-        eq(schema.documents.parentId, database.documentId),
-        inArray(schema.documents.id, documentIds),
-      ),
-    );
+    .where(renumberedPages);
 }

package/corpus/templates/content/actions/_database-row-mutation.ts

@@ -40,6 +40,7 @@ import {
   touchContentDatabase,
 } from "./_content-database-mutation-lock.js";
 import { ensureDocumentFilesMembership } from "./_content-files.js";
+import { lockExistingDatabaseMemberships } from "./_database-membership-lock.js";
 import {
   normalizeDatabasePropertyInput,
   type DatabasePropertyEntry,
@@ -55,6 +56,7 @@ import {
   withPositionLock,
 } from "./_position-utils.js";
 import { nanoid } from "./_property-utils.js";
+import { lockDocumentRows } from "./_row-lock-order.js";
 
 const databaseMutationAuthorityScopeSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("personal"), id: z.string().min(1) }),
@@ -1269,6 +1271,17 @@ async function updateInsideTransaction(
   },
 ) {
   const actor = requireDocumentRequestActor();
+  // The membership before the page, as a save takes them.
+  await tx
+    .update(schema.contentDatabaseItems)
+    .set({ updatedAt: sql`${schema.contentDatabaseItems.updatedAt}` })
+    .where(
+      and(
+        eq(schema.contentDatabaseItems.id, args.itemId),
+        eq(schema.contentDatabaseItems.databaseId, context.database.id),
+        eq(schema.contentDatabaseItems.documentId, args.documentId),
+      ),
+    );
   const [lockedDocument] = await tx
     .update(schema.documents)
     .set({ updatedAt: sql`${schema.documents.updatedAt}` })
@@ -1285,16 +1298,6 @@ async function updateInsideTransaction(
       statusCode: 404,
     });
   }
-  await tx
-    .update(schema.contentDatabaseItems)
-    .set({ updatedAt: sql`${schema.contentDatabaseItems.updatedAt}` })
-    .where(
-      and(
-        eq(schema.contentDatabaseItems.id, args.itemId),
-        eq(schema.contentDatabaseItems.databaseId, context.database.id),
-        eq(schema.contentDatabaseItems.documentId, args.documentId),
-      ),
-    );
   const before = await rowSnapshot(
     tx,
     context.database.id,
@@ -2192,24 +2195,10 @@ async function patchRowsInsideTransaction(
   const actor = requireDocumentRequestActor();
   const itemIds = rows.map((row) => row.itemId);
   const documentIds = rows.map((row) => row.documentId);
-  await tx
-    .update(schema.documents)
-    .set({ updatedAt: sql`${schema.documents.updatedAt}` })
-    .where(
-      and(
-        inArray(schema.documents.id, documentIds),
-        isNull(schema.documents.trashedAt),
-      ),
-    );
-  await tx
-    .update(schema.contentDatabaseItems)
-    .set({ updatedAt: sql`${schema.contentDatabaseItems.updatedAt}` })
-    .where(
-      and(
-        inArray(schema.contentDatabaseItems.id, itemIds),
-        eq(schema.contentDatabaseItems.databaseId, context.database.id),
-      ),
-    );
+  // Memberships, then pages, each by id, as saves take them. The snapshot
+  // below reports any row that's missing.
+  await lockExistingDatabaseMemberships(tx, itemIds);
+  await lockDocumentRows(tx, documentIds);
   const revisionIds = revisionPropertyIds(context);
   const before = await rowSnapshots(tx, context.database.id, rows, revisionIds);
   // Missing and stale rows share one report so a single reread covers both.

package/corpus/templates/content/actions/_database-source-utils.ts

@@ -103,7 +103,10 @@ import {
   organizationContentSpaceId,
   provisionContentSpaces,
 } from "./_content-spaces.js";
-import { lockDatabaseMemberships } from "./_database-membership-lock.js";
+import {
+  lockDatabaseMemberships,
+  lockExistingDatabaseMemberships,
+} from "./_database-membership-lock.js";
 import { ensureFilesSystemPropertyDefinitions } from "./_files-system-properties.js";
 import {
   createAppendPositionAllocator,
@@ -114,6 +117,7 @@ import {
   withPositionLock,
 } from "./_position-utils.js";
 import { listPropertiesForDatabase, nanoid } from "./_property-utils.js";
+import { lockDocumentRows } from "./_row-lock-order.js";
 import { isEffectivelyEmptyDocumentContent } from "./update-document.js";
 
 type ContentDatabaseRow = typeof schema.contentDatabases.$inferSelect;
@@ -2380,6 +2384,9 @@ async function processBuilderBodyHydrationJob(
       return;
     }
     if (shouldWriteBody) {
+      // The membership before the page, as a save takes them: its status
+      // is written after the body.
+      await lockExistingDatabaseMemberships(tx, [row.databaseItemId]);
       const contentCas =
         isEffectivelyEmptyDocumentContent(currentContent) &&
         isEffectivelyEmptyDocumentContent(previousContent)
@@ -2630,6 +2637,16 @@ async function persistPristineBuilderBodyHydrationsInBulk(
         const queueOwnership = batch.map(({ job }) =>
           builderBodyHydrationQueueOwnershipFilter(job),
         );
+        // Memberships, then pages, each by id, as saves take them; the
+        // writes below take pages first and in scan order.
+        await lockExistingDatabaseMemberships(
+          tx,
+          batch.map((row) => row.job.databaseItemId),
+        );
+        await lockDocumentRows(
+          tx as unknown as ReturnType<typeof getDb>,
+          batch.map((row) => row.job.documentId),
+        );
 
         const hydratedContent = hydrationCaseSql(
           schema.documents.id,

package/corpus/templates/content/actions/_database-utils.ts

@@ -152,6 +152,8 @@ export const contentDatabaseTableQuerySchema = z
           value: z.string(),
           filterGroupId: z.string().optional(),
           parentFilterGroupId: z.string().optional(),
+          filterGroupMode: z.enum(["and", "or"]).optional(),
+          parentFilterGroupMode: z.enum(["and", "or"]).optional(),
         }),
       )
       .max(50),
@@ -225,6 +227,7 @@ type DocumentListRow = Omit<
   typeof schema.documents.$inferSelect,
   | "content"
   | "collabBodyRevision"
+  | "liveBodySwitchedAt"
   | "createdBy"
   | "updatedBy"
   | "creationRequestDigest"

package/corpus/templates/content/actions/_database-view-setup.ts

@@ -55,6 +55,8 @@ const filterSchema = z
     value: z.string(),
     filterGroupId: z.string().max(200).optional(),
     parentFilterGroupId: z.string().max(200).optional(),
+    filterGroupMode: z.enum(["and", "or"]).optional(),
+    parentFilterGroupMode: z.enum(["and", "or"]).optional(),
   })
   .strict();
 
@@ -316,6 +318,20 @@ function validateTablePatch(
         400,
       );
     }
+    if (filter.filterGroupMode && !filter.filterGroupId) {
+      setupError(
+        "INVALID_VIEW_REFERENCE",
+        `Filter on "${filter.key}" sets filterGroupMode without a filterGroupId.`,
+        400,
+      );
+    }
+    if (filter.parentFilterGroupMode && !filter.parentFilterGroupId) {
+      setupError(
+        "INVALID_VIEW_REFERENCE",
+        `Filter on "${filter.key}" sets parentFilterGroupMode without a parentFilterGroupId.`,
+        400,
+      );
+    }
   }
 }