@agent-native/core 0.154.3 → 0.154.5

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8208
+- template files: 8215

package/corpus/templates/content/.agents/skills/content/SKILL.md

@@ -121,8 +121,8 @@ For a named intake workflow:
    when the database has no form contract and all required values have already
    been confirmed.
 8. Treat submission as complete only when the successful result includes a
-   `createdDocumentId` and verification. Return the exact `url` or `urlPath`
-   from the result. The canonical Content row route is `/page/<createdDocumentId>`;
+   stable row IDs and verified read-back. Return the exact `url` or `urlPath`
+   from the result. The canonical Content row route is `/page/<documentId>`;
    never invent a different path, slug, ID, or host.
 
 When the user supplies a complete description in one message, do not force a

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

@@ -117,7 +117,9 @@ checkbox filters as initial property values, resolving option labels back to
 stable option IDs for select, status, and multi-select filters, so a row
 created under "Status is Published" remains visible instead of immediately
 disappearing. Agents can mirror that behavior by passing
-`--propertyValues '{"propertyId":"value"}'` to `add-database-item`. Filter
+the discovered property IDs in `propertyValues` to `add-database-item`. The
+action also requires the exact space/database/backing-page target, current
+schema revision, and a caller-stable idempotency key. Filter
 controls are type-aware: option properties choose from their configured
 options, option value editors can search existing options or create a new
 option from the typed query, and property settings can rename option labels
@@ -168,8 +170,10 @@ memberships, but they are references: moving one never reparents, transfers,
 or changes access to the referenced page. Files sidebar Custom order is
 different again: persist it per user and per database view with
 `update-content-database-personal-view`, without changing the shared Files
-membership order. Creating a database row returns the created item IDs and
-opens the new row page in the side preview. Duplicating a database row
+membership order. Creating a database row returns a receipt with stable item
+and document IDs, row link, revisions, affected fields, idempotency outcome,
+and verified read-back, then opens the new row page in the side preview.
+Duplicating a database row
 returns the duplicate item IDs and opens the copied row in the side preview
 so users can continue editing the new page immediately, including from
 table, list, and gallery row action menus. Board, calendar, and timeline
@@ -227,13 +231,25 @@ property definition.
 
 Use `create-content-database`, `create-inline-content-database`,
 `get-content-database`, `list-trashed-content-databases`,
-`restore-content-database`, `add-database-item`, `duplicate-database-item`,
+`restore-content-database`, `add-database-item`, `update-database-item`,
+`upsert-database-item-by-key`, `duplicate-database-item`,
 `duplicate-database-items`, `remove-database-items`, `move-database-item`,
 `update-content-database-view`, `list-document-properties`,
 `configure-document-property`, `set-document-property`,
 `duplicate-document-property`, and `delete-document-property`; do not edit
 property rows or view config via raw SQL when an action can do it.
 
+Read `get-content-database.mutationContract` immediately before a single-row
+mutation. Pass its exact target and schema revision to create, exact item and
+document IDs plus the current row revision to sparse update, and a fresh
+idempotency key for each intended effect. Reusing the same key with the same
+payload replays the durable receipt; reusing it with a different payload fails.
+Configure at most one ordinary text property as the database's natural key,
+then use `upsert-database-item-by-key` with that property. Natural-key upsert
+never accepts an arbitrary property name or silently chooses a field. Blocks,
+computed, system, source-managed, unknown, and relation properties are not
+writable through these actions; use their owning surfaces instead.
+
 For a bounded migration that must rewrite every existing row body while adding
 new property definitions and values, use `migrate-content-database-rows` rather
 than looping the single-row actions. Its `validate` phase is read-only; `apply`

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

