@agent-native/core 0.123.0 → 0.123.2

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

@@ -162,6 +162,9 @@ type SourceMetadataRecord = {
   lastReadSuspiciousEmpty?: boolean;
   activeReadSourceRowIds?: string[];
   sourceFetchState?: "idle" | "fetching" | "error" | string;
+  builderContinuationClaimId?: string;
+  builderContinuationClaimOffset?: number;
+  builderContinuationClaimedAt?: string;
   allowDraftWrites?: boolean;
   allowPublishWrites?: boolean;
   allowedWriteModes?: ContentDatabaseSourcePushMode[];
@@ -183,6 +186,229 @@ function parseObject<T extends object>(
   }
 }
 
+type ContentDatabaseSourceMetadataMutationRow = Pick<
+  ContentDatabaseSourceRowDb,
+  | "capabilitiesJson"
+  | "metadataJson"
+  | "sourceTable"
+  | "sourceType"
+  | "lastSourceUpdatedAt"
+>;
+
+type ContentDatabaseSourceMetadataMutationPatch = Pick<
+  ContentDatabaseSourceRowDb,
+  "metadataJson"
+> &
+  Partial<
+    Pick<
+      ContentDatabaseSourceRowDb,
+      | "capabilitiesJson"
+      | "syncState"
+      | "freshness"
+      | "lastRefreshedAt"
+      | "lastSourceUpdatedAt"
+      | "lastError"
+    >
+  >;
+
+/**
+ * Merge source metadata against the latest persisted row and compare-and-swap
+ * both JSON envelopes. Refresh ownership lives in metadataJson, so every
+ * unrelated writer must retry from the winning value instead of restoring a
+ * stale claim snapshot.
+ */
+export async function mutateContentDatabaseSourceMetadata(args: {
+  sourceId: string;
+  now: string;
+  buildPatch: (
+    current: ContentDatabaseSourceMetadataMutationRow,
+  ) =>
+    | ContentDatabaseSourceMetadataMutationPatch
+    | Promise<ContentDatabaseSourceMetadataMutationPatch>;
+  failureMessage?: string;
+}) {
+  const db = getDb();
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const [current] = await db
+      .select({
+        capabilitiesJson: schema.contentDatabaseSources.capabilitiesJson,
+        metadataJson: schema.contentDatabaseSources.metadataJson,
+        sourceTable: schema.contentDatabaseSources.sourceTable,
+        sourceType: schema.contentDatabaseSources.sourceType,
+        lastSourceUpdatedAt: schema.contentDatabaseSources.lastSourceUpdatedAt,
+      })
+      .from(schema.contentDatabaseSources)
+      .where(eq(schema.contentDatabaseSources.id, args.sourceId))
+      .limit(1);
+    if (!current) throw new Error("Content database source not found.");
+
+    const patch = await args.buildPatch(current);
+    const updated = await db
+      .update(schema.contentDatabaseSources)
+      .set({ ...patch, updatedAt: args.now })
+      .where(
+        and(
+          eq(schema.contentDatabaseSources.id, args.sourceId),
+          eq(
+            schema.contentDatabaseSources.capabilitiesJson,
+            current.capabilitiesJson,
+          ),
+          current.metadataJson === null
+            ? isNull(schema.contentDatabaseSources.metadataJson)
+            : eq(
+                schema.contentDatabaseSources.metadataJson,
+                current.metadataJson,
+              ),
+        ),
+      )
+      .returning({ id: schema.contentDatabaseSources.id });
+    if (updated.length > 0) return;
+  }
+  throw new Error(
+    args.failureMessage ??
+      "Content database source metadata changed repeatedly; retry the action.",
+  );
+}
+
+export function builderCmsSourceContinuationIsCurrent(
+  metadataJson: string | null | undefined,
+  expectedOffset: number,
+) {
+  const metadata = parseObject<SourceMetadataRecord>(metadataJson);
+  return (
+    metadata?.sourceFetchState === "fetching" &&
+    metadata.lastReadHasMore === true &&
+    expectedOffset > 0 &&
+    metadata.lastReadNextOffset === expectedOffset &&
+    Array.isArray(metadata.activeReadSourceRowIds) &&
+    metadata.activeReadSourceRowIds.length > 0 &&
+    metadata.activeReadSourceRowIds.every((id) => typeof id === "string")
+  );
+}
+
+// Content's hosted request wall is 75 seconds. Keep the orphan-recovery lease
+// well beyond that so an expired owner cannot still be executing mutations.
+export const BUILDER_CMS_REFRESH_CLAIM_LEASE_MS = 30 * 60 * 1000;
+
+export async function claimBuilderCmsSourceRefresh(args: {
+  source: ContentDatabaseSourceRowDb;
+  expectedOffset?: number;
+  now?: string;
+}) {
+  const metadata =
+    parseObject<SourceMetadataRecord>(args.source.metadataJson) ?? {};
+  const now = args.now ?? new Date().toISOString();
+  const claimedAt = metadata.builderContinuationClaimedAt
+    ? Date.parse(metadata.builderContinuationClaimedAt)
+    : Number.NaN;
+  const activeClaim =
+    !!metadata.builderContinuationClaimId &&
+    Number.isFinite(claimedAt) &&
+    Date.parse(now) - claimedAt < BUILDER_CMS_REFRESH_CLAIM_LEASE_MS;
+  if (
+    activeClaim ||
+    (args.expectedOffset !== undefined &&
+      !builderCmsSourceContinuationIsCurrent(
+        args.source.metadataJson,
+        args.expectedOffset,
+      ))
+  ) {
+    return null;
+  }
+
+  const claimId = nanoid();
+  const claimedMetadataJson = JSON.stringify({
+    ...metadata,
+    builderContinuationClaimId: claimId,
+    builderContinuationClaimOffset: args.expectedOffset,
+    builderContinuationClaimedAt: now,
+  });
+  const [claimed] = await getDb()
+    .update(schema.contentDatabaseSources)
+    .set({ metadataJson: claimedMetadataJson })
+    .where(
+      and(
+        eq(schema.contentDatabaseSources.id, args.source.id),
+        args.source.metadataJson === null
+          ? isNull(schema.contentDatabaseSources.metadataJson)
+          : eq(
+              schema.contentDatabaseSources.metadataJson,
+              args.source.metadataJson,
+            ),
+      ),
+    )
+    .returning();
+  return claimed ? { source: claimed, claimId } : null;
+}
+
+export async function releaseBuilderCmsSourceRefreshClaim(args: {
+  sourceId: string;
+  claimId: string;
+}) {
+  const db = getDb();
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const [current] = await db
+      .select({ metadataJson: schema.contentDatabaseSources.metadataJson })
+      .from(schema.contentDatabaseSources)
+      .where(eq(schema.contentDatabaseSources.id, args.sourceId))
+      .limit(1);
+    const metadata = parseObject<SourceMetadataRecord>(current?.metadataJson);
+    if (!metadata || metadata.builderContinuationClaimId !== args.claimId) {
+      return false;
+    }
+    delete metadata.builderContinuationClaimId;
+    delete metadata.builderContinuationClaimOffset;
+    delete metadata.builderContinuationClaimedAt;
+    const nextMetadataJson = JSON.stringify(metadata);
+    const released = await db
+      .update(schema.contentDatabaseSources)
+      .set({ metadataJson: nextMetadataJson })
+      .where(
+        and(
+          eq(schema.contentDatabaseSources.id, args.sourceId),
+          eq(schema.contentDatabaseSources.metadataJson, current.metadataJson!),
+        ),
+      )
+      .returning({ id: schema.contentDatabaseSources.id });
+    if (released.length > 0) return true;
+  }
+  return false;
+}
+
+export async function renewBuilderCmsSourceRefreshClaim(args: {
+  sourceId: string;
+  claimId: string;
+  now?: string;
+}) {
+  const db = getDb();
+  const now = args.now ?? new Date().toISOString();
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const [current] = await db
+      .select({ metadataJson: schema.contentDatabaseSources.metadataJson })
+      .from(schema.contentDatabaseSources)
+      .where(eq(schema.contentDatabaseSources.id, args.sourceId))
+      .limit(1);
+    const metadata = parseObject<SourceMetadataRecord>(current?.metadataJson);
+    if (!metadata || metadata.builderContinuationClaimId !== args.claimId) {
+      return false;
+    }
+    metadata.builderContinuationClaimedAt = now;
+    const nextMetadataJson = JSON.stringify(metadata);
+    const renewed = await db
+      .update(schema.contentDatabaseSources)
+      .set({ metadataJson: nextMetadataJson })
+      .where(
+        and(
+          eq(schema.contentDatabaseSources.id, args.sourceId),
+          eq(schema.contentDatabaseSources.metadataJson, current.metadataJson!),
+        ),
+      )
+      .returning({ id: schema.contentDatabaseSources.id });
+    if (renewed.length > 0) return true;
+  }
+  return false;
+}
+
 function parseArray<T>(value: string | null | undefined): T[] {
   if (!value) return [];
   try {
@@ -646,6 +872,26 @@ function stableValueString(value: unknown): string {
   return JSON.stringify(value);
 }
 
+export function reviewedBuilderChangeSetRevisionId(
+  changeSet: ContentDatabaseSourceChangeSet,
+) {
+  const revision = createHash("sha256")
+    .update(
+      stableValueString({
+        databaseItemId: changeSet.databaseItemId,
+        documentId: changeSet.documentId,
+        kind: changeSet.kind,
+        direction: "outbound",
+        pushMode: changeSet.pushMode ?? "autosave",
+        fieldChanges: changeSet.fieldChanges,
+        bodyChange: changeSet.bodyChange,
+      }),
+    )
+    .digest("hex")
+    .slice(0, 16);
+  return `${changeSet.id}-revision-${revision}`;
+}
+
 // Equal when both normalize the same. null/undefined/"" are all "empty"; strings
 // are trimmed; objects compared by stable serialization.
 function sameSourceFieldValue(a: unknown, b: unknown): boolean {
@@ -701,6 +947,15 @@ function normalizeBuilderBodyBaselineContent(value: string | null | undefined) {
   return (value ?? "").replace(/\r\n/g, "\n").trim();
 }
 
+function builderBodyUsesCurrentMediaConverter(
+  content: string | null | undefined,
+) {
+  return (
+    /!\[[^\]]*\]\(\s*https?:\/\//i.test(content ?? "") ||
+    /<(?:img|video)\b/i.test(content ?? "")
+  );
+}
+
 const BUILDER_BODY_HYDRATION_BACKGROUND_PRIORITY = 10;
 const BUILDER_BODY_HYDRATION_OPEN_PRIORITY = 0;
 const BUILDER_BODY_HYDRATION_BATCH_LIMIT = 25;
@@ -2355,8 +2610,7 @@ export async function builderBodyChangeForLocalContent(args: {
   // legacy Text block containing a Markdown image into a real Builder Image
   // (or emit a native Video) without changing the document text at all.
   const usesCurrentMediaConverter =
-    /!\[[^\]]*\]\(\s*https?:\/\//i.test(localContent) ||
-    /<(?:img|video)\b/i.test(localContent);
+    builderBodyUsesCurrentMediaConverter(localContent);
   const normalizedLocalContent =
     normalizeBuilderBodyBaselineContent(localContent);
   if (
@@ -2624,6 +2878,16 @@ export function buildBuilderLocalOutboundChangeSets(args: {
           stableValueString(candidate.bodyChange),
     );
 
+  const withUniqueReviewIdentity = (
+    candidate: ContentDatabaseSourceChangeSet,
+  ): ContentDatabaseSourceChangeSet =>
+    args.storedChangeSets.some((stored) => stored.id === candidate.id)
+      ? {
+          ...candidate,
+          id: reviewedBuilderChangeSetRevisionId(candidate),
+        }
+      : candidate;
+
   const reviewableBuilderValue = (
     field: NonNullable<typeof args.writableFields>[number],
     localValue: unknown,
@@ -2842,7 +3106,9 @@ export function buildBuilderLocalOutboundChangeSets(args: {
       createdAt: now,
       updatedAt: now,
     };
-    if (!sameCancelledSnapshot(candidate)) pending.push(candidate);
+    if (!sameCancelledSnapshot(candidate)) {
+      pending.push(withUniqueReviewIdentity(candidate));
+    }
   }
 
   // New-row creates: a local database item NOT linked to a Builder entry (no
@@ -2934,7 +3200,9 @@ export function buildBuilderLocalOutboundChangeSets(args: {
         createdAt: now,
         updatedAt: now,
       };
-      if (!sameCancelledSnapshot(candidate)) pending.push(candidate);
+      if (!sameCancelledSnapshot(candidate)) {
+        pending.push(withUniqueReviewIdentity(candidate));
+      }
     }
   }
 
@@ -3064,6 +3332,181 @@ export async function getContentDatabaseSourceSnapshotForWrite(
     : null;
 }
 
+export function knownBuilderReviewDocumentIds(
+  changeSets: Array<{ documentId: string | null }>,
+  limit: number,
+): string[] | null {
+  if (changeSets.length === 0 || changeSets.length > limit) return null;
+  const documentIds = new Set<string>();
+  for (const changeSet of changeSets) {
+    if (!changeSet.documentId) return null;
+    documentIds.add(changeSet.documentId);
+  }
+  return [...documentIds];
+}
+
+type BuilderReviewSourceValueTextKey =
+  | typeof BUILDER_CMS_BODY_BLOCKS_HASH_KEY
+  | typeof BUILDER_CMS_BODY_CONTENT_KEY;
+
+export function builderReviewSourceValueTextProjection(
+  key: BuilderReviewSourceValueTextKey,
+) {
+  const sourceValuesJson = schema.contentDatabaseSourceRows.sourceValuesJson;
+  return getDialect() === "postgres"
+    ? sql<string>`COALESCE(${sourceValuesJson}::jsonb ->> ${key}, '')`
+    : sql<string>`COALESCE(json_extract(${sourceValuesJson}, ${`$."${key}"`}), '')`;
+}
+
+async function findBuilderReviewBodyCandidateDocumentIds(args: {
+  database: ContentDatabaseRow | ContentDatabase;
+  source: ContentDatabaseSourceRowDb;
+}) {
+  const sourceRows = schema.contentDatabaseSourceRows;
+  const items = schema.contentDatabaseItems;
+  const documents = schema.documents;
+  const currentContent = builderReviewSourceValueTextProjection(
+    BUILDER_CMS_BODY_CONTENT_KEY,
+  );
+  const localContentIsNonEmpty = sql<boolean>`TRIM(${documents.content}) <> ''`;
+  const localContentDiffers = sql<boolean>`TRIM(${documents.content}) <> TRIM(${currentContent})`;
+  const usesCurrentMediaConverter = sql<boolean>`(
+    LOWER(${documents.content}) LIKE '%![%](http://%'
+    OR LOWER(${documents.content}) LIKE '%![%](https://%'
+    OR LOWER(${documents.content}) LIKE '%<img%'
+    OR LOWER(${documents.content}) LIKE '%<video%'
+  )`;
+  const isSyntheticFixture = and(
+    sql<boolean>`${sourceRows.sourceRowId} = 'builder-' || ${sourceRows.documentId}`,
+    or(
+      isNull(sourceRows.provenance),
+      eq(sourceRows.provenance, BUILDER_CMS_FIXTURE_ROW_PROVENANCE),
+    ),
+  );
+  const rows = await getDb()
+    .select({
+      documentId: sourceRows.documentId,
+    })
+    .from(sourceRows)
+    .innerJoin(
+      items,
+      and(
+        eq(items.databaseId, args.database.id),
+        eq(items.documentId, sourceRows.documentId),
+        eq(items.ownerEmail, args.source.ownerEmail),
+      ),
+    )
+    .innerJoin(
+      documents,
+      and(
+        eq(documents.id, sourceRows.documentId),
+        eq(documents.ownerEmail, args.source.ownerEmail),
+      ),
+    )
+    .where(
+      and(
+        eq(sourceRows.sourceId, args.source.id),
+        or(
+          and(isSyntheticFixture, localContentIsNonEmpty),
+          and(
+            eq(items.bodyHydrationStatus, "hydrated"),
+            or(localContentDiffers, usesCurrentMediaConverter),
+          ),
+        ),
+      ),
+    );
+  return rows.map((row) => row.documentId);
+}
+
+/**
+ * Load a complete Builder review snapshot without transferring every heavy
+ * Builder body baseline. A light pass identifies field/stored changes, while a
+ * narrow body index compares the editable document with the readable baseline.
+ * Only candidate documents then load lossless body data and sidecars.
+ */
+export async function getContentDatabaseSourceSnapshotForReview(
+  database: ContentDatabaseRow | ContentDatabase,
+  sourceId?: string | null,
+  documentIds?: string[],
+): Promise<ContentDatabaseSource | null> {
+  if (documentIds?.length) {
+    return getContentDatabaseSourceSnapshotForWrite(
+      database,
+      sourceId,
+      documentIds,
+    );
+  }
+
+  const db = getDb();
+  const [source] = sourceId
+    ? await db
+        .select()
+        .from(schema.contentDatabaseSources)
+        .where(
+          and(
+            eq(schema.contentDatabaseSources.id, sourceId),
+            eq(schema.contentDatabaseSources.databaseId, database.id),
+          ),
+        )
+    : await db
+        .select()
+        .from(schema.contentDatabaseSources)
+        .where(eq(schema.contentDatabaseSources.databaseId, database.id))
+        .orderBy(
+          asc(schema.contentDatabaseSources.createdAt),
+          asc(schema.contentDatabaseSources.id),
+        );
+  if (!source) return null;
+
+  const lightweight = await loadSourceSnapshot(source, database, {
+    includeHeavyBuilderBodyValues: false,
+  });
+  const reviewableChanges = lightweight.changeSets.filter(
+    (changeSet) =>
+      changeSet.direction === "outbound" &&
+      (changeSet.state === "pending_push" ||
+        changeSet.state === "staged_revision" ||
+        changeSet.state === "approved"),
+  );
+  // The interactive review surface is capped at 100 rows. When a complete
+  // pending batch is already known, load heavy body/sidecar data only for those
+  // documents instead of first discovering body-only candidates. When no
+  // pending batch exists, the fallback compares bodies inside SQL and returns
+  // only candidate document IDs; article bodies never cross into application
+  // memory merely to prove that they are unchanged.
+  const knownReviewDocumentIds = knownBuilderReviewDocumentIds(
+    reviewableChanges,
+    100,
+  );
+  if (knownReviewDocumentIds) {
+    return loadSourceSnapshot(source, database, {
+      includeHeavyBuilderBodyValues: true,
+      documentIds: knownReviewDocumentIds,
+    });
+  }
+  if (reviewableChanges.some((changeSet) => !changeSet.documentId)) {
+    return loadSourceSnapshot(source, database, {
+      includeHeavyBuilderBodyValues: true,
+    });
+  }
+  const candidateDocumentIds = new Set(
+    reviewableChanges.flatMap((changeSet) =>
+      changeSet.documentId ? [changeSet.documentId] : [],
+    ),
+  );
+  for (const documentId of await findBuilderReviewBodyCandidateDocumentIds({
+    database,
+    source,
+  })) {
+    candidateDocumentIds.add(documentId);
+  }
+  if (candidateDocumentIds.size === 0) return lightweight;
+  return loadSourceSnapshot(source, database, {
+    includeHeavyBuilderBodyValues: true,
+    documentIds: [...candidateDocumentIds],
+  });
+}
+
 /**
  * Load every source attached to a database (oldest first → `[0]` is the
  * primary). Federation joins read this; single-source callers keep using
@@ -3941,11 +4384,12 @@ export function serializeBuilderCmsSourceReadMetadataRecord(args: {
   suspiciousEmpty?: boolean;
   builderModelFields?: BuilderCmsModelFieldSummary[];
   existingMetadataJson?: string | null;
+  completedBuilderContinuationClaimId?: string;
 }) {
   const existingMetadata = parseObject<SourceMetadataRecord>(
     args.existingMetadataJson,
   );
-  return JSON.stringify({
+  const metadata: SourceMetadataRecord = {
     ...builderCmsSourceMetadata(args.sourceTable),
     ...existingMetadata,
     builderModelFields:
@@ -3970,7 +4414,17 @@ export function serializeBuilderCmsSourceReadMetadataRecord(args: {
         : args.readState === "error"
           ? "error"
           : "idle"),
-  });
+  };
+  if (
+    args.completedBuilderContinuationClaimId &&
+    existingMetadata?.builderContinuationClaimId ===
+      args.completedBuilderContinuationClaimId
+  ) {
+    delete metadata.builderContinuationClaimId;
+    delete metadata.builderContinuationClaimOffset;
+    delete metadata.builderContinuationClaimedAt;
+  }
+  return JSON.stringify(metadata);
 }
 
 export function serializeSourceCapabilitiesRecord(
@@ -4084,6 +4538,63 @@ export function mergeBuilderCmsModelFieldsPreservingReferenceModels(args: {
   });
 }
 
+function builderSourceFieldPriority(provenance: string | null) {
+  return provenance === "Builder model field"
+    ? 0
+    : provenance === "Builder content field"
+      ? 1
+      : 2;
+}
+
+export function builderSourcePropertyAssignments(args: {
+  properties: Array<{
+    definition: { id: string; name: string; type: string };
+  }>;
+  existingFields?: Array<{
+    propertyId: string | null;
+    sourceFieldKey: string;
+    provenance: string | null;
+  }>;
+}) {
+  const existingByPropertyId = new Map(
+    (args.existingFields ?? [])
+      .filter((field) => field.propertyId)
+      .map((field) => [field.propertyId!, field]),
+  );
+  const canonicalPropertyBySourceKey = new Map<string, string>();
+  for (const field of [...(args.existingFields ?? [])]
+    .filter((candidate) => candidate.propertyId)
+    .sort(
+      (left, right) =>
+        builderSourceFieldPriority(left.provenance) -
+        builderSourceFieldPriority(right.provenance),
+    )) {
+    const key = field.sourceFieldKey.trim();
+    if (!canonicalPropertyBySourceKey.has(key)) {
+      canonicalPropertyBySourceKey.set(key, field.propertyId!);
+    }
+  }
+
+  const claimedSourceKeys = new Set<string>();
+  return args.properties.flatMap((property) => {
+    const existing = existingByPropertyId.get(property.definition.id);
+    const sourceFieldKey =
+      existing?.sourceFieldKey ??
+      builderCmsSourceFieldKey(
+        property.definition.id,
+        property.definition.name,
+      );
+    const normalizedKey = sourceFieldKey.trim();
+    const canonicalPropertyId = canonicalPropertyBySourceKey.get(normalizedKey);
+    if (canonicalPropertyId && canonicalPropertyId !== property.definition.id) {
+      return [];
+    }
+    if (claimedSourceKeys.has(normalizedKey)) return [];
+    claimedSourceKeys.add(normalizedKey);
+    return [{ property, sourceFieldKey }];
+  });
+}
+
 export async function seedMockSourceFields(args: {
   sourceId: string;
   ownerEmail: string;
@@ -4096,11 +4607,6 @@ export async function seedMockSourceFields(args: {
 }) {
   const db = getDb();
   const isBuilder = args.sourceType === "builder-cms";
-  const existingBuilderFieldByPropertyId = new Map(
-    (args.existingFields ?? [])
-      .filter((field) => isBuilder && field.propertyId)
-      .map((field) => [field.propertyId!, field]),
-  );
   const builderModelFieldBySourceKey = new Map(
     (args.builderModelFields ?? []).map((field) => [
       `data.${field.name.trim()}`,
@@ -4193,40 +4699,36 @@ export async function seedMockSourceFields(args: {
     // "Source") and only for Builder sources, so a user's own field happening
     // to be named "Source" — or any non-Builder/local-table source — is left
     // untouched.
-    ...args.properties
+    ...(isBuilder
+      ? builderSourcePropertyAssignments({
+          properties: args.properties,
+          existingFields: args.existingFields,
+        })
+      : args.properties.map((property) => ({
+          property,
+          sourceFieldKey: `fields.${slugifySourceField(property.definition.name)}`,
+        }))
+    )
       .filter(
-        (property) =>
+        ({ property }) =>
           !(
             isBuilder &&
             property.definition.name === SOURCE_PROPERTY_NAME &&
             property.definition.type === "select"
           ),
       )
-      .map((property) => ({
+      .map(({ property, sourceFieldKey }) => ({
         id: crypto.randomUUID(),
         ownerEmail: args.ownerEmail,
         sourceId: args.sourceId,
         propertyId: property.definition.id,
         localFieldKey: property.definition.id,
-        sourceFieldKey: isBuilder
-          ? (existingBuilderFieldByPropertyId.get(property.definition.id)
-              ?.sourceFieldKey ??
-            builderCmsSourceFieldKey(
-              property.definition.id,
-              property.definition.name,
-            ))
-          : `fields.${slugifySourceField(property.definition.name)}`,
+        sourceFieldKey,
         sourceFieldLabel: property.definition.name,
         sourceFieldType: isBuilder
           ? normalizeBuilderCmsSourceFieldType(
-              builderModelFieldBySourceKey.get(
-                existingBuilderFieldByPropertyId.get(property.definition.id)
-                  ?.sourceFieldKey ??
-                  builderCmsSourceFieldKey(
-                    property.definition.id,
-                    property.definition.name,
-                  ),
-              )?.type ?? property.definition.type,
+              builderModelFieldBySourceKey.get(sourceFieldKey)?.type ??
+                property.definition.type,
             )
           : property.definition.type,
         mappingType: "property",
@@ -4330,15 +4832,28 @@ export async function seedMockSourceFields(args: {
   }
 
   const existingFieldBySourceKey = new Map(
-    (args.existingFields ?? []).map((field) => [
-      sourceFieldIdentityKey(field.sourceFieldKey),
-      field,
-    ]),
+    [...(args.existingFields ?? [])]
+      // `Map` keeps the last value for a duplicate key, so sort the preferred
+      // provider-discovered field last. This fallback must agree with
+      // `builderSourcePropertyAssignments`, independent of database row order.
+      .sort(
+        (left, right) =>
+          builderSourceFieldPriority(right.provenance) -
+          builderSourceFieldPriority(left.provenance),
+      )
+      .map((field) => [sourceFieldIdentityKey(field.sourceFieldKey), field]),
+  );
+  const existingFieldByPropertyId = new Map(
+    (args.existingFields ?? [])
+      .filter((field) => field.propertyId)
+      .map((field) => [field.propertyId!, field]),
   );
   const mergedRows = rows.map((row) => {
-    const existing = existingFieldBySourceKey.get(
-      sourceFieldIdentityKey(row.sourceFieldKey),
-    );
+    const existing =
+      (row.propertyId
+        ? existingFieldByPropertyId.get(row.propertyId)
+        : undefined) ??
+      existingFieldBySourceKey.get(sourceFieldIdentityKey(row.sourceFieldKey));
     if (!existing) return row;
     return {
       ...row,
@@ -4367,77 +4882,88 @@ export async function seedMockSourceRows(args: {
 }) {
   if (args.items.length === 0) return;
   const db = getDb();
+  const rows = args.items.map((item, index) => {
+    const builderEntry = args.builderEntriesByDocumentId?.get(item.document.id);
+    const existingBuilderRow = args.existingBuilderRows?.get(item.document.id);
+    const builderIdentity =
+      args.sourceType === "builder-cms"
+        ? builderCmsSourceRowIdentity({
+            item,
+            sourceTable: args.sourceTable,
+            now: args.now,
+            existing: existingBuilderRow,
+            entry: builderEntry,
+          })
+        : null;
+    const sourceQualifiedId = builderIdentity
+      ? builderIdentity.sourceQualifiedId
+      : `${args.sourceType}://${args.sourceTable}/${item.document.id}`;
+    return {
+      id: builderIdentity
+        ? stableBuilderImportId("builder-row", [
+            args.sourceId,
+            sourceQualifiedId,
+            item.document.id,
+          ])
+        : crypto.randomUUID(),
+      ownerEmail: args.ownerEmail,
+      sourceId: args.sourceId,
+      databaseItemId: item.id,
+      documentId: item.document.id,
+      sourceRowId: builderIdentity
+        ? builderIdentity.sourceRowId
+        : `${args.sourceType}-${item.document.id}`,
+      sourceQualifiedId,
+      sourceDisplayKey:
+        builderIdentity?.sourceDisplayKey ??
+        item.document.title?.trim() ??
+        `${args.sourceType}-${index + 1}`,
+      sourceValuesJson: JSON.stringify(
+        sourceValuesForSeededSourceRow({
+          sourceType: args.sourceType,
+          item,
+          sourceTable: args.sourceTable,
+          now: args.now,
+          builderEntry,
+          existingSourceValuesJson: existingBuilderRow?.sourceValuesJson,
+          existingLastSourceUpdatedAt: existingBuilderRow?.lastSourceUpdatedAt,
+        }),
+      ),
+      provenance:
+        args.sourceType === "builder-cms"
+          ? builderEntry
+            ? "Builder CMS read adapter"
+            : (existingBuilderRow?.provenance ??
+              BUILDER_CMS_FIXTURE_ROW_PROVENANCE)
+          : "mock source row",
+      syncState: "linked",
+      freshness: "fresh",
+      lastSyncedAt: args.now,
+      lastSourceUpdatedAt: builderIdentity?.lastSourceUpdatedAt ?? args.now,
+      createdAt: args.now,
+      updatedAt: args.now,
+    };
+  });
   await db
     .insert(schema.contentDatabaseSourceRows)
-    .values(
-      args.items.map((item, index) => {
-        const builderEntry = args.builderEntriesByDocumentId?.get(
-          item.document.id,
-        );
-        const existingBuilderRow = args.existingBuilderRows?.get(
-          item.document.id,
-        );
-        const builderIdentity =
-          args.sourceType === "builder-cms"
-            ? builderCmsSourceRowIdentity({
-                item,
-                sourceTable: args.sourceTable,
-                now: args.now,
-                existing: existingBuilderRow,
-                entry: builderEntry,
-              })
-            : null;
-        const sourceQualifiedId = builderIdentity
-          ? builderIdentity.sourceQualifiedId
-          : `${args.sourceType}://${args.sourceTable}/${item.document.id}`;
-        return {
-          id: builderIdentity
-            ? stableBuilderImportId("builder-row", [
-                args.sourceId,
-                sourceQualifiedId,
-                item.document.id,
-              ])
-            : crypto.randomUUID(),
-          ownerEmail: args.ownerEmail,
-          sourceId: args.sourceId,
-          databaseItemId: item.id,
-          documentId: item.document.id,
-          sourceRowId: builderIdentity
-            ? builderIdentity.sourceRowId
-            : `${args.sourceType}-${item.document.id}`,
-          sourceQualifiedId,
-          sourceDisplayKey:
-            builderIdentity?.sourceDisplayKey ??
-            item.document.title?.trim() ??
-            `${args.sourceType}-${index + 1}`,
-          sourceValuesJson: JSON.stringify(
-            sourceValuesForSeededSourceRow({
-              sourceType: args.sourceType,
-              item,
-              sourceTable: args.sourceTable,
-              now: args.now,
-              builderEntry,
-              existingSourceValuesJson: existingBuilderRow?.sourceValuesJson,
-              existingLastSourceUpdatedAt:
-                existingBuilderRow?.lastSourceUpdatedAt,
-            }),
-          ),
-          provenance:
-            args.sourceType === "builder-cms"
-              ? args.builderEntriesByDocumentId?.has(item.document.id)
-                ? "Builder CMS read adapter"
-                : BUILDER_CMS_FIXTURE_ROW_PROVENANCE
-              : "mock source row",
-          syncState: "linked",
-          freshness: "fresh",
-          lastSyncedAt: args.now,
-          lastSourceUpdatedAt: builderIdentity?.lastSourceUpdatedAt ?? args.now,
-          createdAt: args.now,
-          updatedAt: args.now,
-        };
-      }),
-    )
+    .values(rows)
     .onConflictDoNothing();
+
+  const fixtureItemIds = rows
+    .filter((row) => row.provenance === BUILDER_CMS_FIXTURE_ROW_PROVENANCE)
+    .map((row) => row.databaseItemId);
+  for (const idChunk of chunks(fixtureItemIds, idChunkSize())) {
+    await db
+      .update(schema.contentDatabaseItems)
+      .set({
+        bodyHydrationStatus: "unavailable",
+        bodyHydrationAttemptedAt: args.now,
+        bodyHydrationError: null,
+        bodyHydrationVersion: null,
+        updatedAt: args.now,
+      })
+      .where(inArray(schema.contentDatabaseItems.id, idChunk));
+  }
 }
 
 export function sourceValuesForSeededSourceRow(args: {
@@ -5339,6 +5865,7 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
   source: ContentDatabaseSourceRowDb;
   now: string;
   runFullRefresh?: boolean;
+  refreshClaimId?: string;
 }) {
   let { properties, response } = await sourceSetupPayload(args.database.id);
   const db = getDb();
@@ -5395,12 +5922,29 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
     limit: args.runFullRefresh ? 10_000 : undefined,
     offset: continueOffset,
   });
+  if (builderRead.state === "error") {
+    throw new Error(
+      builderRead.message ??
+        "Builder CMS read failed; the previous source snapshot was preserved.",
+    );
+  }
   const incrementalRead =
     builderRead.state === "live" &&
     (builderRead.progress?.partial === true ||
       (builderRead.progress?.startOffset ?? 0) > 0);
   const builderEntries =
     builderRead.state === "live" ? builderRead.entries : [];
+  if (
+    args.refreshClaimId &&
+    !(await renewBuilderCmsSourceRefreshClaim({
+      sourceId: args.source.id,
+      claimId: args.refreshClaimId,
+    }))
+  ) {
+    throw new Error(
+      "Builder source refresh claim was lost before snapshot mutation.",
+    );
+  }
   let existingRows = await db
     .select()
     .from(schema.contentDatabaseSourceRows)
@@ -5432,6 +5976,7 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
       sourceFetchState: "error",
       syncState: "error",
       suspiciousEmpty: true,
+      refreshClaimId: args.refreshClaimId,
     });
     return;
   }
@@ -5478,6 +6023,7 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
         sourceRowId: row.sourceRowId,
         sourceQualifiedId: row.sourceQualifiedId,
         sourceDisplayKey: row.sourceDisplayKey,
+        provenance: row.provenance,
         lastSourceUpdatedAt: row.lastSourceUpdatedAt,
         sourceValuesJson: row.sourceValuesJson,
       },
@@ -5597,6 +6143,7 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
       sourceFetchState: hasMore ? "fetching" : "idle",
       syncState: hasMore ? "refreshing" : "idle",
       activeReadSourceRowIds: hasMore ? nextActiveReadSourceRowIds : undefined,
+      refreshClaimId: args.refreshClaimId,
     });
     return;
   }
@@ -5708,9 +6255,10 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
     message: builderRead.message,
     builderModelFields,
     progress: builderRead.progress,
-    sourceFetchState: builderRead.state === "error" ? "error" : "idle",
+    sourceFetchState: "idle",
     activeReadSourceRowIds: undefined,
     syncState: "idle",
+    refreshClaimId: args.refreshClaimId,
   });
 }
 
@@ -6024,18 +6572,18 @@ export async function writeSourceFederation(args: {
   federation: ContentDatabaseSourceFederation;
   now: string;
 }) {
-  const db = getDb();
-  const [current] = await db
-    .select({ metadataJson: schema.contentDatabaseSources.metadataJson })
-    .from(schema.contentDatabaseSources)
-    .where(eq(schema.contentDatabaseSources.id, args.sourceId));
-  const metadata =
-    parseObject<SourceMetadataRecord>(current?.metadataJson) ?? {};
-  metadata.federation = args.federation;
-  await db
-    .update(schema.contentDatabaseSources)
-    .set({ metadataJson: JSON.stringify(metadata), updatedAt: args.now })
-    .where(eq(schema.contentDatabaseSources.id, args.sourceId));
+  await mutateContentDatabaseSourceMetadata({
+    sourceId: args.sourceId,
+    now: args.now,
+    buildPatch: (current) => ({
+      metadataJson: JSON.stringify({
+        ...(parseObject<SourceMetadataRecord>(current.metadataJson) ?? {}),
+        federation: args.federation,
+      }),
+    }),
+    failureMessage:
+      "Source metadata changed repeatedly while saving federation settings.",
+  });
 }
 
 export async function updateBuilderCmsSourceReadMetadata(args: {
@@ -6053,58 +6601,87 @@ export async function updateBuilderCmsSourceReadMetadata(args: {
   syncState?: ContentDatabaseSourceSyncState;
   builderModelFields?: BuilderCmsModelFieldSummary[];
   suspiciousEmpty?: boolean;
+  refreshClaimId?: string;
 }) {
   const db = getDb();
-  const [currentSource] = await db
-    .select({
-      capabilitiesJson: schema.contentDatabaseSources.capabilitiesJson,
-      metadataJson: schema.contentDatabaseSources.metadataJson,
-      lastSourceUpdatedAt: schema.contentDatabaseSources.lastSourceUpdatedAt,
-    })
-    .from(schema.contentDatabaseSources)
-    .where(eq(schema.contentDatabaseSources.id, args.sourceId))
-    .limit(1);
-  const nextJson = mergeBuilderCmsWriteSettingsIntoJson({
-    sourceTable: args.sourceTable,
-    currentCapabilitiesJson: currentSource?.capabilitiesJson,
-    currentMetadataJson: currentSource?.metadataJson,
-    nextCapabilitiesJson: sourceCapabilitiesForType("builder-cms"),
-    nextMetadataJson: serializeBuilderCmsSourceReadMetadataRecord({
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const [currentSource] = await db
+      .select({
+        capabilitiesJson: schema.contentDatabaseSources.capabilitiesJson,
+        metadataJson: schema.contentDatabaseSources.metadataJson,
+        lastSourceUpdatedAt: schema.contentDatabaseSources.lastSourceUpdatedAt,
+      })
+      .from(schema.contentDatabaseSources)
+      .where(eq(schema.contentDatabaseSources.id, args.sourceId))
+      .limit(1);
+    if (!currentSource) throw new Error("Builder source not found.");
+    const currentMetadata = parseObject<SourceMetadataRecord>(
+      currentSource.metadataJson,
+    );
+    if (
+      args.refreshClaimId &&
+      currentMetadata?.builderContinuationClaimId !== args.refreshClaimId
+    ) {
+      throw new Error(
+        "Builder source refresh claim was lost before completion.",
+      );
+    }
+    const nextJson = mergeBuilderCmsWriteSettingsIntoJson({
       sourceTable: args.sourceTable,
-      readState: args.readState,
-      entryCount: args.entryCount,
-      matchedRowCount: args.matchedRowCount,
-      progress: args.progress,
-      sourceFetchState: args.sourceFetchState,
-      activeReadSourceRowIds: args.activeReadSourceRowIds,
-      suspiciousEmpty: args.suspiciousEmpty,
-      builderModelFields: args.builderModelFields,
-      existingMetadataJson: currentSource?.metadataJson,
-    }),
-  });
-  await db
-    .update(schema.contentDatabaseSources)
-    .set({
-      syncState: args.syncState ?? "linked",
-      freshness:
-        args.readState === "error" ||
-        args.progress?.partial ||
-        args.suspiciousEmpty
-          ? "stale"
-          : "fresh",
-      capabilitiesJson: nextJson.capabilitiesJson,
-      metadataJson: nextJson.metadataJson,
-      lastRefreshedAt: args.now,
-      lastSourceUpdatedAt: args.suspiciousEmpty
-        ? (currentSource?.lastSourceUpdatedAt ?? null)
-        : args.fetchedAt,
-      lastError:
-        args.readState === "error" || args.suspiciousEmpty
-          ? args.message
-          : null,
-      updatedAt: args.now,
-    })
-    .where(eq(schema.contentDatabaseSources.id, args.sourceId));
+      currentCapabilitiesJson: currentSource.capabilitiesJson,
+      currentMetadataJson: currentSource.metadataJson,
+      nextCapabilitiesJson: sourceCapabilitiesForType("builder-cms"),
+      nextMetadataJson: serializeBuilderCmsSourceReadMetadataRecord({
+        sourceTable: args.sourceTable,
+        readState: args.readState,
+        entryCount: args.entryCount,
+        matchedRowCount: args.matchedRowCount,
+        progress: args.progress,
+        sourceFetchState: args.sourceFetchState,
+        activeReadSourceRowIds: args.activeReadSourceRowIds,
+        suspiciousEmpty: args.suspiciousEmpty,
+        builderModelFields: args.builderModelFields,
+        existingMetadataJson: currentSource.metadataJson,
+        completedBuilderContinuationClaimId: args.refreshClaimId,
+      }),
+    });
+    const updated = await db
+      .update(schema.contentDatabaseSources)
+      .set({
+        syncState: args.syncState ?? "linked",
+        freshness:
+          args.readState === "error" ||
+          args.progress?.partial ||
+          args.suspiciousEmpty
+            ? "stale"
+            : "fresh",
+        capabilitiesJson: nextJson.capabilitiesJson,
+        metadataJson: nextJson.metadataJson,
+        lastRefreshedAt: args.now,
+        lastSourceUpdatedAt: args.suspiciousEmpty
+          ? currentSource.lastSourceUpdatedAt
+          : args.fetchedAt,
+        lastError:
+          args.readState === "error" || args.suspiciousEmpty
+            ? args.message
+            : null,
+        updatedAt: args.now,
+      })
+      .where(
+        and(
+          eq(schema.contentDatabaseSources.id, args.sourceId),
+          currentSource.metadataJson === null
+            ? isNull(schema.contentDatabaseSources.metadataJson)
+            : eq(
+                schema.contentDatabaseSources.metadataJson,
+                currentSource.metadataJson,
+              ),
+        ),
+      )
+      .returning({ id: schema.contentDatabaseSources.id });
+    if (updated.length > 0) return;
+  }
+  throw new Error("Builder source metadata changed repeatedly during refresh.");
 }
 
 export async function updateReadOnlySourceMetadata(args: {
@@ -6117,27 +6694,24 @@ export async function updateReadOnlySourceMetadata(args: {
   metadata?: Record<string, unknown>;
   syncState?: ContentDatabaseSourceSyncState;
 }) {
-  const db = getDb();
-  const [current] = await db
-    .select({ metadataJson: schema.contentDatabaseSources.metadataJson })
-    .from(schema.contentDatabaseSources)
-    .where(eq(schema.contentDatabaseSources.id, args.sourceId))
-    .limit(1);
-  const existing =
-    parseObject<Record<string, unknown>>(current?.metadataJson) ?? {};
-  await db
-    .update(schema.contentDatabaseSources)
-    .set({
+  await mutateContentDatabaseSourceMetadata({
+    sourceId: args.sourceId,
+    now: args.now,
+    buildPatch: (current) => ({
       syncState: args.syncState ?? (args.message ? "refreshing" : "linked"),
       freshness: args.message ? "stale" : "fresh",
       capabilitiesJson: sourceCapabilitiesForType(args.sourceType),
-      metadataJson: JSON.stringify({ ...existing, ...(args.metadata ?? {}) }),
+      metadataJson: JSON.stringify({
+        ...(parseObject<Record<string, unknown>>(current.metadataJson) ?? {}),
+        ...(args.metadata ?? {}),
+      }),
       lastRefreshedAt: args.now,
       lastSourceUpdatedAt: args.fetchedAt,
       lastError: null,
-      updatedAt: args.now,
-    })
-    .where(eq(schema.contentDatabaseSources.id, args.sourceId));
+    }),
+    failureMessage:
+      "Source metadata changed repeatedly while saving read state.",
+  });
 }
 
 export async function getExistingSource(databaseId: string) {