@agent-native/core 0.154.3 → 0.154.4

package/corpus/templates/content/app/components/editor/DocumentBlockFields.tsx

@@ -16,6 +16,7 @@ import {
   type ReactNode,
   type PointerEvent as ReactPointerEvent,
 } from "react";
+import { toast } from "sonner";
 
 import {
   documentPropertiesResponseMatchesScope,
@@ -52,6 +53,25 @@ interface DocumentBlockFieldsProps {
   primaryEditor: ReactNode;
 }
 
+function isBlocksFieldRevisionConflict(error: unknown): boolean {
+  if (error instanceof Error) {
+    return error.message.includes("Blocks field revision conflict");
+  }
+  if (!error || typeof error !== "object") return false;
+  const candidate = error as {
+    status?: unknown;
+    message?: unknown;
+    error?: unknown;
+    cause?: unknown;
+  };
+  if (candidate.status === 409) return true;
+  return [candidate.message, candidate.error, candidate.cause].some(
+    (value) =>
+      typeof value === "string" &&
+      value.includes("Blocks field revision conflict"),
+  );
+}
+
 export function blockFieldsFromProperties(
   properties: DocumentProperty[],
 ): DocumentProperty[] {
@@ -657,24 +677,55 @@ export function useBlockFieldEditor({
   documentId,
   propertyId,
   initialContent,
+  initialRevision,
   save,
+  onRevisionConflict,
 }: {
   documentId: string;
   propertyId: string;
   initialContent: string;
+  initialRevision: number;
   save: (request: {
     documentId: string;
     propertyId: string;
     value: string;
+    expectedBlocksFieldRevision: number;
   }) => Promise<unknown>;
-}): { content: string; onChange: (markdown: string) => void } {
+  onRevisionConflict?: () => void;
+}): {
+  content: string;
+  editorResetVersion: number;
+  onChange: (markdown: string) => void;
+} {
   const key = `${documentId}:${propertyId}`;
 
   // The shared controller calls the freshest save impl through a per-key ref. The
   // save TARGET (documentId:propertyId) is fixed by the key; only the function
   // identity changes per mount, never the field it writes to.
   const implRef = blockFieldSaveImplRef(key);
-  implRef.current = (value: string) => save({ documentId, propertyId, value });
+  const revisionRef = useRef(initialRevision);
+  const rejectedRevisionRef = useRef<number | null>(null);
+  const onRevisionConflictRef = useRef(onRevisionConflict);
+  onRevisionConflictRef.current = onRevisionConflict;
+  if (initialRevision > revisionRef.current) {
+    revisionRef.current = initialRevision;
+  }
+  implRef.current = async (value: string) => {
+    const response = await save({
+      documentId,
+      propertyId,
+      value,
+      expectedBlocksFieldRevision: revisionRef.current,
+    });
+    const nextRevision = (
+      response as DocumentPropertiesResponse
+    )?.properties?.find((candidate) => candidate.definition.id === propertyId)
+      ?.blocksField?.revision;
+    if (typeof nextRevision === "number") revisionRef.current = nextRevision;
+    return response;
+  };
+
+  const controllerRef = useRef<BlockFieldSaveController | null>(null);
 
   // Build (but do not yet ref-count) the controller factory for this key. The
   // formal acquire/release happens in the effect below; we only need the factory
@@ -686,12 +737,24 @@ export function useBlockFieldEditor({
       // saves across ALL editor instances for the key (there is only ever one
       // controller per key), so no cross-instance serialization lane is needed.
       save: (value) => implRef.current(value),
-      onError: (error) =>
+      onError: (error) => {
+        if (isBlocksFieldRevisionConflict(error)) {
+          rejectedRevisionRef.current = revisionRef.current;
+          // A stale payload is not a retryable draft. If this editor unmounts
+          // before the invalidated query returns, flush must not replay it
+          // against the newly advanced revision and overwrite the winner.
+          // The request can reject after this hook unmounts. The per-field
+          // controller outlives that mount, so clear the rejected payload at
+          // the shared boundary instead of relying on the instance ref.
+          peekBlockFieldSaveController(key)?.discardPending();
+          onRevisionConflictRef.current?.();
+        }
         console.error("Failed to save Blocks field content", {
           documentId,
           propertyId,
           error,
-        }),
+        });
+      },
     });
 
   // Acquire the ONE shared controller for this field key, and release it on
