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

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",

package/corpus/templates/content/parity/README.md

@@ -10,7 +10,7 @@ PR 2.2 adds two executable tiers:
   existing action tests, make no model calls, and require no private provider
   credentials.
 - Gated agent evals run through `agent-native eval parity`. They are opt-in via
-  `CONTENT_PARITY_EVALS=1`, capped to four initial scenarios, and should be
+  `CONTENT_PARITY_EVALS=1`, kept to a small explicit scenario set, and should be
   reserved for manual or nightly checks.
 
 ## Deterministic Checks
@@ -33,14 +33,23 @@ cd templates/content
 CONTENT_PARITY_EVALS=1 ANTHROPIC_API_KEY=... ./node_modules/.bin/agent-native eval parity
 ```
 
+The database-create property-preservation regression has a dedicated
+fixture-only runner so it can inspect model-produced arguments without loading
+or executing unrelated Content actions:
+
+```bash
+CONTENT_PARITY_EVALS=1 pnpm eval:property-preservation
+```
+
 With `CONTENT_PARITY_EVALS` unset, parity evals return skipped rows and do not
 call the agent runner. The CLI still exits `0`, but both readable and JSON
 reports mark each row with `status: "skipped"` and a `skipReason` such as
 `Skipped because CONTENT_PARITY_EVALS is unset`.
 
-With the gate set, the eval files run the four PR 2.2 scenarios:
+With the gate set, the eval files include these scenarios:
 
 - `database-source-scope`
+- `database-create-property-preservation`
 - `document-search-edit`
 - `local-file-source-truth`
 - `builder-source-review-readonly`

package/corpus/templates/content/parity/eval-scenarios.ts

@@ -8,9 +8,61 @@ export interface ParityEvalScenario {
   prompt: string;
   successSignals: string[];
   expectedTools?: string[];
+  expectedPropertyValues?: Record<string, unknown>;
+  expectedPropertyTypes?: Record<string, string>;
+  expectedCreateEnvelope?: {
+    target: {
+      spaceId: string;
+      databaseId: string;
+      databaseDocumentId: string;
+    };
+    expectedSchemaRevision: string;
+    idempotencyKey: string;
+    title: string;
+  };
 }
 
 export const parityEvalScenarios: ParityEvalScenario[] = [
+  {
+    id: "database-create-property-preservation",
+    title: "Database create property preservation",
+    capabilityIds: ["database.rows"],
+    gateEnv: "CONTENT_PARITY_EVALS",
+    defaultState: "skipped",
+    requiresPrivateCredentials: false,
+    prompt:
+      "Find the fixture Content database titled PR #3314 feedback — do not treat 3314 as its database ID. Discover its exact database target and mutation contract through Content actions, then create exactly one row titled [FIXTURE] preserve explicit properties with idempotency key fixture-create-property-preservation-v1. Set Status to status-cannot-verify and Evidence to Baseline fixture preserve-me using the discovered immutable property IDs and property types. Omit authority identity because the authenticated server owns it. No Blocks value was requested. Call add-database-item once, then report its result truthfully.",
+    successSignals: [
+      "Discovers the exact database and mutation contract before creating.",
+      "Uses add-database-item once for the discovered stable target without authoring authority identity.",
+      "Preserves both explicitly requested writable property values.",
+      "Does not invent a Blocks value or another property.",
+      "Reports an action failure rather than claiming a row was created if the fixture is unavailable.",
+    ],
+    expectedTools: [
+      "list-content-databases",
+      "get-content-database",
+      "add-database-item",
+    ],
+    expectedPropertyValues: {
+      fixture_status_property: "status-cannot-verify",
+      fixture_evidence_property: "Baseline fixture preserve-me",
+    },
+    expectedPropertyTypes: {
+      fixture_status_property: "status",
+      fixture_evidence_property: "text",
+    },
+    expectedCreateEnvelope: {
+      target: {
+        spaceId: "fixture_personal_space",
+        databaseId: "fixture_feedback_database",
+        databaseDocumentId: "fixture_feedback_document",
+      },
+      expectedSchemaRevision: "fixture_schema_revision",
+      idempotencyKey: "fixture-create-property-preservation-v1",
+      title: "[FIXTURE] preserve explicit properties",
+    },
+  },
   {
     id: "database-bulk-row-reliability",
     title: "Bulk database row reliability",