@agent-native/core 0.154.3 → 0.154.5

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/components/editor/database/DatabaseView.tsx

@@ -1631,6 +1631,11 @@ function DatabaseTable({
   ) {
     if (!databaseId) return null;
     if (isWorkspaceCatalog) return null;
+    const mutationContract = data?.mutationContract;
+    if (!mutationContract) {
+      toast.error(dbText("failedToCreateRow"));
+      return null;
+    }
     const propertyValues = {
       ...databasePropertyValuesForNewItem(filters, properties, filterMode),
       ...propertyValueOverrides,
@@ -1638,8 +1643,10 @@ function DatabaseTable({
     let response;
     try {
       response = await addItem.mutateAsync({
-        databaseId,
-        title,
+        target: mutationContract.target,
+        expectedSchemaRevision: mutationContract.schemaRevision,
+        idempotencyKey: crypto.randomUUID(),
+        ...(title.trim() ? { title } : {}),
         propertyValues:
           Object.keys(propertyValues).length > 0 ? propertyValues : undefined,
       });
@@ -1650,12 +1657,7 @@ function DatabaseTable({
       });
       return null;
     }
-    const createdItem = databaseCreatedItemForImmediatePreview(response, {
-      databaseId,
-      parentDocument: document,
-      title,
-      propertyValues,
-    });
+    const createdItem = response.createdItem ?? null;
     const needsPreview =
       !!createdItem &&
       databaseCreatedItemNeedsPreview(items, createdItem, options);

package/corpus/templates/content/app/hooks/use-content-database.ts

@@ -12,6 +12,7 @@ import type {
   CancelPreparedBuilderSourceUpdateResponse,
   ChangeContentDatabaseSourceRoleRequest,
   ContentDatabaseResponse,
+  ContentDatabaseRowMutationResult,
   ContentDatabaseSourceAttachmentAck,
   ContentDatabaseSourceAttachmentResult,
   ContentDatabaseItemsPageResponse,
@@ -819,40 +820,40 @@ export function useTrashedContentDatabases() {
 
 export function useAddDatabaseItem(documentId: string) {
   const queryClient = useQueryClient();
-  return useActionMutation<ContentDatabaseResponse, AddDatabaseItemRequest>(
-    "add-database-item",
-    {
-      skipActionQueryInvalidation: true,
-      onSuccess: (data) => {
-        if (data.createdItem) {
-          queryClient.setQueriesData<ContentDatabaseResponse>(
-            {
-              queryKey: ["action", "get-content-database"],
-              predicate: (query) => {
-                if (
-                  !isContentDatabaseQueryForDocument(query.queryKey, documentId)
-                ) {
-                  return false;
-                }
-                const params = query.queryKey[2] as {
-                  tableQuery?: unknown;
-                };
-                return params.tableQuery === undefined;
-              },
+  return useActionMutation<
+    ContentDatabaseRowMutationResult,
+    AddDatabaseItemRequest
+  >("add-database-item", {
+    skipActionQueryInvalidation: true,
+    onSuccess: (data) => {
+      if (data.createdItem) {
+        queryClient.setQueriesData<ContentDatabaseResponse>(
+          {
+            queryKey: ["action", "get-content-database"],
+            predicate: (query) => {
+              if (
+                !isContentDatabaseQueryForDocument(query.queryKey, documentId)
+              ) {
+                return false;
+              }
+              const params = query.queryKey[2] as {
+                tableQuery?: unknown;
+              };
+              return params.tableQuery === undefined;
             },
-            (current) =>
-              applyOptimisticItemToContentDatabase(current, data.createdItem!),
-          );
-        }
-        queryClient.invalidateQueries({
-          queryKey: contentDatabaseQueryKey(documentId),
-        });
-        queryClient.invalidateQueries({
-          queryKey: ["action", "list-documents"],
-        });
-      },
+          },
+          (current) =>
+            applyOptimisticItemToContentDatabase(current, data.createdItem!),
+        );
+      }
+      queryClient.invalidateQueries({
+        queryKey: contentDatabaseQueryKey(documentId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "list-documents"],
+      });
     },
-  );
+  });
 }
 
 export function useSubmitContentDatabaseForm(documentId: string) {

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-10-database-row-actions-now-validate-exact-schemas-and-safe-ret.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Database row actions now validate exact schemas and safe retries before changing data.

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/parity/matrix.md

@@ -9,7 +9,7 @@ This generated matrix tracks whether high-value Content UI operations use the sa
 | database.lifecycle-and-trash                       | database    | Create, soft-delete, restore, list, and inspect content databases                                         | action-backed         | `create-content-database`, `create-inline-content-database`, `delete-content-database`, `get-content-database`, `list-content-databases`, `list-trashed-content-databases`, `restore-content-database`                                                                                                                                                                                                      | `app/components/editor/SlashCommandMenu.tsx`, `app/hooks/use-content-database.ts`, `app/hooks/use-documents.ts`                                                                           | Database pages and database records are created, read, soft-deleted, restored, and listed.                                                                                                                                                                                                | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`                                                                                                                                                                         | `database-source-scope`          | -                              |
 | database.private-preview-drafts                    | database    | Persist and reconcile a user's private database-page preview draft                                        | action-backed         | `get-preview-document-draft`, `update-preview-document-draft`                                                                                                                                                                                                                                                                                                                                               | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-documents.ts`                                                                                                           | A user's private preview draft is read, saved, conflict-checked, or deleted without changing the shared database page until the normal save flow applies it.                                                                                                                              | These per-user editor-state actions are intentionally hidden from agent tools because preview drafts are a private UI recovery mechanism.                                                                                                  | -                | P1             | covered       | `actions/preview-document-draft.db.test.ts`                                                                                                                                                                             | -                                | -                              |
 | database.properties-and-view-config                | database    | Configure properties, values, ordering, and saved views                                                   | action-backed         | `configure-document-property`, `delete-document-property`, `duplicate-document-property`, `get-content-database-personal-view`, `list-document-properties`, `reorder-document-property`, `set-document-property`, `update-content-database-personal-view`, `update-content-database-view`                                                                                                                   | `app/components/editor/DocumentProperties.tsx`, `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-document-properties.ts`   | Property schemas, property values, property order, filters, sorts, grouping, hidden columns, view type, and view settings are stored.                                                                                                                                                     | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/bind-content-database-source-field.db.test.ts`, `actions/content-database-source-actions.test.ts`, `actions/resync-content-database-source.db.test.ts`                                                         | `database-source-scope`          | -                              |
-| database.rows                                      | database    | Add, duplicate, move, open, edit, and remove database rows                                                | action-backed         | `add-database-item`, `upsert-database-item-by-key`, `remove-database-items`, `duplicate-database-items`, `duplicate-database-item`, `migrate-content-database-rows`, `move-database-item`, `set-document-property`                                                                                                                                                                                          | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row memberships and ordering are created, duplicated, moved, edited, and removed without deleting the backing page; bounded migrations atomically update row bodies and properties through the same canonical data model.                                                        | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `actions/migrate-content-database-rows.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`                                                          | `database-bulk-row-reliability`  | -                              |
+| database.rows                                      | database    | Add, duplicate, move, open, edit, and remove database rows                                                | action-backed         | `add-database-item`, `update-database-item`, `upsert-database-item-by-key`, `remove-database-items`, `duplicate-database-items`, `duplicate-database-item`, `migrate-content-database-rows`, `move-database-item`, `set-document-property`                                                                                                                                                                  | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row memberships and ordering are created, duplicated, moved, edited, and removed without deleting the backing page; bounded migrations atomically update row bodies and properties through the same canonical data model.                                                        | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `actions/upsert-database-item-by-key.db.test.ts`, `actions/migrate-content-database-rows.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`        | `database-bulk-row-reliability`  | -                              |
 | database.table-query-page                          | database    | Query one constrained page while retaining database metadata                                              | action-backed         | `query-content-database-items`                                                                                                                                                                                                                                                                                                                                                                              | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`                                                                                                    | -                                                                                                                                                                                                                                                                                         | This UI-only bounded projection is intentionally hidden with agentTool: false; agents use get-content-database for the complete database contract.                                                                                         | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`, `app/hooks/use-content-database.test.ts`                                                                                                                               | -                                | -                              |
 | editor.agent-assist-prompts                        | editor      | Ask AI from slash generation or comment context                                                           | client-assist         | -                                                                                                                                                                                                                                                                                                                                                                                                           | `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/CommentsSidebar.tsx`                                                                                                 | No direct durable mutation; the prompt asks the agent to use document actions when it decides to write.                                                                                                                                                                                   | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                                                                                       | -                                | -                              |
 | editor.client-formatting-and-insertions            | editor      | Rich text formatting, selection state, slash block insertion, and copy actions                            | client-only-ephemeral | -                                                                                                                                                                                                                                                                                                                                                                                                           | `app/components/editor/BubbleToolbar.tsx`, `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/DocumentToolbar.tsx`                                                      | -                                                                                                                                                                                                                                                                                         | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                                                                                       | -                                | -                              |

package/corpus/templates/content/parity/matrix.ts

@@ -345,6 +345,7 @@ export const parityMatrix: ParityRow[] = [
     status: "action-backed",
     actions: [
       "add-database-item",
+      "update-database-item",
       "upsert-database-item-by-key",
       "remove-database-items",
       "duplicate-database-items",
@@ -360,6 +361,7 @@ export const parityMatrix: ParityRow[] = [
     followUpPR: null,
     coverageRefs: [
       "actions/database-row-batch-actions.db.test.ts",
+      "actions/upsert-database-item-by-key.db.test.ts",
       "actions/migrate-content-database-rows.db.test.ts",
       "parity/__tests__/database-row-batch-reliability.test.ts",
     ],