@agent-native/core 0.154.3 → 0.154.5

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

@@ -234,6 +234,7 @@ export const contentDatabases = table(
     ownerBlockId: text("owner_block_id"),
     title: text("title").notNull().default("Untitled database"),
     systemRole: text("system_role"),
+    naturalKeyPropertyId: text("natural_key_property_id"),
     viewConfigJson: text("view_config_json").notNull().default("{}"),
     filesSystemPropertiesSeeded: integer("files_system_properties_seeded")
       .notNull()
@@ -287,9 +288,9 @@ export const contentDatabaseItems = table(
   ],
 );
 
-// Opt-in stable-key claims are the durable concurrency fence for the generic
-// database-row upsert action. They intentionally do not constrain ordinary
-// property editing or change add-database-item behavior.
+// Opt-in stable-key claims are the durable concurrency fence for configured
+// natural-key upserts. Ordinary property editing stays independent until a
+// text property is explicitly selected as the database's natural key.
 export const contentDatabaseItemKeyClaims = table(
   "content_database_item_key_claims",
   {
@@ -494,6 +495,41 @@ export const contentDatabaseMigrationReceipts = table(
   ],
 );
 
+export const contentDatabaseRowMutationReceipts = table(
+  "content_database_row_mutation_receipts",
+  {
+    id: text("id").primaryKey(),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    orgId: text("org_id"),
+    spaceId: text("space_id").notNull(),
+    databaseId: text("database_id").notNull(),
+    databaseDocumentId: text("database_document_id").notNull(),
+    operation: text("operation").notNull(),
+    itemId: text("item_id").notNull(),
+    documentId: text("document_id").notNull(),
+    idempotencyKey: text("idempotency_key").notNull(),
+    payloadDigest: text("payload_digest").notNull(),
+    schemaRevision: text("schema_revision").notNull(),
+    preRowRevision: text("pre_row_revision"),
+    postRowRevision: text("post_row_revision").notNull(),
+    resultJson: text("result_json").notNull().default("{}"),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+  (receipt) => [
+    uniqueIndex(
+      "content_database_row_mutation_receipts_database_key_unique",
+    ).on(receipt.databaseId, receipt.idempotencyKey),
+    index("content_database_row_mutation_receipts_owner_database_idx").on(
+      receipt.ownerEmail,
+      receipt.databaseId,
+    ),
+    index("content_database_row_mutation_receipts_document_idx").on(
+      receipt.documentId,
+    ),
+  ],
+);
+
 export const documentPropertyValues = table("document_property_values", {
   id: text("id").primaryKey(),
   ownerEmail: text("owner_email").notNull().default("local@localhost"),
@@ -523,4 +559,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,91 @@ 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`,
+      },
+    },
+    {
+      version: 84,
+      name: "content-database-row-mutation-contract",
+      sql: `ALTER TABLE content_databases ADD COLUMN IF NOT EXISTS natural_key_property_id TEXT;
+      CREATE TABLE IF NOT EXISTS content_database_row_mutation_receipts (
+        id TEXT PRIMARY KEY,
+        owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+        org_id TEXT,
+        space_id TEXT NOT NULL,
+        database_id TEXT NOT NULL,
+        database_document_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        item_id TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        payload_digest TEXT NOT NULL,
+        schema_revision TEXT NOT NULL,
+        pre_row_revision TEXT,
+        post_row_revision TEXT NOT NULL,
+        result_json TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS content_database_row_mutation_receipts_database_key_unique
+        ON content_database_row_mutation_receipts (database_id, idempotency_key);
+      CREATE INDEX IF NOT EXISTS content_database_row_mutation_receipts_owner_database_idx
+        ON content_database_row_mutation_receipts (owner_email, database_id);
+      CREATE INDEX IF NOT EXISTS content_database_row_mutation_receipts_document_idx
+        ON content_database_row_mutation_receipts (document_id)`,
+    },
   ],
   { 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 {
@@ -223,6 +225,7 @@ export interface ConfigureDocumentPropertyRequest {
   description?: string;
   visibility?: DocumentPropertyVisibility;
   options?: DocumentPropertyOptions;
+  naturalKey?: boolean;
 }
 
 export interface SetDocumentPropertyRequest {
@@ -230,6 +233,7 @@ export interface SetDocumentPropertyRequest {
   databaseId: string;
   propertyId: string;
   value: DocumentPropertyValue;
+  expectedBlocksFieldRevision?: number;
 }
 
 export interface DuplicateDocumentPropertyRequest {
@@ -255,8 +259,10 @@ export interface ReorderDocumentPropertyRequest {
 export interface ContentDatabase {
   id: string;
   documentId: string;
+  spaceId?: string | null;
   title: string;
   systemRole?: string | null;
+  naturalKeyPropertyId?: string | null;
   description?: string;
   viewConfig: ContentDatabaseViewConfig;
   createdAt: string;
@@ -466,6 +472,62 @@ export interface ContentDatabaseItem {
   // a secondary source contributes on top of it. Absent for non-federated rows.
   canonicalKey?: string | null;
   sourceOverlays?: ContentDatabaseSourceOverlay[];
+  rowRevision?: string;
+}
+
+export interface ContentDatabaseMutationTarget {
+  authorityScope:
+    | { kind: "personal"; id: string }
+    | { kind: "organization"; id: string };
+  spaceId: string;
+  databaseId: string;
+  databaseDocumentId: string;
+}
+
+export interface ContentDatabaseMutationContract {
+  target: ContentDatabaseMutationTarget;
+  schemaRevision: string;
+  naturalKeyPropertyId: string | null;
+  properties: Array<{
+    id: string;
+    name: string;
+    type: DocumentPropertyType;
+    writable: boolean;
+    sourceManaged: boolean;
+    acceptedShape: string | null;
+    options: DocumentPropertyOptions;
+  }>;
+}
+
+export interface ContentDatabaseRowMutationReceipt {
+  receiptId: string;
+  operation: "create" | "update" | "upsert";
+  outcome: "created" | "updated" | "unchanged";
+  target: ContentDatabaseMutationTarget;
+  schemaRevision: string;
+  row: {
+    itemId: string;
+    documentId: string;
+    urlPath: string;
+    rowRevision: string;
+  };
+  affected: { title: boolean; propertyIds: string[] };
+  idempotency: {
+    key: string;
+    result: "applied" | "replayed";
+    payloadDigest: string;
+  };
+  revisions: { before: string | null; after: string };
+  readback: {
+    verified: true;
+    title: string;
+    propertyValues: Record<string, DocumentPropertyValue>;
+  };
+}
+
+export interface ContentDatabaseRowMutationResult {
+  receipt: ContentDatabaseRowMutationReceipt;
+  createdItem?: ContentDatabaseItem;
 }
 
 // A secondary source's read-only contribution to a federated row, matched on the
@@ -825,6 +887,7 @@ export interface ContentDatabaseResponse {
   removedCount?: number;
   timings?: BuilderActionTiming[];
   tableQueryMode?: "server" | "client-required";
+  mutationContract?: ContentDatabaseMutationContract;
   /** Client-only optimistic state while real provider rows are being attached. */
   attachPreview?: {
     sourceTable: string;
@@ -889,9 +952,22 @@ export interface CreateInlineDatabaseResponse {
 }
 
 export interface AddDatabaseItemRequest {
-  databaseId: string;
+  target: ContentDatabaseMutationTarget;
+  expectedSchemaRevision: string;
+  idempotencyKey: string;
   title?: string;
-  propertyValues?: Record<string, DocumentPropertyValue>;
+  propertyValues?: Record<string, unknown>;
+}
+
+export interface UpdateDatabaseItemRequest extends AddDatabaseItemRequest {
+  itemId: string;
+  documentId: string;
+  expectedRowRevision: string;
+}
+
+export interface UpsertDatabaseItemByKeyRequest extends AddDatabaseItemRequest {
+  keyValue: string;
+  expectedRowRevision: string | null;
 }
 
 export interface SubmitContentDatabaseFormRequest {