@@ -706,7 +769,6 @@ export function useBlockFieldEditor({
   // `factory`/`implRef` are intentionally not effect deps: the impl ref is updated
   // every render, and the identity key forces a remount for a DIFFERENT key, so
   // within one mount the key is stable and we acquire exactly once.
-  const controllerRef = useRef<BlockFieldSaveController | null>(null);
   useEffect(() => {
     controllerRef.current = acquireBlockFieldSaveController(key, factory);
     return () => {
@@ -741,6 +803,7 @@ export function useBlockFieldEditor({
     }
     return initialContent;
   });
+  const [editorResetVersion, setEditorResetVersion] = useState(0);
 
   // Adopt fresh server content when it is a GENUINELY newer external update (e.g.
   // an agent edit) — not when it is merely stale server props lagging a local
@@ -761,6 +824,27 @@ export function useBlockFieldEditor({
   useEffect(() => {
     const controller = controllerRef.current;
     if (!controller) return;
+    const rejectedRevision = rejectedRevisionRef.current;
+    if (rejectedRevision !== null && initialRevision > rejectedRevision) {
+      if (controller.pending !== controller.lastSaved) {
+        // The user typed again while the winner was being refetched. Preserve
+        // that newer draft; revisionRef already reflects initialRevision, so
+        // its pending save will use the newly accepted boundary.
+        rejectedRevisionRef.current = null;
+        return;
+      }
+      // The server rejected our stale revision and the invalidated query has
+      // now delivered the winner. The rejected draft is not retryable against
+      // the new baseline: adopt the accepted value and clear the dirty latch.
+      setContent(initialContent);
+      controller.mark(initialContent);
+      rejectedRevisionRef.current = null;
+      // VisualEditor owns an imperative TipTap instance. Reset it only for this
+      // explicit conflict recovery so the accepted server value replaces the
+      // rejected draft without disrupting ordinary save cursor/undo state.
+      setEditorResetVersion((version) => version + 1);
+      return;
+    }
     // Never adopt over a dirty local edit.
     if (controller.pending !== controller.lastSaved) return;
     if (initialContent === controller.lastSaved) {
@@ -780,10 +864,10 @@ export function useBlockFieldEditor({
     }
     // else: server props are stale, lagging a local save the server hasn't
     // echoed yet. Keep showing lastSaved and wait for the echo above to clear
-    // the latch. (Cross-client concurrent same-field edits remain last-write-
-    // wins for v1; true coherence needs the deferred server-side versioning.)
+    // the latch. Concurrent writes are guarded by the field revision; a
+    // rejected stale write follows the explicit conflict branch above.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [initialContent]);
+  }, [initialContent, initialRevision]);
 
   function onChange(markdown: string) {
     setContent(markdown);
@@ -792,7 +876,7 @@ export function useBlockFieldEditor({
     controllerRef.current?.change(markdown);
   }
 
-  return { content, onChange };
+  return { content, editorResetVersion, onChange };
 }
 
 /**
@@ -811,6 +895,7 @@ function AdditionalBlockEditor({
   property: DocumentProperty;
   canEdit: boolean;
 }) {
+  const t = useT();
   const setProperty = useSetDocumentProperty(
     documentId,
     property.definition.databaseId!,
@@ -819,16 +904,19 @@ function AdditionalBlockEditor({
   const propertyId = property.definition.id;
   const initialContent =
     typeof property.value === "string" ? property.value : "";
-  const { content, onChange } = useBlockFieldEditor({
+  const { content, editorResetVersion, onChange } = useBlockFieldEditor({
     documentId,
     propertyId,
     initialContent,
+    initialRevision: property.blocksField?.revision ?? 0,
     save: setProperty.mutateAsync,
+    onRevisionConflict: () =>
+      toast.error(t("editor.blocksFieldRevisionConflict")),
   });
 
   return (
     <VisualEditor
-      key={propertyId}
+      key={`${propertyId}:${editorResetVersion}`}
       documentId={documentId}
       content={content}
       onChange={onChange}

package/corpus/templates/content/app/components/editor/blockFieldSaveController.ts

@@ -40,6 +40,8 @@ export interface BlockFieldSaveController {
   cancel(): void;
   /** Adopt `content` as the confirmed-saved baseline (no save scheduled). */
   mark(content: string): void;
+  /** Drop a rejected pending write so an unmount flush cannot retry it. */
+  discardPending(): void;
   /** The value last CONFIRMED persisted. */
   readonly lastSaved: string;
   /** The latest value the user has typed (may differ from lastSaved). */
@@ -161,6 +163,10 @@ export function createBlockFieldSaveController(args: {
       // hasn't echoed — so server props are no longer "behind" this controller.
       hasSavedLocally = false;
     },
+    discardPending() {
+      clearTimer();
+      pending = lastSaved;
+    },
     get lastSaved() {
       return lastSaved;
     },

package/corpus/templates/content/app/hooks/use-document-properties.ts

@@ -132,7 +132,7 @@ export function useSetDocumentProperty(
       );
       return { previous };
     },
-    onError: (_error, _variables, context) => {
+    onError: (_error, variables, context) => {
       const rollback = context as
         | {
             previous?: Array<[readonly unknown[], unknown]>;
@@ -141,6 +141,9 @@ export function useSetDocumentProperty(
       for (const [queryKey, data] of rollback?.previous ?? []) {
         queryClient.setQueryData(queryKey, data);
       }
+      queryClient.invalidateQueries({
+        queryKey: documentPropertiesQueryKey(variables.documentId, databaseId),
+      });
     },
     onSuccess: (data, variables) => {
       const savedValue =

package/corpus/templates/content/app/i18n-data.ts

@@ -3119,6 +3119,8 @@ const enUS = {
     searchLanguages: "Search languages...",
     noBlocksFields: "No Blocks fields. Add one from the property menu.",
     noDocumentSelected: "No document selected",
+    blocksFieldRevisionConflict:
+      "This Blocks field changed elsewhere. Your edit wasn't saved; the latest version is now shown.",
     couldNotReadLocalSourceFile: "Could not read local source file",
     couldNotSaveLocalFile: "Could not save local file",
     collabConnectingReadOnly:
@@ -5619,6 +5621,8 @@ const databaseExactEnglishMessagesByLocale = {
 const editorMessagesByLocale = {
   "zh-CN": {
     noDocumentSelected: "未选择文档",
+    blocksFieldRevisionConflict:
+      "此 Blocks 字段已在其他位置更改。你的编辑未保存；现已显示最新版本。",
     collabConnectingReadOnly: "正在连接实时编辑器。显示只读快照。",
     liveDocumentSaveBeforeSyncFailed: "实时文档无法在同步前保存。",
     builderBodySyncing: "内容仍在从 Builder 同步",
@@ -5966,6 +5970,8 @@ const editorMessagesByLocale = {
   },
   "es-ES": {
     noDocumentSelected: "Ningún documento seleccionado",
+    blocksFieldRevisionConflict:
+      "Este campo de bloques cambió en otro lugar. Tu edición no se guardó; ahora se muestra la versión más reciente.",
     collabConnectingReadOnly:
       "Conectando el editor en vivo. Mostrando una instantánea de solo lectura.",
     liveDocumentSaveBeforeSyncFailed:
@@ -6326,6 +6332,8 @@ const editorMessagesByLocale = {
   },
   "fr-FR": {
     noDocumentSelected: "Aucun document sélectionné",
+    blocksFieldRevisionConflict:
+      "Ce champ de blocs a été modifié ailleurs. Votre modification n’a pas été enregistrée ; la dernière version est maintenant affichée.",
     collabConnectingReadOnly:
       "Connexion de l'éditeur en direct. Affichage d'un instantané en lecture seule.",
     liveDocumentSaveBeforeSyncFailed:
@@ -6691,6 +6699,8 @@ const editorMessagesByLocale = {
   },
   "de-DE": {
     noDocumentSelected: "Kein Dokument ausgewählt",
+    blocksFieldRevisionConflict:
+      "Dieses Blocks-Feld wurde an anderer Stelle geändert. Deine Bearbeitung wurde nicht gespeichert; jetzt wird die neueste Version angezeigt.",
     collabConnectingReadOnly:
       "Live-Editor wird verbunden. Schreibgeschützte Momentaufnahme wird angezeigt.",
     liveDocumentSaveBeforeSyncFailed:
@@ -7059,6 +7069,8 @@ const editorMessagesByLocale = {
   },
   "ja-JP": {
     noDocumentSelected: "ドキュメントが選択されていません",
+    blocksFieldRevisionConflict:
+      "このブロックフィールドは別の場所で変更されました。編集内容は保存されず、最新バージョンが表示されています。",
     collabConnectingReadOnly:
       "ライブエディターに接続中。読み取り専用のスナップショットを表示しています。",
     liveDocumentSaveBeforeSyncFailed:
@@ -7416,6 +7428,8 @@ const editorMessagesByLocale = {
   },
   "ko-KR": {
     noDocumentSelected: "선택한 문서가 없습니다.",
+    blocksFieldRevisionConflict:
+      "이 블록 필드가 다른 곳에서 변경되었습니다. 편집 내용은 저장되지 않았으며 최신 버전이 표시됩니다.",
     collabConnectingReadOnly:
       "라이브 편집기에 연결하는 중입니다. 읽기 전용 스냅샷을 표시합니다.",
     liveDocumentSaveBeforeSyncFailed:
@@ -7772,6 +7786,8 @@ const editorMessagesByLocale = {
   },
   "pt-BR": {
     noDocumentSelected: "Nenhum documento selecionado",
+    blocksFieldRevisionConflict:
+      "Este campo de blocos foi alterado em outro lugar. Sua edição não foi salva; a versão mais recente agora está sendo exibida.",
     collabConnectingReadOnly:
       "Conectando o editor ao vivo. Exibindo um instantâneo somente leitura.",
     liveDocumentSaveBeforeSyncFailed:
@@ -8134,6 +8150,8 @@ const editorMessagesByLocale = {
   },
   "hi-IN": {
     noDocumentSelected: "कोई दस्तावेज़ चयनित नहीं",
+    blocksFieldRevisionConflict:
+      "यह ब्लॉक फ़ील्ड कहीं और बदल गया है। आपका संपादन सहेजा नहीं गया; अब नवीनतम संस्करण दिखाया जा रहा है।",
     collabConnectingReadOnly:
       "लाइव संपादक कनेक्ट हो रहा है। केवल-पठन स्नैपशॉट दिखाया जा रहा है।",
     liveDocumentSaveBeforeSyncFailed:
@@ -8486,6 +8504,8 @@ const editorMessagesByLocale = {
   },
   "ar-SA": {
     noDocumentSelected: "لم يتم تحديد أي مستند",
+    blocksFieldRevisionConflict:
+      "تم تغيير حقل الكتل هذا في مكان آخر. لم يتم حفظ تعديلك؛ ويظهر الآن أحدث إصدار.",
     collabConnectingReadOnly:
       "جارٍ الاتصال بالمحرر المباشر. يتم عرض لقطة للقراءة فقط.",
     liveDocumentSaveBeforeSyncFailed: "تعذّر حفظ المستند المباشر قبل المزامنة.",

package/corpus/templates/content/changelog/2026-08-10-database-blocks-fields-now-keep-logical-block-identity-throu.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Database Blocks fields now keep logical block identity through editing, reordering, deletion recovery, and reloads

package/corpus/templates/content/changelog/2026-08-13-blocks-field-conflicts-now-keep-the-newer-saved-version-visi.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-13
+---
+
+Blocks field conflicts now keep the newer saved version visible instead of leaving a rejected edit on screen

package/corpus/templates/content/docs/product/capabilities/content.object.block.md

@@ -6,7 +6,7 @@ name: "Blocks"
 user_promise: "A Block is a stable addressable unit of rich content inside its owning field."
 primary_user_job: "Edit and point to a meaningful part of content without fragile position-only anchors."
 kind: "primitive"
-state: "approved_shape"
+state: "in_progress"
 publicness: "public"
 availability: "universal"
 dependencies: []
@@ -21,9 +21,10 @@ proof_requirements:
     "Comment anchors retain historical target context",
     "Shared Action/UI editing, conflict, undo, and reload behavior",
   ]
-evidence: []
+evidence:
+  ["shared/blocks-field-identity.ts", "actions/blocks-seeding.db.test.ts"]
 superseded_by: null
-last_reviewed: "2026-07-29"
+last_reviewed: "2026-08-10"
 ---
 
 # Blocks
@@ -62,7 +63,7 @@ Given a Block reference in another Page, when an authorized reader opens it, the
 
 ## Current evidence
 
-The current editor stores rich document content and supports anchored comments, but the repository does not yet demonstrate stable universal Block IDs, reference serialization, or recovery across all typed Block operations. This remains `approved_shape`.
+Database Blocks fields now have a field-scoped ordered identity sidecar with deterministic legacy IDs, persisted revisions, and bounded tombstone recovery. Deterministic tests cover editing, reorder, insertion, deletion, recovery, reload, and field independence. Agent-facing exact Block actions, reference/comment anchors, actor-aware history, and real-interface proof remain incomplete, so this is `in_progress`, not verified.
 
 ## Proof plan
 

package/corpus/templates/content/docs/product/capabilities/content.object.blocks-field.md

@@ -6,7 +6,7 @@ name: "Blocks fields"
 user_promise: "Every editable rich-content body uses one Blocks-field grammar and keeps its own stable revision boundary."
 primary_user_job: "Write rich content in Pages and collaboration surfaces without each body inventing incompatible editing and history rules."
 kind: "primitive"
-state: "approved_shape"
+state: "in_progress"
 publicness: "public"
 availability: "universal"
 dependencies: ["content.object.block"]
@@ -24,9 +24,14 @@ proof_requirements:
     "Owner-scoped access and typed rendering including unavailable content",
     "Shared Action/UI behavior for concurrency, history, and portable output",
   ]
-evidence: []
+evidence:
+  [
+    "server/db/schema.ts",
+    "actions/_blocks-field-identity.ts",
+    "actions/blocks-seeding.db.test.ts",
+  ]
 superseded_by: null
-last_reviewed: "2026-07-29"
+last_reviewed: "2026-08-10"
 ---
 
 # Blocks fields
@@ -65,7 +70,7 @@ Given a Page with two Blocks fields, when an authorized editor restores one fiel
 
 ## Current evidence
 
-The document editor proves rich Page-body editing and comments provide collaboration substrate. The repository does not yet prove one generalized Blocks-field grammar or independent field history across all owners; this remains `approved_shape`.
+Primary and additional database Blocks properties now retain distinct field identities, ordered Block identities, and independent monotonic revisions around their existing Markdown stores. Export reports each field and its identity status without changing plain NFM. Comment/Discussion owners, attributable history, arbitrary restore, shared mutation actions, and real-interface proof remain incomplete, so this is `in_progress`, not verified.
 
 ## Proof plan
 

package/corpus/templates/content/docs/product/encyclopedia.md

@@ -16,8 +16,8 @@ This index summarizes the atomic product contracts beneath the public roadmap. E
 | Verified         |     3 |
 | Failing          |     1 |
 | Stale            |     0 |
-| In Progress      |    16 |
-| Approved Shape   |    91 |
+| In Progress      |    18 |
+| Approved Shape   |    89 |
 | Exploring        |     8 |
 | Deferred         |     0 |
 | Superseded       |     5 |
@@ -358,8 +358,8 @@ graph LR
 
 | Capability                                                                       | State          | User promise                                                                                                              |
 | -------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| [Blocks](capabilities/content.object.block.md)                                   | Approved Shape | A Block is a stable addressable unit of rich content inside its owning field.                                             |
-| [Blocks fields](capabilities/content.object.blocks-field.md)                     | Approved Shape | Every editable rich-content body uses one Blocks-field grammar and keeps its own stable revision boundary.                |
+| [Blocks](capabilities/content.object.block.md)                                   | In Progress    | A Block is a stable addressable unit of rich content inside its owning field.                                             |
+| [Blocks fields](capabilities/content.object.blocks-field.md)                     | In Progress    | Every editable rich-content body uses one Blocks-field grammar and keeps its own stable revision boundary.                |
 | [Databases](capabilities/content.object.database.md)                             | Verified       | Database as a Page-backed typed collection                                                                                |
 | [Multiple Database memberships](capabilities/content.object.multi-membership.md) | In Progress    | One Page can belong to several Databases without copies or a hidden primary home.                                         |
 | [Pages](capabilities/content.object.page.md)                                     | Verified       | A durable Page keeps its identity, body, properties, access, discussion, and portable representation wherever it appears. |

package/corpus/templates/content/server/db/schema.ts

@@ -523,4 +523,65 @@ export const documentBlockFieldContents = table(
   },
 );
 
+// Stable identity and revision boundary for one database Blocks property. The
+// Markdown body remains in documents.content or document_block_field_contents;
+// this row binds the ordered identity sidecar to those exact bytes.
+export const documentBlockFields = table(
+  "document_block_fields",
+  {
+    id: text("id").primaryKey(),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    documentId: text("document_id").notNull(),
+    propertyId: text("property_id").notNull(),
+    revision: integer("revision").notNull().default(0),
+    contentHash: text("content_hash").notNull(),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+  (field) => [
+    uniqueIndex("document_block_fields_document_property_unique").on(
+      field.documentId,
+      field.propertyId,
+    ),
+    index("document_block_fields_owner_document_idx").on(
+      field.ownerEmail,
+      field.documentId,
+    ),
+  ],
+);
+
+// Ordered block identity index plus bounded tombstones. This is deliberately
+// not an actor-aware history log: it records only current nodes and the minimum
+// deleted fragment needed for editor undo to recover the same logical ID.
+export const documentBlocks = table(
+  "document_blocks",
+  {
+    id: text("id").primaryKey(),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    fieldId: text("field_id").notNull(),
+    parentId: text("parent_id"),
+    kind: text("kind").notNull(),
+    position: integer("position").notNull(),
+    sortIndex: integer("sort_index").notNull(),
+    addressable: integer("addressable", { mode: "boolean" })
+      .notNull()
+      .default(true),
+    contentHash: text("content_hash").notNull(),
+    markdown: text("markdown").notNull().default(""),
+    state: text("state").notNull().default("live"),
+    deletedAtRevision: integer("deleted_at_revision"),
+    recoveredAtRevision: integer("recovered_at_revision"),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+  (block) => [
+    index("document_blocks_field_state_sort_idx").on(
+      block.fieldId,
+      block.state,
+      block.sortIndex,
+    ),
+    index("document_blocks_parent_idx").on(block.parentId),
+  ],
+);
+
 export const documentShares = createSharesTable("document_shares");

package/corpus/templates/content/server/plugins/db.ts

@@ -956,6 +956,61 @@ export const runContentMigrations = runMigrations(
       CREATE INDEX IF NOT EXISTS content_database_migration_receipts_owner_database_idx
         ON content_database_migration_receipts (owner_email, database_id)`,
     },
+    {
+      version: 81,
+      name: "content-block-field-identities",
+      sql: `CREATE TABLE IF NOT EXISTS document_block_fields (
+        id TEXT PRIMARY KEY,
+        owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+        document_id TEXT NOT NULL,
+        property_id TEXT NOT NULL,
+        revision INTEGER NOT NULL DEFAULT 0,
+        content_hash TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS document_block_fields_document_property_unique
+        ON document_block_fields (document_id, property_id);
+      CREATE INDEX IF NOT EXISTS document_block_fields_owner_document_idx
+        ON document_block_fields (owner_email, document_id)`,
+    },
+    {
+      version: 82,
+      name: "content-block-identities-and-tombstones",
+      sql: `CREATE TABLE IF NOT EXISTS document_blocks (
+        id TEXT PRIMARY KEY,
+        owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+        field_id TEXT NOT NULL,
+        parent_id TEXT,
+        kind TEXT NOT NULL,
+        position INTEGER NOT NULL,
+        sort_index INTEGER NOT NULL,
+        addressable INTEGER NOT NULL DEFAULT 1,
+        content_hash TEXT NOT NULL,
+        markdown TEXT NOT NULL DEFAULT '',
+        state TEXT NOT NULL DEFAULT 'live',
+        deleted_at_revision INTEGER,
+        recovered_at_revision INTEGER,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+      CREATE INDEX IF NOT EXISTS document_blocks_field_state_sort_idx
+        ON document_blocks (field_id, state, sort_index);
+      CREATE INDEX IF NOT EXISTS document_blocks_parent_idx
+        ON document_blocks (parent_id)`,
+    },
+    // The portable schema maps integer({ mode: "boolean" }) to BOOLEAN on
+    // Postgres, while the raw INTEGER migration above is adapted to BIGINT.
+    // Convert the stored column before Drizzle sends boolean values.
+    {
+      version: 83,
+      name: "content-block-addressable-postgres-boolean",
+      sql: {
+        postgres: `ALTER TABLE document_blocks ALTER COLUMN addressable DROP DEFAULT;
+        ALTER TABLE document_blocks ALTER COLUMN addressable TYPE boolean USING addressable::text::boolean;
+        ALTER TABLE document_blocks ALTER COLUMN addressable SET DEFAULT true`,
+      },
+    },
   ],
   { table: "content_migrations" },
 );

package/corpus/templates/content/shared/api.ts

@@ -1,3 +1,4 @@
+import type { BlocksFieldIdentity } from "./blocks-field-identity";
 import type {
   DocumentPropertyOptions,
   DocumentPropertyOption,
@@ -206,6 +207,7 @@ export interface DocumentProperty {
   definition: DocumentPropertyDefinition;
   value: DocumentPropertyValue;
   editable: boolean;
+  blocksField?: BlocksFieldIdentity;
 }
 
 export interface DocumentPropertiesResponse {
@@ -230,6 +232,7 @@ export interface SetDocumentPropertyRequest {
   databaseId: string;
   propertyId: string;
   value: DocumentPropertyValue;
+  expectedBlocksFieldRevision?: number;
 }
 
 export interface DuplicateDocumentPropertyRequest {