@agent-native/core 0.154.3 → 0.154.5

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

@@ -16,6 +16,7 @@ import {
   normalizePropertyVisibility,
   type DocumentPropertyType,
 } from "../shared/properties.js";
+import { deleteBlocksFieldIdentity } from "./_blocks-field-identity.js";
 import { lockContentDatabaseMutation } from "./_content-database-mutation-lock.js";
 import { lockDatabaseMemberships } from "./_database-membership-lock.js";
 import {
@@ -51,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()
@@ -103,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,
@@ -114,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
@@ -135,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)
@@ -150,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.");
         }
@@ -233,6 +262,10 @@ export default defineAction({
             ) &&
             !isBlocksPropertyType(type)
           ) {
+            await deleteBlocksFieldIdentity({
+              db: tx as unknown as ReturnType<typeof getDb>,
+              propertyId: args.id!,
+            });
             await tx
               .delete(schema.documentBlockFieldContents)
               .where(
@@ -260,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(
@@ -270,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)`,
@@ -289,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,
@@ -302,6 +347,13 @@ export default defineAction({
               createdAt: now,
               updatedAt: now,
             });
+            await configureNaturalKey(tx, {
+              database: lockedDatabase,
+              propertyId,
+              naturalKey: args.naturalKey,
+              ownerEmail: document.ownerEmail,
+              now,
+            });
           });
         },
       );
@@ -316,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

@@ -11,6 +11,10 @@ import {
   parsePropertyOptions,
   type DocumentPropertyType,
 } from "../shared/properties.js";
+import {
+  deleteBlocksFieldIdentity,
+  lockPrimaryBlocksFieldsForDocuments,
+} from "./_blocks-field-identity.js";
 import { lockContentDatabaseMutation } from "./_content-database-mutation-lock.js";
 import { lockDatabaseMemberships } from "./_database-membership-lock.js";
 import {
@@ -65,14 +69,14 @@ export default defineAction({
         tx as unknown as ReturnType<typeof getDb>,
         database.id,
       );
-      const memberships = await tx
-        .select({ id: schema.contentDatabaseItems.id })
-        .from(schema.contentDatabaseItems)
-        .where(eq(schema.contentDatabaseItems.databaseId, database.id));
-      await lockDatabaseMemberships(
-        tx,
-        memberships.map((membership) => membership.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)
@@ -100,6 +104,25 @@ export default defineAction({
         isPrimaryBlocksField(
           parsePropertyOptions(lockedDefinition.optionsJson),
         );
+      const items = await tx
+        .select({
+          id: schema.contentDatabaseItems.id,
+          documentId: schema.contentDatabaseItems.documentId,
+        })
+        .from(schema.contentDatabaseItems)
+        .where(eq(schema.contentDatabaseItems.databaseId, database.id));
+      const primaryFieldsByDocument = isPrimaryBlocks
+        ? await lockPrimaryBlocksFieldsForDocuments(
+            tx as unknown as ReturnType<typeof getDb>,
+            items.map((item) => item.documentId),
+          )
+        : new Map();
+      if (!isPrimaryBlocks) {
+        await lockDatabaseMemberships(
+          tx,
+          items.map((item) => item.id),
+        );
+      }
 
       await tx
         .delete(schema.documentPropertyValues)
@@ -116,7 +139,21 @@ 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>,
+          propertyId,
+        });
         await tx
           .delete(schema.documentBlockFieldContents)
           .where(eq(schema.documentBlockFieldContents.propertyId, propertyId));
@@ -130,20 +167,22 @@ export default defineAction({
             })
             .where(eq(schema.contentDatabases.id, database.id));
 
-          const items = await tx
-            .select({ documentId: schema.contentDatabaseItems.documentId })
-            .from(schema.contentDatabaseItems)
-            .where(eq(schema.contentDatabaseItems.databaseId, database.id));
-          if (items.length > 0) {
+          const documentsWithoutSurvivingPrimary = items
+            .filter(
+              (item) =>
+                !(primaryFieldsByDocument.get(item.documentId) ?? []).some(
+                  (field: { propertyId: string }) =>
+                    field.propertyId !== propertyId,
+                ),
+            )
+            .map((item) => item.documentId);
+          if (documentsWithoutSurvivingPrimary.length > 0) {
             const now = new Date().toISOString();
             await tx
               .update(schema.documents)
               .set({ content: "", updatedAt: now })
               .where(
-                inArray(
-                  schema.documents.id,
-                  items.map((item) => item.documentId),
-                ),
+                inArray(schema.documents.id, documentsWithoutSurvivingPrimary),
               );
           }
         }

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

@@ -6,6 +6,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { chunks } from "./_batch-utils.js";
+import { deleteBlocksFieldIdentity } from "./_blocks-field-identity.js";
 import {
   lockContentDatabaseMutation,
   touchContentDatabase,
@@ -695,6 +696,7 @@ async function deleteCollectedDocuments(
   });
 
   await deleteWhereIn(propertyDefinitionIds, async (propertyIdBatch) => {
+    await deleteBlocksFieldIdentity({ db, propertyIds: propertyIdBatch });
     await db
       .delete(schema.documentPropertyValues)
       .where(
@@ -730,6 +732,7 @@ async function deleteCollectedDocuments(
   });
 
   await deleteWhereIn(documentIds, async (documentIdBatch) => {
+    await deleteBlocksFieldIdentity({ db, documentIds: documentIdBatch });
     await db
       .delete(schema.contentDatabaseBodyHydrationQueue)
       .where(

package/corpus/templates/content/actions/edit-document.ts

@@ -17,6 +17,10 @@ import { eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import {
+  lockPrimaryBlocksFields,
+  persistBlocksFieldIdentity,
+} from "./_blocks-field-identity.js";
 
 interface TextEdit {
   find: string;
@@ -235,11 +239,24 @@ export default defineAction({
     // Persist. The fresh updatedAt is the signal the open editor uses to tell an
     // intentional external edit apart from a stale autosave echo.
     const db = getDb();
+    const now = new Date().toISOString();
     await db.transaction(async (tx: any) => {
+      const primaryBlocksFields = await lockPrimaryBlocksFields(tx, id);
       await tx
         .update(schema.documents)
-        .set({ content, updatedAt: new Date().toISOString() })
+        .set({ content, updatedAt: now })
         .where(eq(schema.documents.id, id));
+      for (const field of primaryBlocksFields) {
+        await persistBlocksFieldIdentity({
+          db: tx as unknown as ReturnType<typeof getDb>,
+          ownerEmail: field.ownerEmail,
+          documentId: id,
+          propertyId: field.propertyId,
+          previousMarkdown: existing.content ?? "",
+          markdown: content,
+          now,
+        });
+      }
       if (creativeContext) {
         await recordGenerationCreativeContext(
           {

package/corpus/templates/content/actions/export-document.ts

@@ -3,8 +3,14 @@ import { buildDeepLink } from "@agent-native/core/server";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
+import { blocksContentHash } from "../shared/blocks-field-identity.js";
 import { buildDocumentExport } from "../shared/document-export.js";
+import {
+  isBlocksPropertyType,
+  isPrimaryBlocksField,
+} from "../shared/properties.js";
 import "../server/db/index.js";
+import { listPropertiesForAllDocumentDatabases } from "./_property-utils.js";
 
 export default defineAction({
   description:
@@ -33,12 +39,47 @@ export default defineAction({
     if (!access) throw new Error(`Document "${id}" not found`);
 
     const doc = access.resource;
+    const properties = await listPropertiesForAllDocumentDatabases(doc);
+    const blocksFields = properties
+      .filter((property) => isBlocksPropertyType(property.definition.type))
+      .map((property) => {
+        if (!property.definition.databaseId) {
+          throw new Error(
+            `Blocks field "${property.definition.id}" is not attached to a database`,
+          );
+        }
+        if (!property.blocksField) {
+          throw new Error(
+            `Blocks field "${property.definition.id}" has no identity state`,
+          );
+        }
+        const markdown =
+          content !== undefined &&
+          isPrimaryBlocksField(property.definition.options)
+            ? content
+            : typeof property.value === "string"
+              ? property.value
+              : "";
+        const identity =
+          blocksContentHash(markdown) === property.blocksField.contentHash
+            ? property.blocksField
+            : { ...property.blocksField, identityStatus: "stale" as const };
+        return {
+          databaseId: property.definition.databaseId,
+          propertyId: property.definition.id,
+          name: property.definition.name,
+          position: property.definition.position,
+          markdown,
+          identity,
+        };
+      });
     const payload = buildDocumentExport({
       id: doc.id,
       title: title ?? doc.title,
       content: content ?? doc.content,
       updatedAt: doc.updatedAt,
       format,
+      blocksFields,
     });
 
     return {

package/corpus/templates/content/actions/remove-database-items.ts

@@ -4,6 +4,7 @@ import { assertAccess } from "@agent-native/core/sharing";
 import { and, eq, inArray } from "drizzle-orm";
 
 import { getDb, schema } from "../server/db/index.js";
+import { deleteBlocksFieldIdentity } from "./_blocks-field-identity.js";
 import {
   lockContentDatabaseMutation,
   touchContentDatabase,
@@ -132,6 +133,15 @@ export default defineAction({
             )
         ).map((property) => property.id);
         if (removedDocumentIds.length > 0 && propertyIds.length > 0) {
+          for (const removedDocumentId of removedDocumentIds) {
+            for (const propertyId of propertyIds) {
+              await deleteBlocksFieldIdentity({
+                db: tx as unknown as ReturnType<typeof getDb>,
+                documentId: removedDocumentId,
+                propertyId,
+              });
+            }
+          }
           await tx
             .delete(schema.documentPropertyValues)
             .where(