@@ -0,0 +1,464 @@
+import { and, asc, eq, inArray } from "drizzle-orm";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  blocksContentHash,
+  blocksFieldId,
+  exposeBlocksFieldIdentity,
+  legacyBlocksFieldIdentity,
+  materializeLegacyBlocksFieldIdentity,
+  reconcileBlocksFieldIdentity,
+  type BlocksFieldIdentity,
+  type StoredBlocksFieldIdentity,
+} from "../shared/blocks-field-identity.js";
+import { lockDatabaseMemberships } from "./_database-membership-lock.js";
+
+type ContentDb = ReturnType<typeof getDb>;
+
+export interface PrimaryBlocksField {
+  propertyId: string;
+  ownerEmail: string;
+}
+
+export class BlocksFieldRevisionConflictError extends Error {
+  readonly statusCode = 409;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "BlocksFieldRevisionConflictError";
+  }
+}
+
+function nanoid(size = 12): string {
+  const chars =
+    "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+  let id = "";
+  const bytes = crypto.getRandomValues(new Uint8Array(size));
+  for (const byte of bytes) id += chars[byte % chars.length];
+  return id;
+}
+
+function groups<T>(values: T[], size: number): T[][] {
+  const result: T[][] = [];
+  for (let index = 0; index < values.length; index += size) {
+    result.push(values.slice(index, index + size));
+  }
+  return result;
+}
+
+export async function lockPrimaryBlocksFields(
+  db: ContentDb,
+  documentId: string,
+): Promise<PrimaryBlocksField[]> {
+  return (
+    (await lockPrimaryBlocksFieldsForDocuments(db, [documentId])).get(
+      documentId,
+    ) ?? []
+  );
+}
+
+export async function lockPrimaryBlocksFieldsForDocuments(
+  db: ContentDb,
+  documentIds: string[],
+): Promise<Map<string, PrimaryBlocksField[]>> {
+  const uniqueDocumentIds = [...new Set(documentIds)];
+  const memberships: Array<{
+    id: string;
+    documentId: string;
+  }> = [];
+  for (const documentIdGroup of groups(uniqueDocumentIds, 90)) {
+    memberships.push(
+      ...(await db
+        .select({
+          id: schema.contentDatabaseItems.id,
+          documentId: schema.contentDatabaseItems.documentId,
+        })
+        .from(schema.contentDatabaseItems)
+        .where(
+          inArray(schema.contentDatabaseItems.documentId, documentIdGroup),
+        )),
+    );
+  }
+  const membershipIds = memberships.map((membership) => membership.id);
+  await lockDatabaseMemberships(db, membershipIds);
+  if (membershipIds.length === 0) return new Map();
+
+  const fields: Array<{
+    documentId: string;
+    propertyId: string | null;
+    ownerEmail: string;
+  }> = [];
+  for (const membershipIdGroup of groups(membershipIds, 90)) {
+    fields.push(
+      ...(await db
+        .select({
+          documentId: schema.contentDatabaseItems.documentId,
+          propertyId: schema.contentDatabases.primaryBlocksPropertyId,
+          ownerEmail: schema.contentDatabases.ownerEmail,
+        })
+        .from(schema.contentDatabaseItems)
+        .innerJoin(
+          schema.contentDatabases,
+          eq(
+            schema.contentDatabases.id,
+            schema.contentDatabaseItems.databaseId,
+          ),
+        )
+        .where(inArray(schema.contentDatabaseItems.id, membershipIdGroup))),
+    );
+  }
+  const fieldsByDocument = new Map<string, Map<string, string>>();
+  for (const field of fields) {
+    if (!field.propertyId) continue;
+    const documentFields =
+      fieldsByDocument.get(field.documentId) ?? new Map<string, string>();
+    documentFields.set(field.propertyId, field.ownerEmail);
+    fieldsByDocument.set(field.documentId, documentFields);
+  }
+  return new Map(
+    [...fieldsByDocument].map(([id, documentFields]) => [
+      id,
+      [...documentFields].map(([propertyId, ownerEmail]) => ({
+        propertyId,
+        ownerEmail,
+      })),
+    ]),
+  );
+}
+
+async function loadStoredIdentity(
+  db: ContentDb,
+  fieldId: string,
+): Promise<StoredBlocksFieldIdentity | null> {
+  const [field] = await db
+    .select()
+    .from(schema.documentBlockFields)
+    .where(eq(schema.documentBlockFields.id, fieldId));
+  if (!field) return null;
+  const blocks = await db
+    .select()
+    .from(schema.documentBlocks)
+    .where(eq(schema.documentBlocks.fieldId, fieldId))
+    .orderBy(asc(schema.documentBlocks.sortIndex));
+  return {
+    fieldId,
+    revision: field.revision,
+    contentHash: field.contentHash,
+    blocks: blocks.map((block) => ({
+      id: block.id,
+      parentId: block.parentId,
+      kind: block.kind,
+      position: block.position,
+      addressable: block.addressable,
+      contentHash: block.contentHash,
+      markdown: block.markdown,
+      state: block.state === "deleted" ? "deleted" : "live",
+      deletedAtRevision: block.deletedAtRevision,
+      recoveredAtRevision: block.recoveredAtRevision,
+    })),
+  };
+}
+
+export async function readBlocksFieldIdentity(args: {
+  db?: ContentDb;
+  documentId: string;
+  propertyId: string;
+  markdown: string;
+}): Promise<BlocksFieldIdentity> {
+  const fieldId = blocksFieldId(args.documentId, args.propertyId);
+  const stored = await loadStoredIdentity(args.db ?? getDb(), fieldId);
+  return stored
+    ? exposeBlocksFieldIdentity(stored, args.markdown)
+    : legacyBlocksFieldIdentity(args);
+}
+
+export async function readBlocksFieldIdentities(args: {
+  db?: ContentDb;
+  fields: Array<{
+    documentId: string;
+    propertyId: string;
+    markdown: string;
+  }>;
+}): Promise<Map<string, BlocksFieldIdentity>> {
+  const db = args.db ?? getDb();
+  const inputs = new Map(
+    args.fields.map((field) => [
+      blocksFieldId(field.documentId, field.propertyId),
+      field,
+    ]),
+  );
+  const storedFields: Array<typeof schema.documentBlockFields.$inferSelect> =
+    [];
+  for (const ids of groups([...inputs.keys()], 200)) {
+    if (ids.length === 0) continue;
+    storedFields.push(
+      ...(await db
+        .select()
+        .from(schema.documentBlockFields)
+        .where(inArray(schema.documentBlockFields.id, ids))),
+    );
+  }
+  const storedById = new Map(storedFields.map((field) => [field.id, field]));
+  const storedBlocks: Array<typeof schema.documentBlocks.$inferSelect> = [];
+  for (const ids of groups(
+    storedFields.map((field) => field.id),
+    200,
+  )) {
+    if (ids.length === 0) continue;
+    storedBlocks.push(
+      ...(await db
+        .select()
+        .from(schema.documentBlocks)
+        .where(inArray(schema.documentBlocks.fieldId, ids))
+        .orderBy(asc(schema.documentBlocks.sortIndex))),
+    );
+  }
+  const blocksByField = new Map<
+    string,
+    Array<typeof schema.documentBlocks.$inferSelect>
+  >();
+  for (const block of storedBlocks) {
+    const values = blocksByField.get(block.fieldId) ?? [];
+    values.push(block);
+    blocksByField.set(block.fieldId, values);
+  }
+
+  const result = new Map<string, BlocksFieldIdentity>();
+  for (const [fieldId, input] of inputs) {
+    const field = storedById.get(fieldId);
+    if (!field) {
+      result.set(fieldId, legacyBlocksFieldIdentity(input));
+      continue;
+    }
+    result.set(
+      fieldId,
+      exposeBlocksFieldIdentity(
+        {
+          fieldId,
+          revision: field.revision,
+          contentHash: field.contentHash,
+          blocks: (blocksByField.get(fieldId) ?? []).map((block) => ({
+            id: block.id,
+            parentId: block.parentId,
+            kind: block.kind,
+            position: block.position,
+            addressable: block.addressable,
+            contentHash: block.contentHash,
+            markdown: block.markdown,
+            state: block.state === "deleted" ? "deleted" : "live",
+            deletedAtRevision: block.deletedAtRevision,
+            recoveredAtRevision: block.recoveredAtRevision,
+          })),
+        },
+        input.markdown,
+      ),
+    );
+  }
+  return result;
+}
+
+export async function persistBlocksFieldIdentity(args: {
+  db: ContentDb;
+  ownerEmail: string;
+  documentId: string;
+  propertyId: string;
+  previousMarkdown: string;
+  markdown: string;
+  expectedRevision?: number;
+  now: string;
+}): Promise<StoredBlocksFieldIdentity> {
+  const fieldId = blocksFieldId(args.documentId, args.propertyId);
+  const stored = await loadStoredIdentity(args.db, fieldId);
+  const actualRevision = stored?.revision ?? 0;
+  if (
+    args.expectedRevision !== undefined &&
+    args.expectedRevision !== actualRevision
+  ) {
+    throw new BlocksFieldRevisionConflictError(
+      `Blocks field revision conflict: expected ${args.expectedRevision}, current ${actualRevision}`,
+    );
+  }
+
+  let previous =
+    stored ??
+    materializeLegacyBlocksFieldIdentity({
+      documentId: args.documentId,
+      propertyId: args.propertyId,
+      markdown: args.previousMarkdown,
+    });
+
+  // A legacy whole-field writer may have changed Markdown without updating the
+  // sidecar. Reconcile exact unique blocks first and report the resulting extra
+  // revision instead of silently pretending continuity was complete.
+  if (previous.contentHash !== blocksContentHash(args.previousMarkdown)) {
+    previous = reconcileBlocksFieldIdentity({
+      documentId: args.documentId,
+      propertyId: args.propertyId,
+      previous,
+      markdown: args.previousMarkdown,
+      createId: () => `block_${nanoid(16)}`,
+    });
+  }
+
+  let next = reconcileBlocksFieldIdentity({
+    documentId: args.documentId,
+    propertyId: args.propertyId,
+    previous,
+    markdown: args.markdown,
+    createId: () => `block_${nanoid(16)}`,
+  });
+
+  if (next.blocks.length > 0) {
+    const existingOwners = await args.db
+      .select({
+        id: schema.documentBlocks.id,
+        fieldId: schema.documentBlocks.fieldId,
+      })
+      .from(schema.documentBlocks)
+      .where(
+        inArray(
+          schema.documentBlocks.id,
+          next.blocks.map((block) => block.id),
+        ),
+      );
+    const remappedIds = new Map<string, string>();
+    const reserved = new Set(next.blocks.map((block) => block.id));
+    for (const existing of existingOwners) {
+      if (existing.fieldId === fieldId) continue;
+      let replacement = `block_${nanoid(16)}`;
+      while (reserved.has(replacement)) replacement = `block_${nanoid(16)}`;
+      reserved.add(replacement);
+      remappedIds.set(existing.id, replacement);
+    }
+    if (remappedIds.size > 0) {
+      next = {
+        ...next,
+        blocks: next.blocks.map((block) => ({
+          ...block,
+          id: remappedIds.get(block.id) ?? block.id,
+          parentId: block.parentId
+            ? (remappedIds.get(block.parentId) ?? block.parentId)
+            : null,
+        })),
+      };
+    }
+  }
+
+  if (stored) {
+    const applied = await args.db
+      .update(schema.documentBlockFields)
+      .set({
+        revision: next.revision,
+        contentHash: next.contentHash,
+        updatedAt: args.now,
+      })
+      .where(
+        and(
+          eq(schema.documentBlockFields.id, fieldId),
+          eq(schema.documentBlockFields.revision, actualRevision),
+        ),
+      )
+      .returning({ id: schema.documentBlockFields.id });
+    if (applied.length === 0) {
+      throw new BlocksFieldRevisionConflictError(
+        `Blocks field revision conflict: expected ${actualRevision}, current revision changed`,
+      );
+    }
+  } else {
+    const inserted = await args.db
+      .insert(schema.documentBlockFields)
+      .values({
+        id: fieldId,
+        ownerEmail: args.ownerEmail,
+        documentId: args.documentId,
+        propertyId: args.propertyId,
+        revision: next.revision,
+        contentHash: next.contentHash,
+        createdAt: args.now,
+        updatedAt: args.now,
+      })
+      .onConflictDoNothing()
+      .returning({ id: schema.documentBlockFields.id });
+    if (inserted.length === 0) {
+      throw new BlocksFieldRevisionConflictError(
+        "Blocks field revision conflict: concurrent first materialization",
+      );
+    }
+  }
+  await args.db
+    .delete(schema.documentBlocks)
+    .where(eq(schema.documentBlocks.fieldId, fieldId));
+  if (next.blocks.length > 0) {
+    await args.db.insert(schema.documentBlocks).values(
+      next.blocks.map((block, sortIndex) => ({
+        id: block.id,
+        ownerEmail: args.ownerEmail,
+        fieldId,
+        parentId: block.parentId,
+        kind: block.kind,
+        position: block.position,
+        sortIndex,
+        addressable: block.addressable,
+        contentHash: block.contentHash,
+        markdown: block.markdown,
+        state: block.state,
+        deletedAtRevision: block.deletedAtRevision,
+        recoveredAtRevision: block.recoveredAtRevision,
+        createdAt: args.now,
+        updatedAt: args.now,
+      })),
+    );
+  }
+  return next;
+}
+
+export async function deleteBlocksFieldIdentity(args: {
+  db: ContentDb;
+  documentId?: string;
+  documentIds?: string[];
+  propertyId?: string;
+  propertyIds?: string[];
+}): Promise<void> {
+  if (
+    !args.documentId &&
+    !args.documentIds?.length &&
+    !args.propertyId &&
+    !args.propertyIds?.length
+  ) {
+    return;
+  }
+  const clauses = [];
+  if (args.documentId) {
+    clauses.push(eq(schema.documentBlockFields.documentId, args.documentId));
+  }
+  if (args.documentIds?.length) {
+    clauses.push(
+      inArray(schema.documentBlockFields.documentId, args.documentIds),
+    );
+  }
+  if (args.propertyId) {
+    clauses.push(eq(schema.documentBlockFields.propertyId, args.propertyId));
+  }
+  if (args.propertyIds?.length) {
+    clauses.push(
+      inArray(schema.documentBlockFields.propertyId, args.propertyIds),
+    );
+  }
+  const fields = await args.db
+    .select({ id: schema.documentBlockFields.id })
+    .from(schema.documentBlockFields)
+    .where(clauses.length === 1 ? clauses[0] : and(...clauses));
+  if (fields.length === 0) return;
+  await args.db.delete(schema.documentBlocks).where(
+    inArray(
+      schema.documentBlocks.fieldId,
+      fields.map((field) => field.id),
+    ),
+  );
+  await args.db.delete(schema.documentBlockFields).where(
+    inArray(
+      schema.documentBlockFields.id,
+      fields.map((field) => field.id),
+    ),
+  );
+}