@agent-native/core 0.154.4 → 0.155.0

package/corpus/templates/content/actions/_database-utils.ts

@@ -45,6 +45,10 @@ import {
   normalizeContentSpaceEmail,
   resolveContentSpaceAccess,
 } from "./_content-space-access.js";
+import {
+  databaseRowRevision,
+  getDatabaseMutationContract,
+} from "./_database-row-mutation.js";
 import { getAllContentDatabaseSourceSnapshots } from "./_database-source-utils.js";
 import {
   applyFederatedOverlayValues,
@@ -1050,6 +1054,21 @@ export async function getContentDatabasePageResponse(
         queued: bodyHydrationQueued,
       }),
       properties: propertiesByDocumentId.get(document.id) ?? [],
+      rowRevision: databaseRowRevision({
+        itemId: item.id,
+        documentId: document.id,
+        title: document.title,
+        values: (propertiesByDocumentId.get(document.id) ?? [])
+          .filter(
+            (property) =>
+              !isBlocksPropertyType(property.definition.type) &&
+              !isComputedPropertyType(property.definition.type),
+          )
+          .map((property) => ({
+            propertyId: property.definition.id,
+            value: property.value,
+          })),
+      }),
     });
   }
 
@@ -1195,6 +1214,26 @@ export async function getContentDatabaseResponse(
     sources: page.sources,
     pagination: page.pagination,
     tableQueryMode: page.tableQueryMode,
+    mutationContract:
+      page.databaseRecord.spaceId && !page.databaseRecord.systemRole
+        ? await getDatabaseMutationContract(
+            {
+              authorityScope: page.databaseRecord.orgId
+                ? {
+                    kind: "organization",
+                    id: page.databaseRecord.orgId,
+                  }
+                : {
+                    kind: "personal",
+                    id: page.databaseRecord.ownerEmail,
+                  },
+              spaceId: page.databaseRecord.spaceId,
+              databaseId: page.databaseRecord.id,
+              databaseDocumentId: page.databaseRecord.documentId,
+            },
+            { accessAlreadyResolved: true },
+          )
+        : undefined,
   };
 }
 
