@agent-native/core 0.173.1 → 0.173.2-nightly-20260825161643

package/corpus/README.md

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

package/corpus/templates/content/actions/_database-property-input.ts

@@ -0,0 +1,211 @@
+import { ActionContractError } from "@agent-native/core";
+import { z } from "zod";
+
+const nullable = <T extends z.ZodTypeAny>(schema: T) =>
+  z.union([schema, z.null()]);
+
+const propertyIdSchema = z
+  .string()
+  .min(1)
+  .describe("Exact immutable property definition ID");
+
+const stringPropertyEntry = (
+  propertyType: "text" | "place" | "phone" | "url" | "email",
+  valueDescription: string,
+) =>
+  z
+    .object({
+      propertyId: propertyIdSchema,
+      propertyType: z.literal(propertyType),
+      value: nullable(z.string()).describe(valueDescription),
+    })
+    .strict();
+
+const optionPropertyEntry = (propertyType: "select" | "status") =>
+  z
+    .object({
+      propertyId: propertyIdSchema,
+      propertyType: z.literal(propertyType),
+      value: nullable(z.string()).describe(
+        "Exact option ID or exact option label from the discovered property contract; null explicitly clears the value",
+      ),
+    })
+    .strict();
+
+export const databasePropertyEntrySchema = z.discriminatedUnion(
+  "propertyType",
+  [
+    stringPropertyEntry("text", "Text value; null explicitly clears the value"),
+    stringPropertyEntry(
+      "place",
+      "Place text; null explicitly clears the value",
+    ),
+    stringPropertyEntry(
+      "phone",
+      "Phone text; null explicitly clears the value",
+    ),
+    stringPropertyEntry(
+      "url",
+      "Absolute http/https URL; null explicitly clears the value",
+    ),
+    stringPropertyEntry(
+      "email",
+      "Email address; null explicitly clears the value",
+    ),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("number"),
+        value: nullable(z.number().finite()).describe(
+          "Finite number; use a JSON number rather than numeric text, or null to explicitly clear",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("checkbox"),
+        value: nullable(z.boolean()).describe(
+          "Boolean; use true or false rather than text, or null to explicitly clear",
+        ),
+      })
+      .strict(),
+    optionPropertyEntry("select"),
+    optionPropertyEntry("status"),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("multi_select"),
+        value: nullable(z.array(z.string())).describe(
+          "Option IDs or exact option labels from the discovered property contract; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("date"),
+        value: nullable(
+          z.union([
+            z.string(),
+            z
+              .object({
+                start: z.string(),
+                end: z.string().optional(),
+                includeTime: z.boolean().optional(),
+              })
+              .strict(),
+          ]),
+        ).describe(
+          "ISO date/date-time string or { start, end?, includeTime? }; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("person"),
+        value: nullable(z.array(z.string())).describe(
+          "Person identifiers from the discovered property contract; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("files_media"),
+        value: nullable(z.array(z.string())).describe(
+          "Absolute http/https file URLs; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+  ],
+);
+
+export type DatabasePropertyEntry = z.infer<typeof databasePropertyEntrySchema>;
+
+export const databasePropertyValuesSchema = z
+  .record(z.string(), z.unknown())
+  .optional()
+  .describe(
+    "Programmatic property values keyed by exact property definition ID.",
+  );
+
+export const databasePropertyEntriesSchema = z
+  .array(databasePropertyEntrySchema)
+  .min(1)
+  .max(1_000)
+  .optional()
+  .describe(
+    "Typed property values as explicit entries. Copy each propertyType from the discovered mutation contract and include one entry for every writable property value the user requested, using the exact immutable property definition ID. When at least one value was requested, never pass an empty array. Do not invent or clear unmentioned properties.",
+  );
+
+export function normalizeDatabasePropertyInput(input: {
+  propertyEntries?: DatabasePropertyEntry[];
+  propertyValues?: Record<string, unknown>;
+}): {
+  propertyValues: Record<string, unknown> | undefined;
+  propertyTypeAssertions: Record<string, string> | undefined;
+} {
+  if (input.propertyEntries && input.propertyValues) {
+    throw new ActionContractError(
+      "Provide propertyEntries or propertyValues, not both.",
+      { errorCode: "AMBIGUOUS_PROPERTY_INPUT" },
+    );
+  }
+  if (!input.propertyEntries) {
+    return {
+      propertyValues: input.propertyValues,
+      propertyTypeAssertions: undefined,
+    };
+  }
+
+  const values: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
+  const propertyTypes: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  for (const entry of input.propertyEntries) {
+    if (Object.prototype.hasOwnProperty.call(values, entry.propertyId)) {
+      throw new ActionContractError(
+        `Property entry ${entry.propertyId} was provided more than once.`,
+        {
+          errorCode: "DUPLICATE_PROPERTY_INPUT",
+          details: { propertyId: entry.propertyId },
+        },
+      );
+    }
+    values[entry.propertyId] = entry.value;
+    propertyTypes[entry.propertyId] = entry.propertyType;
+  }
+  return {
+    propertyValues: values,
+    propertyTypeAssertions: propertyTypes,
+  };
+}
+
+export function canonicalizeDatabasePropertyInput<
+  T extends {
+    propertyEntries?: DatabasePropertyEntry[];
+    propertyValues?: Record<string, unknown>;
+  },
+>(
+  input: T,
+): Omit<T, "propertyEntries" | "propertyValues"> & {
+  propertyValues?: Record<string, unknown>;
+  propertyTypeAssertions?: Record<string, string>;
+} {
+  const { propertyEntries, propertyValues, ...canonicalInput } = input;
+  const normalized = normalizeDatabasePropertyInput({
+    propertyEntries,
+    propertyValues,
+  });
+  return {
+    ...canonicalInput,
+    propertyValues: normalized.propertyValues,
+    propertyTypeAssertions: normalized.propertyTypeAssertions,
+  };
+}

package/corpus/templates/content/actions/_database-row-mutation.ts

@@ -34,11 +34,13 @@ import {
 } from "./_position-utils.js";
 import { nanoid } from "./_property-utils.js";
 
+const databaseMutationAuthorityScopeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("personal"), id: z.string().min(1) }),
+  z.object({ kind: z.literal("organization"), id: z.string().min(1) }),
+]);
+
 export const databaseMutationTargetSchema = z.object({
-  authorityScope: z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("personal"), id: z.string().min(1) }),
-    z.object({ kind: z.literal("organization"), id: z.string().min(1) }),
-  ]),
+  authorityScope: databaseMutationAuthorityScopeSchema,
   spaceId: z.string().min(1).describe("Exact Content space ID"),
   databaseId: z.string().min(1).describe("Exact Content database ID"),
   databaseDocumentId: z
