Add safe individual-block actions for Content databases

templates/content/.agents/skills/document-editing/references/databases.md

@@ -96,6 +96,18 @@ its stored name). In table views a Blocks column shows a word count (e.g.
 database view's column menu (not from the page body); deleting the last
 Blocks field warns that it removes the body for every object of the type.
 
+For one-block agent edits, call `list-content-database-blocks` with the exact
+space, database, backing document, membership row, row document, and property
+IDs. Preserve its schema, row, and field revisions. Each returned block names
+the operations its kind supports and carries canonical Notion-flavored Markdown
+(NFM) for that one block. Pass all three revisions to
+`mutate-content-database-block`; its `insert`, `update`, `upsert`, `delete`, and
+`reorder` variants preserve unmentioned fields and sibling blocks. A block
+value must contain exactly one top-level block of the declared kind. Reuse an
+idempotency key only for an exact retry. Unsupported kinds, kind conversion,
+tombstone reuse, cross-parent reorder, schema drift, and stale row or field
+revisions fail explicitly.
+
 Formula properties store their expression in property options and support
 `{Property name}` substitution plus simple numeric math such as `{MSV} * 2`.
 
@@ -236,6 +248,7 @@ Use `create-content-database`, `create-inline-content-database`,
 `duplicate-database-items`, `remove-database-items`, `move-database-item`,
 `update-content-database-view`, `list-document-properties`,
 `configure-document-property`, `set-document-property`,
+`list-content-database-blocks`, `mutate-content-database-block`,
 `duplicate-document-property`, and `delete-document-property`; do not edit
 property rows or view config via raw SQL when an action can do it.
 

templates/content/AGENTS.md

@@ -79,6 +79,8 @@ Read the relevant skill before deeper work:
 | `edit-document` | Find/replace edit — preferred for small changes |
 | `update-document` | Full rewrite of title, content, or description |
 | `delete-document` | Move a page and its children to Trash |
+| `list-content-database-blocks` | List stable blocks and revisions in one exact database row/property |
+| `mutate-content-database-block` | Insert, update, upsert, delete, or reorder one supported stable block |
 | `migrate-content-database-rows` | Validate, atomically apply, verify, roll back, or finalize one bounded whole-database row migration |
 
 Every action carries its own schema, and the rest of the app-specific surface

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

@@ -29,6 +29,17 @@ export class BlocksFieldRevisionConflictError extends Error {
   }
 }
 
+export class BlocksFieldIdCollisionError extends Error {
+  readonly blockId: string;
+  readonly statusCode = 409;
+
+  constructor(blockId: string) {
+    super(`Block ID is already owned by another Blocks field: ${blockId}`);
+    this.name = "BlocksFieldIdCollisionError";
+    this.blockId = blockId;
+  }
+}
+
 function nanoid(size = 12): string {
   const chars =
     "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
@@ -265,6 +276,8 @@ export async function persistBlocksFieldIdentity(args: {
   previousMarkdown: string;
   markdown: string;
   expectedRevision?: number;
+  preferredIdsByPath?: Readonly<Record<string, string>>;
+  rejectCrossFieldIdRemapping?: boolean;
   now: string;
 }): Promise<StoredBlocksFieldIdentity> {
   const fieldId = blocksFieldId(args.documentId, args.propertyId);
@@ -306,6 +319,7 @@ export async function persistBlocksFieldIdentity(args: {
     previous,
     markdown: args.markdown,
     createId: () => `block_${nanoid(16)}`,
+    preferredIdsByPath: args.preferredIdsByPath,
   });
 
   if (next.blocks.length > 0) {
@@ -325,6 +339,9 @@ export async function persistBlocksFieldIdentity(args: {
     const reserved = new Set(next.blocks.map((block) => block.id));
     for (const existing of existingOwners) {
       if (existing.fieldId === fieldId) continue;
+      if (args.rejectCrossFieldIdRemapping) {
+        throw new BlocksFieldIdCollisionError(existing.id);
+      }
       let replacement = `block_${nanoid(16)}`;
       while (reserved.has(replacement)) replacement = `block_${nanoid(16)}`;
       reserved.add(replacement);