@@ -1470,6 +1509,11 @@ export async function deleteDatabaseDataForDocument(
       .where(
         eq(schema.contentDatabaseMigrationReceipts.databaseId, database.id),
       );
+    await db
+      .delete(schema.contentDatabaseRowMutationReceipts)
+      .where(
+        eq(schema.contentDatabaseRowMutationReceipts.databaseId, database.id),
+      );
     await db
       .delete(schema.documentPropertyDefinitions)
       .where(eq(schema.documentPropertyDefinitions.databaseId, database.id));

package/corpus/templates/content/actions/_property-utils.ts

@@ -65,7 +65,8 @@ type ContentDatabaseSummaryRow = Pick<
   | "viewConfigJson"
   | "createdAt"
   | "updatedAt"
->;
+> &
+  Partial<Pick<ContentDatabaseRow, "spaceId" | "naturalKeyPropertyId">>;
 type ContentDatabaseItemRow = InferSelectModel<
   typeof schema.contentDatabaseItems
 >;
@@ -199,8 +200,10 @@ export function serializeDatabase(
   return {
     id: database.id,
     documentId: database.documentId,
+    spaceId: database.spaceId,
     title: database.title,
     systemRole: database.systemRole,
+    naturalKeyPropertyId: database.naturalKeyPropertyId,
     description,
     viewConfig: parseDatabaseViewConfig(database.viewConfigJson),
     createdAt: database.createdAt,

package/corpus/templates/content/actions/add-comment.ts

@@ -44,7 +44,8 @@ function displayNameFromEmail(email: string): string {
 }
 
 export default defineAction({
-  description: "Add a comment to a document. For new threads, omit threadId.",
+  description:
+    "Add a comment to a document. Comment text supports inline Markdown for emphasis, inline code, links, and line breaks; headings are flattened. For new threads, omit threadId.",
   schema: z.object({
     documentId: z.string().optional().describe("Document ID (required)"),
     content: z.string().optional().describe("Comment text (required)"),

package/corpus/templates/content/actions/add-database-item.ts

@@ -1,255 +1,77 @@
 import { defineAction } from "@agent-native/core";
-import { writeAppState } from "@agent-native/core/application-state";
-import { getRequestUserEmail } from "@agent-native/core/server/request-context";
-import { assertAccess } from "@agent-native/core/sharing";
-import { and, eq, inArray, isNull, sql } from "drizzle-orm";
+import { buildDeepLink } from "@agent-native/core/server";
 import { z } from "zod";
 
-import { getDb, schema } from "../server/db/index.js";
+import type { ContentDatabaseRowMutationResult } from "../shared/api.js";
 import {
-  isComputedPropertyType,
-  type DocumentPropertyType,
-} from "../shared/properties.js";
-import {
-  lockContentDatabaseMutation,
-  touchContentDatabase,
-} from "./_content-database-mutation-lock.js";
-import { ensureDocumentFilesMembership } from "./_content-files.js";
+  createDatabaseRow,
+  databaseMutationEnvelopeSchema,
+} from "./_database-row-mutation.js";
 import { getContentDatabaseResponse } from "./_database-utils.js";
-import {
-  databaseItemsPositionScope,
-  documentsPositionScope,
-  withPositionLock,
-} from "./_position-utils.js";
-import { nanoid, normalizedValueJson } from "./_property-utils.js";
 
-export default defineAction({
-  description: "Add a page item to a content database table.",
-  schema: z.object({
-    databaseId: z.string().describe("Database ID"),
-    title: z.string().optional().describe("New row page title"),
-    propertyValues: z
-      .record(z.string(), z.unknown())
-      .optional()
-      .describe("Initial property values keyed by property definition ID"),
-  }),
-  run: async ({ databaseId, title, propertyValues }) => {
-    const db = getDb();
-    const [database] = await db
-      .select()
-      .from(schema.contentDatabases)
-      .where(
-        and(
-          eq(schema.contentDatabases.id, databaseId),
-          isNull(schema.contentDatabases.deletedAt),
-        ),
-      );
-    if (!database) throw new Error(`Database "${databaseId}" not found`);
-    if (database.systemRole === "workspaces") {
-      throw new Error("Use create-content-space to add a workspace");
-    }
+const schema = databaseMutationEnvelopeSchema.extend({
+  title: z
+    .string()
+    .trim()
+    .min(1)
+    .max(500)
+    .optional()
+    .describe("New row page title"),
+  propertyValues: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("Strict property values keyed by property definition ID"),
+});
 
-    const access = await assertAccess(
-      "document",
-      database.documentId,
-      "editor",
+export default defineAction({
+  description:
+    "Create one row in an exact ordinary Content database using its discovered schema revision. Strictly validates every non-Blocks property, applies the side effect once per idempotency key, and returns a verified receipt with stable row identity.",
+  schema,
+  audit: {
+    recordInputs: false,
+    target: (args) => ({
+      type: "content-database",
+      id: args.target.databaseId,
+      visibility: "private",
+    }),
+    summary: (_args, result) => {
+      const receipt = (result as ContentDatabaseRowMutationResult | null)
+        ?.receipt;
+      return receipt
+        ? `Created Content database row ${receipt.row.itemId}`
+        : "Created Content database row";
+    },
+  },
+  run: async (args): Promise<ContentDatabaseRowMutationResult> => {
+    const result = await createDatabaseRow(args);
+    const response = await getContentDatabaseResponse(
+      result.receipt.target.databaseId,
+      {
+        limit: 1,
+        offset: 0,
+        documentIds: [result.receipt.row.documentId],
+      },
     );
-    const databaseDocument = access.resource;
-    if (
-      database.spaceId &&
-      databaseDocument.spaceId &&
-      databaseDocument.spaceId !== database.spaceId
-    ) {
+    const createdItem = response.items[0];
+    if (!createdItem || createdItem.id !== result.receipt.row.itemId) {
       throw new Error(
-        `Database "${databaseId}" has inconsistent Content space`,
+        "Created row receipt did not resolve to its exact read-back.",
       );
     }
-    const now = new Date().toISOString();
-    const databaseSpaceId =
-      database.spaceId ?? (databaseDocument.spaceId as string | null);
-    if (!databaseSpaceId) {
-      throw new Error("Database does not belong to a Content space.");
-    }
-    if (databaseSpaceId && (!database.spaceId || !databaseDocument.spaceId)) {
-      await db.transaction(async (tx) => {
-        if (!database.spaceId) {
-          await tx
-            .update(schema.contentDatabases)
-            .set({ spaceId: databaseSpaceId, updatedAt: now })
-            .where(eq(schema.contentDatabases.id, databaseId));
-        }
-        if (!databaseDocument.spaceId) {
-          await tx
-            .update(schema.documents)
-            .set({ spaceId: databaseSpaceId, updatedAt: now })
-            .where(eq(schema.documents.id, database.documentId));
-        }
-        await ensureDocumentFilesMembership(tx, database.documentId, now);
-      });
-    }
-
-    const documentId = nanoid();
-    const itemId = nanoid();
-
-    const inheritedShares = await db
-      .select({
-        principalType: schema.documentShares.principalType,
-        principalId: schema.documentShares.principalId,
-        role: schema.documentShares.role,
-      })
-      .from(schema.documentShares)
-      .where(eq(schema.documentShares.resourceId, database.documentId));
-
-    const initialValues = Object.entries(propertyValues ?? {});
-
-    await withPositionLock(
-      documentsPositionScope(database.ownerEmail, database.documentId),
-      () =>
-        withPositionLock(databaseItemsPositionScope(databaseId), async () => {
-          await db.transaction(async (tx) => {
-            await lockContentDatabaseMutation(
-              tx as unknown as ReturnType<typeof getDb>,
-              databaseId,
-            );
-            await touchContentDatabase(
-              tx as unknown as ReturnType<typeof getDb>,
-              databaseId,
-              now,
-            );
-            const propertyValueRows: Array<
-              typeof schema.documentPropertyValues.$inferInsert
-            > = [];
-            if (initialValues.length > 0) {
-              const requestedPropertyIds = initialValues.map(
-                ([propertyId]) => propertyId,
-              );
-              const definitions = await tx
-                .select()
-                .from(schema.documentPropertyDefinitions)
-                .where(
-                  and(
-                    eq(
-                      schema.documentPropertyDefinitions.ownerEmail,
-                      database.ownerEmail,
-                    ),
-                    eq(
-                      schema.documentPropertyDefinitions.databaseId,
-                      databaseId,
-                    ),
-                    inArray(
-                      schema.documentPropertyDefinitions.id,
-                      requestedPropertyIds,
-                    ),
-                  ),
-                );
-              const definitionById = new Map(
-                definitions.map((definition) => [definition.id, definition]),
-              );
-              for (const [propertyId, value] of initialValues) {
-                const definition = definitionById.get(propertyId);
-                const type = definition?.type as
-                  | DocumentPropertyType
-                  | undefined;
-                if (!definition || !type || isComputedPropertyType(type))
-                  continue;
-                propertyValueRows.push({
-                  id: nanoid(),
-                  ownerEmail: database.ownerEmail,
-                  documentId,
-                  propertyId,
-                  valueJson: normalizedValueJson(type, value),
-                  createdAt: now,
-                  updatedAt: now,
-                });
-              }
-            }
-            const [maxDocPos] = await tx
-              .select({ max: sql<number>`COALESCE(MAX(position), -1)` })
-              .from(schema.documents)
-              .where(
-                and(
-                  eq(schema.documents.ownerEmail, database.ownerEmail),
-                  eq(schema.documents.parentId, database.documentId),
-                ),
-              );
-            const [maxItemPos] = await tx
-              .select({ max: sql<number>`COALESCE(MAX(position), -1)` })
-              .from(schema.contentDatabaseItems)
-              .where(eq(schema.contentDatabaseItems.databaseId, databaseId));
-
-            await tx.insert(schema.documents).values({
-              id: documentId,
-              spaceId: databaseSpaceId,
-              ownerEmail: database.ownerEmail,
-              orgId: database.orgId,
-              parentId: database.documentId,
-              title: title?.trim() ?? "",
-              content: "",
-              icon: null,
-              position: (maxDocPos?.max ?? -1) + 1,
-              isFavorite: 0,
-              hideFromSearch: databaseDocument.hideFromSearch ?? 0,
-              visibility: databaseDocument.visibility ?? "private",
-              createdAt: now,
-              updatedAt: now,
-            });
-            await tx.insert(schema.contentDatabaseItems).values({
-              id: itemId,
-              ownerEmail: database.ownerEmail,
-              orgId: database.orgId,
-              databaseId,
-              documentId,
-              position: (maxItemPos?.max ?? -1) + 1,
-              createdAt: now,
-              updatedAt: now,
-            });
-            if (inheritedShares.length > 0) {
-              await tx.insert(schema.documentShares).values(
-                inheritedShares.map((share) => ({
-                  id: nanoid(),
-                  resourceId: documentId,
-                  principalType: share.principalType,
-                  principalId: share.principalId,
-                  role: share.role,
-                  createdBy: getRequestUserEmail() ?? database.ownerEmail,
-                  createdAt: now,
-                })),
-              );
-            }
-            if (propertyValueRows.length > 0) {
-              await tx
-                .insert(schema.documentPropertyValues)
-                .values(propertyValueRows);
-            }
-            await ensureDocumentFilesMembership(tx, documentId, now);
-          });
-        }),
-    );
-
-    await writeAppState("refresh-signal", { ts: Date.now() }).catch(() => {
-      // The row is already committed; polling will reconcile if a concurrent
-      // SQLite writer briefly blocks this best-effort refresh hint.
-    });
-
-    const response = await getContentDatabaseResponse(databaseId, {
-      limit: 100,
-      offset: 0,
-    });
-    const createdItem =
-      response.items.find((item) => item.id === itemId) ??
-      (
-        await getContentDatabaseResponse(databaseId, {
-          limit: 1,
-          offset: 0,
-          documentIds: [documentId],
-        })
-      ).items.find((item) => item.id === itemId);
+    return { ...result, createdItem };
+  },
+  link: ({ result }) => {
+    const documentId = (result as ContentDatabaseRowMutationResult | null)
+      ?.receipt.row.documentId;
+    if (!documentId) return null;
     return {
-      ...response,
-      createdItem,
-      createdItemId: itemId,
-      createdDocumentId: documentId,
-      createdDocumentUpdatedAt: now,
+      url: buildDeepLink({
+        app: "content",
+        view: "editor",
+        params: { documentId },
+      }),
+      label: "Open database row",
+      view: "editor",
     };
   },
 });

package/corpus/templates/content/actions/configure-document-property.ts

@@ -52,6 +52,12 @@ export default defineAction({
         "Stable guidance describing what this property means and which value belongs here",
       ),
     type: z.enum(CREATABLE_DOCUMENT_PROPERTY_TYPES).describe("Property type"),
+    naturalKey: z
+      .boolean()
+      .optional()
+      .describe(
+        "Declare or clear this ordinary text property as the database's single natural key",
+      ),
     visibility: z
       .enum(DOCUMENT_PROPERTY_VISIBILITIES)
       .optional()
@@ -104,6 +110,7 @@ export default defineAction({
     const now = new Date().toISOString();
     const name = args.name.trim();
     const type = args.type as DocumentPropertyType;
+    const propertyId = args.id ?? nanoid();
     const optionsJson = optionsForNewProperty(type, args.options as any);
     const database = await resolvePropertyDatabaseForDocument(
       document,
@@ -115,6 +122,14 @@ export default defineAction({
         "Properties belong to databases. Create or open a database before adding properties.",
       );
     }
+    if (args.naturalKey === true && type !== "text") {
+      throw new Error(
+        "A database natural key must be an ordinary text property.",
+      );
+    }
+    if (args.naturalKey !== undefined && database.systemRole) {
+      throw new Error("System databases cannot configure a natural key.");
+    }
 
     if (args.id) {
       const [existing] = await db
@@ -136,6 +151,11 @@ export default defineAction({
           tx as unknown as ReturnType<typeof getDb>,
           database.id,
         );
+        const [lockedDatabase] = await tx
+          .select()
+          .from(schema.contentDatabases)
+          .where(eq(schema.contentDatabases.id, database.id));
+        if (!lockedDatabase) throw new Error("Database not found.");
         let [lockedDefinition] = await tx
           .select()
           .from(schema.documentPropertyDefinitions)
@@ -151,6 +171,14 @@ export default defineAction({
           );
         if (!lockedDefinition)
           throw new Error(`Property "${args.id}" not found`);
+        if (
+          lockedDatabase.naturalKeyPropertyId === args.id &&
+          type !== "text"
+        ) {
+          throw new Error(
+            "Clear the database natural key before changing this property's type.",
+          );
+        }
         if (lockedDefinition.systemRole) {
           throw new Error("System properties cannot be changed.");
         }
@@ -265,6 +293,13 @@ export default defineAction({
             updatedAt: now,
           })
           .where(eq(schema.documentPropertyDefinitions.id, args.id!));
+        await configureNaturalKey(tx, {
+          database: lockedDatabase,
+          propertyId,
+          naturalKey: args.naturalKey,
+          ownerEmail: document.ownerEmail,
+          now,
+        });
       });
     } else {
       await withPositionLock(
@@ -275,6 +310,11 @@ export default defineAction({
               tx as unknown as ReturnType<typeof getDb>,
               database.id,
             );
+            const [lockedDatabase] = await tx
+              .select()
+              .from(schema.contentDatabases)
+              .where(eq(schema.contentDatabases.id, database.id));
+            if (!lockedDatabase) throw new Error("Database not found.");
             const [maxPos] = await tx
               .select({
                 max: sql<number>`COALESCE(MAX(position), -1)`,
@@ -294,7 +334,7 @@ export default defineAction({
               );
 
             await tx.insert(schema.documentPropertyDefinitions).values({
-              id: nanoid(),
+              id: propertyId,
               ownerEmail: document.ownerEmail,
               orgId: document.orgId ?? null,
               databaseId: database.id,
@@ -307,6 +347,13 @@ export default defineAction({
               createdAt: now,
               updatedAt: now,
             });
+            await configureNaturalKey(tx, {
+              database: lockedDatabase,
+              propertyId,
+              naturalKey: args.naturalKey,
+              ownerEmail: document.ownerEmail,
+              now,
+            });
           });
         },
       );
@@ -321,3 +368,120 @@ export default defineAction({
     };
   },
 });
+
+async function configureNaturalKey(
+  tx: Parameters<Parameters<ReturnType<typeof getDb>["transaction"]>[0]>[0],
+  args: {
+    database: typeof schema.contentDatabases.$inferSelect;
+    propertyId: string;
+    naturalKey: boolean | undefined;
+    ownerEmail: string;
+    now: string;
+  },
+) {
+  if (args.naturalKey === undefined) return;
+  if (!args.naturalKey) {
+    if (args.database.naturalKeyPropertyId === args.propertyId) {
+      await tx
+        .delete(schema.contentDatabaseItemKeyClaims)
+        .where(
+          and(
+            eq(
+              schema.contentDatabaseItemKeyClaims.databaseId,
+              args.database.id,
+            ),
+            eq(schema.contentDatabaseItemKeyClaims.propertyId, args.propertyId),
+          ),
+        );
+      await tx
+        .update(schema.contentDatabases)
+        .set({ naturalKeyPropertyId: null, updatedAt: args.now })
+        .where(eq(schema.contentDatabases.id, args.database.id));
+    }
+    return;
+  }
+  if (
+    args.database.naturalKeyPropertyId &&
+    args.database.naturalKeyPropertyId !== args.propertyId
+  ) {
+    throw new Error(
+      "Clear the existing database natural key before configuring another one.",
+    );
+  }
+  const [sourceField] = await tx
+    .select({ id: schema.contentDatabaseSourceFields.id })
+    .from(schema.contentDatabaseSourceFields)
+    .where(eq(schema.contentDatabaseSourceFields.propertyId, args.propertyId))
+    .limit(1);
+  if (sourceField) {
+    throw new Error("A source-managed property cannot be a natural key.");
+  }
+  const values = await tx
+    .select({
+      valueJson: schema.documentPropertyValues.valueJson,
+      itemId: schema.contentDatabaseItems.id,
+      documentId: schema.contentDatabaseItems.documentId,
+    })
+    .from(schema.contentDatabaseItems)
+    .innerJoin(
+      schema.documentPropertyValues,
+      and(
+        eq(
+          schema.documentPropertyValues.documentId,
+          schema.contentDatabaseItems.documentId,
+        ),
+        eq(schema.documentPropertyValues.propertyId, args.propertyId),
+      ),
+    )
+    .where(eq(schema.contentDatabaseItems.databaseId, args.database.id));
+  const claims = new Map<string, (typeof values)[number]>();
+  for (const value of values) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(value.valueJson);
+    } catch {
+      throw new Error("Natural key values must be readable strings.");
+    }
+    if (parsed === null || parsed === "") continue;
+    if (typeof parsed !== "string") {
+      throw new Error("Natural key values must be non-empty strings.");
+    }
+    if (!parsed.trim()) {
+      throw new Error("Natural key values must be non-empty strings.");
+    }
+    if (claims.has(value.valueJson)) {
+      throw new Error(
+        `Natural key value ${value.valueJson} belongs to more than one row.`,
+      );
+    }
+    claims.set(value.valueJson, value);
+  }
+  await tx
+    .delete(schema.contentDatabaseItemKeyClaims)
+    .where(
+      and(
+        eq(schema.contentDatabaseItemKeyClaims.databaseId, args.database.id),
+        eq(schema.contentDatabaseItemKeyClaims.propertyId, args.propertyId),
+      ),
+    );
+  if (claims.size > 0) {
+    await tx.insert(schema.contentDatabaseItemKeyClaims).values(
+      [...claims.entries()].map(([keyValueJson, value]) => ({
+        id: nanoid(),
+        ownerEmail: args.ownerEmail,
+        orgId: args.database.orgId,
+        databaseId: args.database.id,
+        propertyId: args.propertyId,
+        keyValueJson,
+        itemId: value.itemId,
+        documentId: value.documentId,
+        createdAt: args.now,
+        updatedAt: args.now,
+      })),
+    );
+  }
+  await tx
+    .update(schema.contentDatabases)
+    .set({ naturalKeyPropertyId: args.propertyId, updatedAt: args.now })
+    .where(eq(schema.contentDatabases.id, args.database.id));
+}

package/corpus/templates/content/actions/delete-document-property.ts

@@ -69,6 +69,14 @@ export default defineAction({
         tx as unknown as ReturnType<typeof getDb>,
         database.id,
       );
+      const [lockedDatabase] = await tx
+        .select({
+          naturalKeyPropertyId: schema.contentDatabases.naturalKeyPropertyId,
+        })
+        .from(schema.contentDatabases)
+        .where(eq(schema.contentDatabases.id, database.id));
+      if (!lockedDatabase)
+        throw new Error(`Database "${database.id}" not found`);
       const [lockedDefinition] = await tx
         .select()
         .from(schema.documentPropertyDefinitions)
@@ -131,6 +139,16 @@ export default defineAction({
         .delete(schema.documentPropertyDefinitions)
         .where(eq(schema.documentPropertyDefinitions.id, propertyId));
 
+      if (lockedDatabase.naturalKeyPropertyId === propertyId) {
+        await tx
+          .update(schema.contentDatabases)
+          .set({
+            naturalKeyPropertyId: null,
+            updatedAt: new Date().toISOString(),
+          })
+          .where(eq(schema.contentDatabases.id, database.id));
+      }
+
       if (isBlocks) {
         await deleteBlocksFieldIdentity({
           db: tx as unknown as ReturnType<typeof getDb>,