@@ -47,8 +49,35 @@ export const databaseMutationTargetSchema = z.object({
     .describe("Exact page ID backing the Content database"),
 });
 
+export const databaseMutationTargetInputSchema = z.object({
+  authorityScope: databaseMutationAuthorityScopeSchema
+    .optional()
+    .describe(
+      "Optional legacy assertion only. Agents must omit it; the authenticated server derives authority from the selected database.",
+    ),
+  spaceId: z
+    .string()
+    .min(1)
+    .describe("Exact Content space ID returned by database discovery"),
+  databaseId: z
+    .string()
+    .min(1)
+    .describe(
+      "Exact Content database ID returned by database discovery; never derive it from a title or number in the request",
+    ),
+  databaseDocumentId: z
+    .string()
+    .min(1)
+    .describe(
+      "Exact page ID backing the database, returned by database discovery",
+    ),
+});
+
+export const databaseMutationAgentTargetSchema =
+  databaseMutationTargetInputSchema.omit({ authorityScope: true });
+
 export const databaseMutationEnvelopeSchema = z.object({
-  target: databaseMutationTargetSchema,
+  target: databaseMutationTargetInputSchema,
   expectedSchemaRevision: z
     .string()
     .min(1)
@@ -59,6 +88,9 @@ export const databaseMutationEnvelopeSchema = z.object({
 export type DatabaseMutationTarget = z.infer<
   typeof databaseMutationTargetSchema
 >;
+export type DatabaseMutationTargetInput = z.infer<
+  typeof databaseMutationTargetInputSchema
+>;
 
 type DatabaseRow = typeof schema.contentDatabases.$inferSelect;
 type DefinitionRow = typeof schema.documentPropertyDefinitions.$inferSelect;
@@ -82,11 +114,12 @@ export interface RowSnapshot {
 export type DatabaseRowMutationOperation = "create" | "update" | "upsert";
 
 export interface CreateDatabaseRowMutationInput {
-  target: DatabaseMutationTarget;
+  target: DatabaseMutationTargetInput;
   expectedSchemaRevision: string;
   idempotencyKey: string;
   title?: string;
   propertyValues?: Record<string, unknown>;
+  propertyTypeAssertions?: Record<string, string>;
 }
 
 export interface UpdateDatabaseRowMutationInput extends CreateDatabaseRowMutationInput {
@@ -211,7 +244,7 @@ function acceptedShape(type: DocumentPropertyType): string {
 }
 
 export async function loadContext(
-  target: DatabaseMutationTarget,
+  target: DatabaseMutationTargetInput,
   role: "viewer" | "editor",
   db: Db = getDb(),
   accessAlreadyResolved = false,
@@ -260,8 +293,9 @@ export async function loadContext(
     ? { kind: "organization" as const, id: database.orgId }
     : { kind: "personal" as const, id: database.ownerEmail };
   if (
-    target.authorityScope.kind !== authorityScope.kind ||
-    target.authorityScope.id !== authorityScope.id ||
+    (target.authorityScope !== undefined &&
+      (target.authorityScope.kind !== authorityScope.kind ||
+        target.authorityScope.id !== authorityScope.id)) ||
     database.spaceId !== target.spaceId ||
     database.documentId !== target.databaseDocumentId ||
     databaseDocument.spaceId !== target.spaceId ||
@@ -322,7 +356,12 @@ export async function getDatabaseMutationContract(
   );
   return {
     target: {
-      ...target,
+      authorityScope: context.database.orgId
+        ? { kind: "organization", id: context.database.orgId }
+        : { kind: "personal", id: context.database.ownerEmail },
+      spaceId: context.database.spaceId!,
+      databaseId: context.database.id,
+      databaseDocumentId: context.database.documentId,
     },
     schemaRevision: context.schemaRevision,
     naturalKeyPropertyId: context.database.naturalKeyPropertyId,
@@ -695,14 +734,72 @@ export function revisionPropertyIds(context: MutationContext) {
   );
 }
 
-function payloadDigest(
+export function databaseMutationPayloadDigest(
   operation: DatabaseRowMutationOperation,
   input:
     | CreateDatabaseRowMutationInput
     | UpdateDatabaseRowMutationInput
     | UpsertDatabaseRowMutationInput,
 ) {
-  return digest({ operation, ...input });
+  const {
+    propertyTypeAssertions: _propertyTypeAssertions,
+    target,
+    ...canonicalInput
+  } = input;
+  const { authorityScope: _authorityScope, ...stableTarget } = target ?? {};
+  return digest({ operation, ...canonicalInput, target: stableTarget });
+}
+
+export function legacyDatabaseMutationPayloadDigest(
+  operation: DatabaseRowMutationOperation,
+  input:
+    | CreateDatabaseRowMutationInput
+    | UpdateDatabaseRowMutationInput
+    | UpsertDatabaseRowMutationInput,
+  authorityScope = input.target.authorityScope,
+) {
+  const { propertyTypeAssertions: _propertyTypeAssertions, ...legacyInput } =
+    input;
+  return digest({
+    operation,
+    ...legacyInput,
+    target: { ...legacyInput.target, authorityScope },
+  });
+}
+
+function authorityScopeForContext(context: MutationContext) {
+  return context.database.orgId
+    ? ({ kind: "organization", id: context.database.orgId } as const)
+    : ({ kind: "personal", id: context.database.ownerEmail } as const);
+}
+
+function assertPropertyTypeAssertions(
+  context: MutationContext,
+  assertions: Record<string, string> | undefined,
+) {
+  if (!assertions) return;
+  const definitionsById = new Map(
+    context.definitions.map((definition) => [definition.id, definition]),
+  );
+  for (const [propertyId, assertedType] of Object.entries(assertions)) {
+    const definition = definitionsById.get(propertyId);
+    if (!definition) {
+      throw new ActionContractError(
+        `Unknown property definition "${propertyId}".`,
+        {
+          errorCode: "UNKNOWN_PROPERTY",
+          details: { propertyId },
+          statusCode: 400,
+        },
+      );
+    }
+    if (definition.type !== assertedType) {
+      invalidProperty(
+        definition,
+        `typed entry declared propertyType "${assertedType}" but the discovered property type is "${definition.type}"`,
+      );
+    }
+  }
 }
 
 function resultForReceipt(
@@ -721,9 +818,7 @@ function resultForReceipt(
   },
 ): ContentDatabaseRowMutationResult {
   const target = {
-    authorityScope: context.database.orgId
-      ? ({ kind: "organization", id: context.database.orgId } as const)
-      : ({ kind: "personal", id: context.database.ownerEmail } as const),
+    authorityScope: authorityScopeForContext(context),
     spaceId: context.database.spaceId!,
     databaseId: context.database.id,
     databaseDocumentId: context.database.documentId,
@@ -770,7 +865,7 @@ function resultForReceipt(
 async function replayReceipt(
   context: MutationContext,
   idempotencyKey: string,
-  expectedPayloadDigest: string,
+  expectedPayloadDigests: readonly string[],
   db: Db = getDb(),
 ): Promise<ContentDatabaseRowMutationResult | null> {
   const [stored] = await db
@@ -789,7 +884,7 @@ async function replayReceipt(
       ),
     );
   if (!stored) return null;
-  if (stored.payloadDigest !== expectedPayloadDigest) {
+  if (!expectedPayloadDigests.includes(stored.payloadDigest)) {
     conflict(
       "IDEMPOTENCY_KEY_REUSED",
       "This idempotency key was already used for a different row mutation.",
@@ -1137,13 +1232,22 @@ export async function createDatabaseRow(
   input: CreateDatabaseRowMutationInput,
 ): Promise<ContentDatabaseRowMutationResult> {
   const initial = await loadContext(input.target, "editor");
-  const inputDigest = payloadDigest("create", input);
+  const inputDigest = databaseMutationPayloadDigest("create", input);
+  const replayDigests = [
+    inputDigest,
+    legacyDatabaseMutationPayloadDigest(
+      "create",
+      input,
+      authorityScopeForContext(initial),
+    ),
+  ];
   const replay = await replayReceipt(
     initial,
     input.idempotencyKey,
-    inputDigest,
+    replayDigests,
   );
   if (replay) return replay;
+  assertPropertyTypeAssertions(initial, input.propertyTypeAssertions);
   assertSchema(initial, input.expectedSchemaRevision);
   const values = await normalizePatch(initial, input.propertyValues);
   const result = await withMutationLocks(initial.database, () =>
@@ -1160,10 +1264,11 @@ export async function createDatabaseRow(
       const lockedReplay = await replayReceipt(
         locked,
         input.idempotencyKey,
-        inputDigest,
+        replayDigests,
         tx as unknown as Db,
       );
       if (lockedReplay) return lockedReplay;
+      assertPropertyTypeAssertions(locked, input.propertyTypeAssertions);
       assertSchema(locked, input.expectedSchemaRevision);
       await touchContentDatabase(
         tx as unknown as Db,
@@ -1206,13 +1311,22 @@ export async function updateDatabaseRow(
 ): Promise<ContentDatabaseRowMutationResult> {
   const initial = await loadContext(input.target, "editor");
   await assertAccess("document", input.documentId, "editor");
-  const inputDigest = payloadDigest("update", input);
+  const inputDigest = databaseMutationPayloadDigest("update", input);
+  const replayDigests = [
+    inputDigest,
+    legacyDatabaseMutationPayloadDigest(
+      "update",
+      input,
+      authorityScopeForContext(initial),
+    ),
+  ];
   const replay = await replayReceipt(
     initial,
     input.idempotencyKey,
-    inputDigest,
+    replayDigests,
   );
   if (replay) return replay;
+  assertPropertyTypeAssertions(initial, input.propertyTypeAssertions);
   assertSchema(initial, input.expectedSchemaRevision);
   const values = await normalizePatch(initial, input.propertyValues);
   const result = await withMutationLocks(initial.database, () =>
@@ -1229,10 +1343,11 @@ export async function updateDatabaseRow(
       const lockedReplay = await replayReceipt(
         locked,
         input.idempotencyKey,
-        inputDigest,
+        replayDigests,
         tx as unknown as Db,
       );
       if (lockedReplay) return lockedReplay;
+      assertPropertyTypeAssertions(locked, input.propertyTypeAssertions);
       assertSchema(locked, input.expectedSchemaRevision);
       const updated = await updateInsideTransaction(
         tx as unknown as Db,
@@ -1305,13 +1420,22 @@ export async function upsertDatabaseRow(
       "must match the upsert keyValue when provided in propertyValues",
     );
   }
-  const inputDigest = payloadDigest("upsert", input);
+  const inputDigest = databaseMutationPayloadDigest("upsert", input);
+  const replayDigests = [
+    inputDigest,
+    legacyDatabaseMutationPayloadDigest(
+      "upsert",
+      input,
+      authorityScopeForContext(initial),
+    ),
+  ];
   const replay = await replayReceipt(
     initial,
     input.idempotencyKey,
-    inputDigest,
+    replayDigests,
   );
   if (replay) return replay;
+  assertPropertyTypeAssertions(initial, input.propertyTypeAssertions);
   assertSchema(initial, input.expectedSchemaRevision);
   const keyPropertyId = initial.database.naturalKeyPropertyId;
   if (!keyPropertyId) {
@@ -1368,10 +1492,11 @@ export async function upsertDatabaseRow(
       const lockedReplay = await replayReceipt(
         locked,
         input.idempotencyKey,
-        inputDigest,
+        replayDigests,
         tx as unknown as Db,
       );
       if (lockedReplay) return lockedReplay;
+      assertPropertyTypeAssertions(locked, input.propertyTypeAssertions);
       assertSchema(locked, input.expectedSchemaRevision);
       if (locked.database.naturalKeyPropertyId !== keyPropertyId) {
         conflict("SCHEMA_REVISION_CONFLICT", "The natural key changed.");

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

@@ -3,8 +3,14 @@ import { buildDeepLink } from "@agent-native/core/server";
 import { z } from "zod";
 
 import type { ContentDatabaseRowMutationResult } from "../shared/api.js";
+import {
+  canonicalizeDatabasePropertyInput,
+  databasePropertyEntriesSchema,
+  databasePropertyValuesSchema,
+} from "./_database-property-input.js";
 import {
   createDatabaseRow,
+  databaseMutationAgentTargetSchema,
   databaseMutationEnvelopeSchema,
 } from "./_database-row-mutation.js";
 import { getContentDatabaseResponse } from "./_database-utils.js";
@@ -17,15 +23,17 @@ const schema = databaseMutationEnvelopeSchema.extend({
     .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"),
+  propertyValues: databasePropertyValuesSchema,
+  propertyEntries: databasePropertyEntriesSchema,
 });
+const agentSchema = schema
+  .extend({ target: databaseMutationAgentTargetSchema })
+  .omit({ propertyValues: true });
 
 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.",
+  agentInputSchema: agentSchema,
   publicAgent: {
     expose: true,
     readOnly: false,
@@ -52,7 +60,9 @@ export default defineAction({
     },
   },
   run: async (args): Promise<ContentDatabaseRowMutationResult> => {
-    const result = await createDatabaseRow(args);
+    const result = await createDatabaseRow(
+      canonicalizeDatabasePropertyInput(args),
+    );
     const response = await getContentDatabaseResponse(
       result.receipt.target.databaseId,
       {

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

@@ -4,6 +4,12 @@ import { z } from "zod";
 
 import type { ContentDatabaseRowMutationResult } from "../shared/api.js";
 import {
+  canonicalizeDatabasePropertyInput,
+  databasePropertyEntriesSchema,
+  databasePropertyValuesSchema,
+} from "./_database-property-input.js";
+import {
+  databaseMutationAgentTargetSchema,
   databaseMutationEnvelopeSchema,
   updateDatabaseRow,
 } from "./_database-row-mutation.js";
@@ -16,17 +22,19 @@ const schema = databaseMutationEnvelopeSchema.extend({
     .min(1)
     .describe("Row revision returned by get-content-database"),
   title: z.string().trim().min(1).max(500).optional(),
-  propertyValues: z
-    .record(z.string(), z.unknown())
-    .optional()
-    .describe(
-      "Sparse strict patch keyed by property definition ID; omitted fields are preserved and explicit null clears a value",
-    ),
+  propertyValues: databasePropertyValuesSchema,
+  propertyEntries: databasePropertyEntriesSchema.describe(
+    "Sparse typed property patch as explicit entries; omitted fields are preserved and explicit null clears a value. Copy each propertyType from the discovered mutation contract and include one entry for every writable property value the user requested, using the exact immutable property definition ID. When at least one value was requested, never pass an empty array. Do not invent or clear unmentioned properties.",
+  ),
 });
+const agentSchema = schema
+  .extend({ target: databaseMutationAgentTargetSchema })
+  .omit({ propertyValues: true });
 
 export default defineAction({
   description:
     "Sparsely update one exact Content database row by stable item and document IDs. Requires schema and row revisions, validates every non-Blocks property, and returns a verified idempotent receipt.",
+  agentInputSchema: agentSchema,
   schema,
   http: { method: "PUT" },
   audit: {
@@ -44,7 +52,7 @@ export default defineAction({
         : "Updated Content database row";
     },
   },
-  run: updateDatabaseRow,
+  run: (args) => updateDatabaseRow(canonicalizeDatabasePropertyInput(args)),
   link: ({ result }) => {
     const documentId = (result as ContentDatabaseRowMutationResult | null)
       ?.receipt.row.documentId;

package/corpus/templates/content/actions/upsert-database-item-by-key.ts

@@ -4,6 +4,12 @@ import { z } from "zod";
 
 import type { ContentDatabaseRowMutationResult } from "../shared/api.js";
 import {
+  canonicalizeDatabasePropertyInput,
+  databasePropertyEntriesSchema,
+  databasePropertyValuesSchema,
+} from "./_database-property-input.js";
+import {
+  databaseMutationAgentTargetSchema,
   databaseMutationEnvelopeSchema,
   upsertDatabaseRow,
 } from "./_database-row-mutation.js";
@@ -18,15 +24,19 @@ const schema = databaseMutationEnvelopeSchema.extend({
       "Use null to assert the key is absent and create; use the discovered row revision to update an existing key",
     ),
   title: z.string().trim().min(1).max(500).optional(),
-  propertyValues: z
-    .record(z.string(), z.unknown())
-    .optional()
-    .describe("Sparse strict values keyed by property definition ID"),
+  propertyValues: databasePropertyValuesSchema,
+  propertyEntries: databasePropertyEntriesSchema.describe(
+    "Sparse typed property values as explicit entries. Copy each propertyType from the discovered mutation contract and include one entry for every writable property value the user requested, using the exact immutable property definition ID. When at least one value was requested, never pass an empty array. Do not invent or clear unmentioned properties.",
+  ),
 });
+const agentSchema = schema
+  .extend({ target: databaseMutationAgentTargetSchema })
+  .omit({ propertyValues: true });
 
 export default defineAction({
   description:
     "Create or sparsely update one Content database row by that database's explicitly configured natural key. Requires schema and row compare-and-swap revisions and returns a verified idempotent receipt.",
+  agentInputSchema: agentSchema,
   schema,
   audit: {
     recordInputs: false,
@@ -43,7 +53,7 @@ export default defineAction({
         : "Upserted Content database row by natural key";
     },
   },
-  run: upsertDatabaseRow,
+  run: (args) => upsertDatabaseRow(canonicalizeDatabasePropertyInput(args)),
   link: ({ result }) => {
     const documentId = (result as ContentDatabaseRowMutationResult | null)
       ?.receipt.row.documentId;

package/corpus/templates/content/package.json

@@ -12,6 +12,7 @@
     "test:parity": "vitest --run parity",
     "test:parity-capabilities": "vitest --run parity actions/content-database-lifecycle.db.test.ts actions/bind-content-database-source-field.db.test.ts actions/_local-file-documents.test.ts actions/builder-source-review-gates.db.test.ts",
     "eval:parity": "agent-native eval parity",
+    "eval:property-preservation": "tsx parity/run-database-create-property-preservation.ts",
     "format.fix": "oxfmt --write .",
     "typecheck": "agent-native typecheck",
     "migrate:production": "tsx scripts/migrate-production.ts",