@agent-native/core 0.101.7 → 0.101.11

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

@@ -1,4 +1,5 @@
-import { deleteCollabState, releaseDoc } from "@agent-native/core/collab";
+import { createHash } from "node:crypto";
+
 import { getDialect, type Dialect } from "@agent-native/core/db";
 import { and, asc, eq, inArray, isNull, or, sql } from "drizzle-orm";
 
@@ -38,6 +39,7 @@ import type {
 import {
   builderBlocksHash,
   builderBlocksToReadableMarkdown,
+  builderEntryBlocks,
   builderEntryToReadableMdxBundle,
   builderEntryToMdxBundle,
   builderReadableBodyToBuilderBlocks,
@@ -64,6 +66,7 @@ import {
 import {
   BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
   BUILDER_CMS_BODY_CONTENT_KEY,
+  BUILDER_CMS_BODY_LAST_UPDATED_KEY,
   BUILDER_CMS_BODY_LOSSLESS_CONTENT_KEY,
   BUILDER_CMS_BODY_READABLE_MAP_KEY,
   BUILDER_CMS_BODY_SIDECARS_KEY,
@@ -73,6 +76,7 @@ import {
   builderCmsSourceFieldKey,
   builderCmsSourceMetadata,
   builderCmsSourceRowIdentity,
+  builderCmsSourceRowIdentityState,
   type BuilderCmsSourceEntry,
   type ExistingBuilderSourceRowIdentity,
 } from "./_builder-cms-source-adapter.js";
@@ -103,6 +107,16 @@ type ContentDatabaseSourceChangeReviewRowDb =
 type ContentDatabaseSourceExecutionRowDb =
   typeof schema.contentDatabaseSourceExecutions.$inferSelect;
 
+function stableBuilderImportId(
+  prefix: "builder-doc" | "builder-item" | "builder-row",
+  parts: readonly string[],
+) {
+  return `${prefix}_${createHash("sha256")
+    .update(parts.join("\0"))
+    .digest("base64url")
+    .slice(0, 24)}`;
+}
+
 const DEFAULT_SOURCE_CAPABILITIES: ContentDatabaseSourceCapabilities = {
   canRefresh: true,
   canCreateChangeSets: true,
@@ -319,7 +333,7 @@ export function serializeSourceField(
   };
 }
 
-function serializeSourceRowRecord(
+export function serializeSourceRowRecord(
   row: ContentDatabaseSourceRecordRowDb,
   options: { includeHeavyBuilderBodyValues?: boolean } = {},
 ): ContentDatabaseSourceRow {
@@ -393,6 +407,37 @@ function sourceSnapshotRowSelection(args: {
   };
 }
 
+// Snapshot reads need document titles for change-set summaries. Body text is
+// required only by write/review paths that explicitly request heavy Builder
+// body values; routine list and source reads must not transfer it.
+export function sourceSnapshotDocumentSelection(
+  includeHeavyBuilderBodyValues: true,
+): {
+  id: typeof schema.documents.id;
+  title: typeof schema.documents.title;
+  content: typeof schema.documents.content;
+};
+export function sourceSnapshotDocumentSelection(
+  includeHeavyBuilderBodyValues: false,
+): {
+  id: typeof schema.documents.id;
+  title: typeof schema.documents.title;
+};
+export function sourceSnapshotDocumentSelection(
+  includeHeavyBuilderBodyValues: boolean,
+) {
+  return includeHeavyBuilderBodyValues
+    ? {
+        id: schema.documents.id,
+        title: schema.documents.title,
+        content: schema.documents.content,
+      }
+    : {
+        id: schema.documents.id,
+        title: schema.documents.title,
+      };
+}
+
 export function sourceValuesForSnapshot(
   sourceValues: Record<string, DocumentPropertyValue>,
   options: { includeHeavyBuilderBodyValues?: boolean } = {},
@@ -468,6 +513,47 @@ function serializeExecution(
   };
 }
 
+/**
+ * A blocked execution with neither an attempt token nor a response proves it
+ * stopped before the Builder dispatch claim. This includes a blocked dry run
+ * and a validated plan stopped by the final live preflight. Any other state or
+ * remote evidence stays frozen until normal reconciliation resolves it.
+ */
+export function builderExecutionIsProvablyLocallyBlockedUnsent(execution: {
+  state: string;
+  payloadJson: string;
+  attemptToken?: string | null;
+}) {
+  const payload = parseObject<Record<string, unknown>>(execution.payloadJson);
+  return (
+    execution.state === "blocked" &&
+    !execution.attemptToken &&
+    !(payload?.response && typeof payload.response === "object")
+  );
+}
+
+export function canRefreshLocallyBlockedBuilderReview(
+  executions: Array<{
+    state: string;
+    payloadJson: string;
+    attemptToken?: string | null;
+  }>,
+) {
+  return (
+    executions.length === 0 ||
+    executions.every(builderExecutionIsProvablyLocallyBlockedUnsent)
+  );
+}
+
+export const CANCELLED_BUILDER_EXECUTION_SUMMARY =
+  "Cancelled before Builder dispatch.";
+export const CANCELLED_BUILDER_REVIEW_NOTE_PREFIX =
+  "Cancelled prepared Builder update before dispatch";
+
+export function builderReferenceIdSourceValueKey(sourceFieldKey: string) {
+  return `__agent_native_builder_reference_id:${sourceFieldKey}`;
+}
+
 function riskRank(level: ContentDatabaseSourceRiskLevel) {
   if (level === "high") return 3;
   if (level === "medium") return 2;
@@ -609,7 +695,8 @@ const BUILDER_BODY_HYDRATION_OPEN_PRIORITY = 0;
 const BUILDER_BODY_HYDRATION_BATCH_LIMIT = 25;
 const BUILDER_BODY_HYDRATION_PROCESS_CONCURRENCY = 6;
 const BUILDER_BODY_HYDRATION_MAX_ATTEMPTS = 5;
-const BUILDER_BODY_HYDRATION_CODEC_VERSION = "readable-native-images-v5";
+const BUILDER_BODY_HYDRATION_CODEC_VERSION =
+  "readable-native-images-authoritative-raw-baseline-v9";
 const BUILDER_CMS_REFRESH_INITIAL_PAGES = 1;
 const BUILDER_BODY_NOT_AVAILABLE_ERROR = "body not yet available from Builder";
 
@@ -686,12 +773,27 @@ async function builderBodySnapshotForEntry(entry: BuilderCmsSourceEntry) {
   return {
     content: readableBundle.mdx.body,
     losslessContent: losslessBundle.mdx.body,
-    blocksHash: builderBlocksHash(losslessBundle.blocks),
+    blocksHash: builderAuthoritativeRawBodyHash({
+      entry,
+      generatedBlocks: losslessBundle.blocks,
+    }),
     readableMapJson: null,
     sidecarsJson: JSON.stringify(sidecars),
   };
 }
 
+export function builderAuthoritativeRawBodyHash(args: {
+  entry: BuilderCmsSourceEntry;
+  generatedBlocks: unknown[];
+}) {
+  const rawBlocks = args.entry.rawEntry
+    ? builderEntryBlocks(args.entry.rawEntry)
+    : [];
+  return builderBlocksHash(
+    rawBlocks.length > 0 ? rawBlocks : args.generatedBlocks,
+  );
+}
+
 export function builderBodyHydrationVersion(entry: BuilderCmsSourceEntry) {
   const hash = stringSourceValue(
     entry.sourceValues,
@@ -700,6 +802,15 @@ export function builderBodyHydrationVersion(entry: BuilderCmsSourceEntry) {
   return `${hash ?? entry.updatedAt ?? entry.id}:${BUILDER_BODY_HYDRATION_CODEC_VERSION}`;
 }
 
+export function builderBodyUnavailableVersion(entry: BuilderCmsSourceEntry) {
+  const lastUpdated =
+    stringSourceValue(entry.sourceValues, BUILDER_CMS_BODY_LAST_UPDATED_KEY) ??
+    stringSourceValue(entry.sourceValues, "lastUpdated") ??
+    entry.updatedAt ??
+    entry.id;
+  return `${lastUpdated}:${BUILDER_BODY_HYDRATION_CODEC_VERSION}`;
+}
+
 function normalizeHydrationLimit(limit: number | null | undefined) {
   if (typeof limit !== "number" || !Number.isFinite(limit)) {
     return BUILDER_BODY_HYDRATION_BATCH_LIMIT;
@@ -800,9 +911,14 @@ function builderStoredBodyIsStale(args: {
   >;
   entry: BuilderCmsSourceEntry;
 }) {
+  const expectedVersion =
+    args.item.bodyHydrationStatus === "unavailable"
+      ? builderBodyUnavailableVersion(args.entry)
+      : builderBodyHydrationVersion(args.entry);
   return (
-    args.item.bodyHydrationStatus !== "hydrated" ||
-    args.item.bodyHydrationVersion !== builderBodyHydrationVersion(args.entry)
+    (args.item.bodyHydrationStatus !== "hydrated" &&
+      args.item.bodyHydrationStatus !== "unavailable") ||
+    args.item.bodyHydrationVersion !== expectedVersion
   );
 }
 
@@ -813,7 +929,7 @@ function builderEntryHasBodyContent(entry: BuilderCmsSourceEntry | null) {
   )?.trim();
 }
 
-async function readableBuilderBodyFromStoredLossless(args: {
+async function builderBodySnapshotFromStoredLossless(args: {
   losslessContent: string | null;
   sidecarsJson: string | null;
 }) {
@@ -825,12 +941,60 @@ async function readableBuilderBodyFromStoredLossless(args: {
     sidecars,
   );
   if (blocks.length === 0) return null;
-  return builderBlocksToReadableMarkdown(blocks);
+  return {
+    content: await builderBlocksToReadableMarkdown(blocks),
+    blocksHash: builderBlocksHash(blocks),
+  };
+}
+
+export function builderBodyHydrationNeedsLiveBaseline(args: {
+  bodyHydrationVersion: string | null | undefined;
+  storedBlocksHash: string | null | undefined;
+  rebuiltBlocksHash: string | null | undefined;
+}) {
+  if (!args.storedBlocksHash) return false;
+  if (
+    args.bodyHydrationVersion &&
+    !args.bodyHydrationVersion.endsWith(
+      `:${BUILDER_BODY_HYDRATION_CODEC_VERSION}`,
+    )
+  ) {
+    return true;
+  }
+  return Boolean(
+    !args.rebuiltBlocksHash || args.storedBlocksHash !== args.rebuiltBlocksHash,
+  );
+}
+
+export function builderBodyHydrationIsCodecMigration(
+  bodyHydrationVersion: string | null | undefined,
+) {
+  return Boolean(
+    bodyHydrationVersion &&
+    !bodyHydrationVersion.endsWith(`:${BUILDER_BODY_HYDRATION_CODEC_VERSION}`),
+  );
+}
+
+export function builderBodyHydrationCanAdoptSameVersionVariant(args: {
+  documentContent: string | null | undefined;
+  persistedContent: string | null | undefined;
+}) {
+  return (
+    args.documentContent !== undefined &&
+    normalizeBuilderBodyBaselineContent(args.documentContent) ===
+      normalizeBuilderBodyBaselineContent(args.persistedContent)
+  );
 }
 
-async function refreshBuilderBodySourceValuesFromStoredLossless(
+export async function refreshBuilderBodySourceValuesFromStoredLossless(
   entry: BuilderCmsSourceEntry,
 ) {
+  if (entry.rawEntry && builderEntryBlocks(entry.rawEntry).length > 0) {
+    // A fresh single-entry Builder read is the authoritative preflight
+    // representation. Never replace its raw block hash with a hash rebuilt
+    // from generated lossless MDX.
+    return entry;
+  }
   const losslessContent = stringSourceValue(
     entry.sourceValues,
     BUILDER_CMS_BODY_LOSSLESS_CONTENT_KEY,
@@ -839,20 +1003,51 @@ async function refreshBuilderBodySourceValuesFromStoredLossless(
     entry.sourceValues,
     BUILDER_CMS_BODY_SIDECARS_KEY,
   );
-  const content = await readableBuilderBodyFromStoredLossless({
+  const snapshot = await builderBodySnapshotFromStoredLossless({
     losslessContent,
     sidecarsJson,
   });
-  if (!content) return entry;
+  if (!snapshot) return entry;
   return {
     ...entry,
     sourceValues: {
       ...entry.sourceValues,
-      [BUILDER_CMS_BODY_CONTENT_KEY]: content,
+      [BUILDER_CMS_BODY_CONTENT_KEY]: snapshot.content,
+      [BUILDER_CMS_BODY_BLOCKS_HASH_KEY]: snapshot.blocksHash,
     },
   };
 }
 
+function builderTimestampEpoch(value: string | null | undefined) {
+  if (!value?.trim()) return null;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric)) return numeric;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function builderBodyBaselineHasSameVersionConflict(args: {
+  persistedBlocksHash: string | null | undefined;
+  incomingBlocksHash: string | null | undefined;
+  persistedLastUpdated: string | null | undefined;
+  incomingLastUpdated: string | null | undefined;
+}) {
+  if (
+    !args.persistedBlocksHash ||
+    !args.incomingBlocksHash ||
+    args.persistedBlocksHash === args.incomingBlocksHash
+  ) {
+    return false;
+  }
+  const persistedEpoch = builderTimestampEpoch(args.persistedLastUpdated);
+  const incomingEpoch = builderTimestampEpoch(args.incomingLastUpdated);
+  return (
+    persistedEpoch !== null &&
+    incomingEpoch !== null &&
+    persistedEpoch === incomingEpoch
+  );
+}
+
 function builderEntryFromSourceRow(args: {
   row: Pick<
     ContentDatabaseSourceRecordRowDb,
@@ -911,8 +1106,12 @@ async function readBuilderEntryWithLiveBodyFromSourceRow(args: {
       ...liveEntry.sourceValues,
     },
   };
-  const refreshedEntry = await refreshBuilderBodySourceValuesFromStoredLossless(
-    await withBuilderBodySourceValues(entryWithStoredValues),
+  // This entry came from a fresh Builder response. Preserve the block hash
+  // computed from those authoritative raw blocks; rebuilding the generated
+  // lossless MDX can normalize block details and produce a different hash than
+  // the execute-time live preflight sees for the same response.
+  const refreshedEntry = await withBuilderBodySourceValues(
+    entryWithStoredValues,
   );
   return builderEntryHasBodyContent(refreshedEntry) ? refreshedEntry : null;
 }
@@ -1068,15 +1267,84 @@ export async function enqueueBuilderBodyHydrationForItems(args: {
   now: string;
 }) {
   if (!args.builderEntriesByDocumentId?.size) return;
+  const persistedStateByDocumentId = new Map<
+    string,
+    {
+      entry: BuilderCmsSourceEntry;
+      bodyHydrationStatus: string | null;
+      bodyHydrationVersion: string | null;
+      documentContent: string | null;
+    }
+  >();
+  const documentIds = args.items.map((item) => item.document.id);
+  for (const documentIdChunk of chunks(documentIds, idChunkSize())) {
+    const rows = await getDb()
+      .select({
+        documentId: schema.contentDatabaseSourceRows.documentId,
+        sourceRowId: schema.contentDatabaseSourceRows.sourceRowId,
+        sourceValuesJson: schema.contentDatabaseSourceRows.sourceValuesJson,
+        lastSourceUpdatedAt:
+          schema.contentDatabaseSourceRows.lastSourceUpdatedAt,
+        bodyHydrationStatus: schema.contentDatabaseItems.bodyHydrationStatus,
+        bodyHydrationVersion: schema.contentDatabaseItems.bodyHydrationVersion,
+        documentContent: schema.documents.content,
+      })
+      .from(schema.contentDatabaseSourceRows)
+      .innerJoin(
+        schema.contentDatabaseItems,
+        eq(
+          schema.contentDatabaseItems.id,
+          schema.contentDatabaseSourceRows.databaseItemId,
+        ),
+      )
+      .innerJoin(
+        schema.documents,
+        eq(schema.documents.id, schema.contentDatabaseSourceRows.documentId),
+      )
+      .where(
+        and(
+          eq(schema.contentDatabaseSourceRows.sourceId, args.sourceId),
+          inArray(schema.contentDatabaseSourceRows.documentId, documentIdChunk),
+        ),
+      );
+    for (const row of rows) {
+      const entry = builderEntryFromSourceRow({
+        row,
+        sourceTable: args.sourceTable,
+        fallbackTitle: row.sourceRowId ?? row.documentId,
+      });
+      if (entry) {
+        persistedStateByDocumentId.set(row.documentId, {
+          entry,
+          bodyHydrationStatus: row.bodyHydrationStatus,
+          bodyHydrationVersion: row.bodyHydrationVersion,
+          documentContent: row.documentContent,
+        });
+      }
+    }
+  }
   const requests: BuilderBodyHydrationEnqueueRequest[] = [];
   for (const item of args.items) {
     const entry = args.builderEntriesByDocumentId.get(item.document.id);
     if (!entry) continue;
+    const persistedState = persistedStateByDocumentId.get(item.document.id);
+    const persistedEntry = persistedState?.entry ?? entry;
+    const bodyHydrationStatus =
+      persistedState?.bodyHydrationStatus ?? item.bodyHydration?.status;
+    const bodyHydrationVersion =
+      persistedState?.bodyHydrationVersion ?? item.bodyHydration?.version;
+    const documentContent =
+      persistedState?.documentContent ?? item.document.content;
+    const expectedVersion =
+      bodyHydrationStatus === "unavailable"
+        ? builderBodyUnavailableVersion(persistedEntry)
+        : builderBodyHydrationVersion(persistedEntry);
     if (
-      item.bodyHydration?.status === "hydrated" &&
-      item.bodyHydration.version === builderBodyHydrationVersion(entry) &&
-      !isEffectivelyEmptyDocumentContent(item.document.content) &&
-      !builderBodyIsRawPlaceholderOnly(item.document.content)
+      (bodyHydrationStatus === "unavailable" ||
+        (bodyHydrationStatus === "hydrated" &&
+          !isEffectivelyEmptyDocumentContent(documentContent) &&
+          !builderBodyIsRawPlaceholderOnly(documentContent))) &&
+      bodyHydrationVersion === expectedVersion
     ) {
       continue;
     }
@@ -1197,11 +1465,16 @@ async function processBuilderBodyHydrationJob(
   preloaded?: {
     sourceRow?: ContentDatabaseSourceRecordRowDb | null;
     documentContent?: string | null;
+    bodyHydrationVersion?: string | null;
   },
 ) {
   const db = getDb();
   const entry = parseHydrationEntry(row);
   if (!entry) throw new Error("Builder body hydration entry is missing.");
+  const queuedBlocksHash = stringSourceValue(
+    entry.sourceValues,
+    BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+  );
   let activeSourceEntryJson = row.sourceEntryJson;
   let entryWithBody = await refreshBuilderBodySourceValuesFromStoredLossless(
     await withBuilderBodySourceValues(entry),
@@ -1227,6 +1500,73 @@ async function processBuilderBodyHydrationJob(
     parseObject<Record<string, DocumentPropertyValue>>(
       sourceRow?.sourceValuesJson ?? "{}",
     ) ?? {};
+  const rebuiltBlocksHash = stringSourceValue(
+    entryWithBody.sourceValues,
+    BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+  );
+  const storedBlocksHash =
+    queuedBlocksHash ??
+    stringSourceValue(sourceValues, BUILDER_CMS_BODY_BLOCKS_HASH_KEY);
+  const isCodecMigration = builderBodyHydrationIsCodecMigration(
+    preloaded?.bodyHydrationVersion,
+  );
+  if (
+    builderBodyHydrationNeedsLiveBaseline({
+      bodyHydrationVersion: preloaded?.bodyHydrationVersion,
+      storedBlocksHash,
+      rebuiltBlocksHash,
+    })
+  ) {
+    if (!sourceRow) {
+      throw new Error(
+        "Builder body baseline migration requires a linked source row.",
+      );
+    }
+    const liveEntry = await readBuilderEntryWithLiveBodyFromSourceRow({
+      row: sourceRow,
+      sourceTable: row.sourceTable,
+      fallbackTitle: entry.title,
+    });
+    if (!liveEntry) {
+      throw new Error(
+        "Builder body baseline migration could not read a fresh remote body; retry the refresh before reviewing or publishing.",
+      );
+    }
+    entryWithBody = liveEntry;
+  }
+  const incomingBlocksHash = stringSourceValue(
+    entryWithBody.sourceValues,
+    BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+  );
+  const persistedBaselineLastUpdated =
+    stringSourceValue(sourceValues, BUILDER_CMS_BODY_LAST_UPDATED_KEY) ??
+    stringSourceValue(sourceValues, "lastUpdated");
+  const incomingLastUpdated =
+    stringSourceValue(entryWithBody.sourceValues, "lastUpdated") ??
+    entryWithBody.updatedAt;
+  if (
+    !isCodecMigration &&
+    builderBodyBaselineHasSameVersionConflict({
+      persistedBlocksHash: stringSourceValue(
+        sourceValues,
+        BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+      ),
+      incomingBlocksHash,
+      persistedLastUpdated: persistedBaselineLastUpdated,
+      incomingLastUpdated,
+    }) &&
+    !builderBodyHydrationCanAdoptSameVersionVariant({
+      documentContent: preloaded?.documentContent,
+      persistedContent: stringSourceValue(
+        sourceValues,
+        BUILDER_CMS_BODY_CONTENT_KEY,
+      ),
+    })
+  ) {
+    throw new Error(
+      "Builder returned inconsistent body variants for the same lastUpdated value; the stored baseline and local document were preserved for retry.",
+    );
+  }
   let nextValues = {
     ...sourceValues,
     ...entryWithBody.sourceValues,
@@ -1355,9 +1695,11 @@ async function processBuilderBodyHydrationJob(
           await tx
             .update(schema.contentDatabaseItems)
             .set({
-              bodyHydrationStatus: "error",
+              bodyHydrationStatus: "unavailable",
               bodyHydrationAttemptedAt: now,
-              bodyHydrationError: BUILDER_BODY_NOT_AVAILABLE_ERROR,
+              bodyHydrationError: null,
+              bodyHydrationVersion:
+                builderBodyUnavailableVersion(entryWithBody),
               updatedAt: now,
             })
             .where(eq(schema.contentDatabaseItems.id, row.databaseItemId));
@@ -1570,14 +1912,11 @@ async function processBuilderBodyHydrationJob(
       })
       .where(eq(schema.contentDatabaseItems.id, row.databaseItemId));
   });
-  if (wroteBody) {
-    try {
-      await deleteCollabState(row.documentId);
-      releaseDoc(row.documentId);
-    } catch {
-      // Non-fatal: the updated document row still lets open editors reconcile.
-    }
-  }
+  // Keep persisted and in-memory Yjs state intact. The SQL content + updatedAt
+  // written above are authoritative; an open full-page editor reconciles that
+  // snapshot into its Y.Doc. Deleting collab state here can race a connected
+  // client, briefly bootstrap an empty fragment, and let that stale client
+  // repersist the empty state over the newly hydrated Builder body.
 }
 
 async function enqueueStaleBuilderBodyHydrationForOpenDocument(args: {
@@ -1796,6 +2135,29 @@ export async function processBuilderBodyHydrationQueue(args: {
   const sourceRowsByItemId = new Map(
     sourceRows.map((row) => [row.databaseItemId, row]),
   );
+  const itemVersions =
+    claimedJobs.length > 0
+      ? (
+          await Promise.all(
+            chunks(
+              claimedJobs.map((job) => job.databaseItemId),
+              idChunkSize(),
+            ).map((idChunk) =>
+              db
+                .select({
+                  id: schema.contentDatabaseItems.id,
+                  bodyHydrationVersion:
+                    schema.contentDatabaseItems.bodyHydrationVersion,
+                })
+                .from(schema.contentDatabaseItems)
+                .where(inArray(schema.contentDatabaseItems.id, idChunk)),
+            ),
+          )
+        ).flat()
+      : [];
+  const bodyHydrationVersionByItemId = new Map(
+    itemVersions.map((item) => [item.id, item.bodyHydrationVersion]),
+  );
   const documents =
     claimedJobs.length > 0
       ? (
@@ -1828,6 +2190,8 @@ export async function processBuilderBodyHydrationQueue(args: {
         if (delayMs > 0) await sleep(delayMs);
         await processBuilderBodyHydrationJob(job, attemptNow, {
           sourceRow: sourceRowsByItemId.get(job.databaseItemId) ?? null,
+          bodyHydrationVersion:
+            bodyHydrationVersionByItemId.get(job.databaseItemId) ?? null,
           documentContent: documentContentById.has(job.documentId)
             ? (documentContentById.get(job.documentId) ?? null)
             : undefined,
@@ -1935,6 +2299,8 @@ export async function withBuilderBodySourceValues(
       [BUILDER_CMS_BODY_LOSSLESS_CONTENT_KEY]: snapshot.losslessContent,
       [BUILDER_CMS_BODY_READABLE_MAP_KEY]: snapshot.readableMapJson,
       [BUILDER_CMS_BODY_BLOCKS_HASH_KEY]: snapshot.blocksHash,
+      [BUILDER_CMS_BODY_LAST_UPDATED_KEY]:
+        stringSourceValue(entry.sourceValues, "lastUpdated") ?? entry.updatedAt,
       [BUILDER_CMS_BODY_SIDECARS_KEY]: snapshot.sidecarsJson,
     },
   };
@@ -1973,9 +2339,17 @@ export async function builderBodyChangeForLocalContent(args: {
   const localContent = args.localContent ?? "";
   if (!currentHash && !currentContent && !localContent.trim()) return null;
   if (!currentContent?.trim() && !losslessContent?.trim()) return null;
+  // Native media is converter-owned output. Re-run it even when the editable
+  // Markdown text is byte-for-byte unchanged: a converter upgrade can turn a
+  // 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);
   const normalizedLocalContent =
     normalizeBuilderBodyBaselineContent(localContent);
   if (
+    !usesCurrentMediaConverter &&
     normalizedLocalContent &&
     normalizedLocalContent ===
       normalizeBuilderBodyBaselineContent(currentContent)
@@ -1983,6 +2357,7 @@ export async function builderBodyChangeForLocalContent(args: {
     return null;
   }
   if (
+    !usesCurrentMediaConverter &&
     normalizedLocalContent &&
     normalizedLocalContent ===
       normalizeBuilderBodyBaselineContent(losslessContent)
@@ -2005,8 +2380,15 @@ export async function builderBodyChangeForLocalContent(args: {
   }
 
   try {
-    const proposed =
-      losslessContent && !localContent.includes("<Builder")
+    const proposed = usesCurrentMediaConverter
+      ? {
+          blocks: await builderMdxBodyToBuilderBlocks(
+            normalizeUnsourcedBuilderCreateMdx(localContent),
+            sidecars,
+          ),
+          warnings: [] as string[],
+        }
+      : losslessContent && !localContent.includes("<Builder")
         ? await builderReadableBodyToBuilderBlocks({
             localContent,
             losslessContent,
@@ -2062,6 +2444,98 @@ export async function builderBodyChangeForLocalContent(args: {
   }
 }
 
+function htmlMediaAttribute(tag: string, name: string) {
+  const match = tag.match(
+    new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i"),
+  );
+  return match?.[1] ?? match?.[2] ?? null;
+}
+
+function normalizeUnsourcedBuilderCreateMdx(content: string) {
+  return content.replace(/<img\b[^>]*\/?\s*>/gi, (tag) => {
+    const src = htmlMediaAttribute(tag, "src");
+    if (!src) return tag;
+    const alt = htmlMediaAttribute(tag, "alt") ?? "";
+    return `![${alt.replace(/]/g, "\\]")}](${src.replace(/\)/g, "%29")})`;
+  });
+}
+
+export async function builderBodyChangeForUnsourcedLocalCreate(args: {
+  localContent: string | null | undefined;
+}): Promise<ContentDatabaseSourceBodyChange | null> {
+  const localContent = args.localContent ?? "";
+  if (!localContent.trim()) return null;
+  const sidecarsJson = "{}";
+
+  try {
+    const blocks = await builderMdxBodyToBuilderBlocks(
+      normalizeUnsourcedBuilderCreateMdx(localContent),
+      {},
+    );
+    return {
+      summary: "Builder draft body ready to create.",
+      currentExcerpt: null,
+      proposedExcerpt: bodyExcerpt(localContent),
+      currentHash: null,
+      proposedHash: builderBlocksHash(blocks),
+      proposedContent: localContent,
+      proposedBlocksJson: JSON.stringify(blocks),
+      sidecarsJson,
+      warnings: [],
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? error.message
+        : "Builder body could not be converted.";
+    return {
+      summary: "Builder draft body needs attention before create.",
+      currentExcerpt: null,
+      proposedExcerpt: bodyExcerpt(localContent),
+      currentHash: null,
+      proposedHash: null,
+      proposedContent: localContent,
+      proposedBlocksJson: null,
+      sidecarsJson,
+      warnings: [message],
+    };
+  }
+}
+
+export async function builderBodyChangeForSourceSnapshotDocument(args: {
+  row?: {
+    documentId: string;
+    sourceRowId: string;
+    sourceQualifiedId: string;
+    provenance: string | null;
+    sourceValuesJson: string;
+  };
+  isHydrated: boolean;
+  allowUnsourcedCreate: boolean;
+  localContent: string | null | undefined;
+}): Promise<ContentDatabaseSourceBodyChange | null> {
+  if (args.row) {
+    const identity = builderCmsSourceRowIdentityState({ row: args.row });
+    if (identity.isSyntheticFixture) {
+      // Fixture rows are local placeholders, not imported Builder baselines.
+      // Execution resolves their synthetic identity to create_draft, so their
+      // local body must follow the same create path even before hydration.
+      return builderBodyChangeForUnsourcedLocalCreate({
+        localContent: args.localContent,
+      });
+    }
+    if (!args.isHydrated) return null;
+    return builderBodyChangeForLocalContent({
+      row: args.row,
+      localContent: args.localContent,
+    });
+  }
+  if (!args.allowUnsourcedCreate) return null;
+  return builderBodyChangeForUnsourcedLocalCreate({
+    localContent: args.localContent,
+  });
+}
+
 export function buildBuilderLocalOutboundChangeSets(args: {
   source: ContentDatabaseSourceRowDb;
   rowRows: ContentDatabaseSourceRecordRowDb[];
@@ -2078,6 +2552,8 @@ export function buildBuilderLocalOutboundChangeSets(args: {
     sourceFieldLabel: string;
     propertyType?: DocumentProperty["definition"]["type"] | null;
     propertyOptions?: DocumentPropertyOptions;
+    sourceFieldType?: string;
+    sourceFieldModel?: string;
   }>;
   // Row-union scoping (multi-source). Documents owned by ANOTHER source must
   // never be create candidates for this one — each row belongs to exactly one
@@ -2093,6 +2569,12 @@ export function buildBuilderLocalOutboundChangeSets(args: {
   taggedSourceByDocumentId?: Map<string, string>;
   bodyChangeByDocumentId?: Map<string, ContentDatabaseSourceBodyChange>;
   sourceImportedDocumentIds?: Set<string>;
+  /**
+   * Rejected change-sets that are provably cancellations of a prepared,
+   * pre-dispatch Builder gate. Their exact snapshot remains durable audit
+   * history and suppresses only the byte-equivalent local-vs-source diff.
+   */
+  cancelledRejectedChangeSetIds?: Set<string>;
 }): ContentDatabaseSourceChangeSet[] {
   if (normalizeSourceType(args.source.sourceType) !== "builder-cms") return [];
 
@@ -2103,6 +2585,106 @@ export function buildBuilderLocalOutboundChangeSets(args: {
     normalizeCapabilities(args.source.capabilitiesJson).liveWritesEnabled ===
       true;
   const pending: ContentDatabaseSourceChangeSet[] = [];
+
+  const sameCancelledSnapshot = (
+    candidate: Pick<
+      ContentDatabaseSourceChangeSet,
+      | "databaseItemId"
+      | "documentId"
+      | "kind"
+      | "direction"
+      | "pushMode"
+      | "fieldChanges"
+      | "bodyChange"
+    >,
+  ) =>
+    args.storedChangeSets.some(
+      (stored) =>
+        stored.state === "rejected" &&
+        args.cancelledRejectedChangeSetIds?.has(stored.id) === true &&
+        stored.databaseItemId === candidate.databaseItemId &&
+        stored.documentId === candidate.documentId &&
+        stored.kind === candidate.kind &&
+        stored.direction === candidate.direction &&
+        stored.pushMode === candidate.pushMode &&
+        stableValueString(stored.fieldChanges) ===
+          stableValueString(candidate.fieldChanges) &&
+        stableValueString(stored.bodyChange) ===
+          stableValueString(candidate.bodyChange),
+    );
+
+  const reviewableBuilderValue = (
+    field: NonNullable<typeof args.writableFields>[number],
+    localValue: unknown,
+  ): Pick<
+    ContentDatabaseSourceFieldChange,
+    "proposedValue" | "builderValueJson"
+  > => {
+    const type = field.propertyType;
+    const options = field.propertyOptions?.options ?? [];
+    const optionNameById = new Map(
+      options.map((option) => [option.id, option.name]),
+    );
+    const sourceType = field.sourceFieldType?.trim().toLowerCase();
+    if (sourceType === "reference") {
+      const id = typeof localValue === "string" ? localValue.trim() : "";
+      const label = optionNameById.get(id) ?? id;
+      const builderValue =
+        id && field.sourceFieldModel
+          ? {
+              "@type": "@builder.io/core:Reference",
+              id,
+              model: field.sourceFieldModel,
+            }
+          : null;
+      return {
+        proposedValue: label || null,
+        builderValueJson: JSON.stringify(builderValue),
+      };
+    }
+    if (sourceType === "file") {
+      const values = Array.isArray(localValue)
+        ? localValue.filter(
+            (value): value is string => typeof value === "string",
+          )
+        : typeof localValue === "string"
+          ? [localValue]
+          : [];
+      return {
+        proposedValue: values,
+        builderValueJson: JSON.stringify(
+          values.length === 1 ? values[0] : null,
+        ),
+      };
+    }
+    if (type === "multi_select" && Array.isArray(localValue)) {
+      const labels = localValue
+        .filter((value): value is string => typeof value === "string")
+        .map((value) => optionNameById.get(value) ?? value);
+      return {
+        proposedValue: labels,
+        builderValueJson: JSON.stringify(labels),
+      };
+    }
+    if (
+      (sourceType === "datetime" || sourceType === "date") &&
+      localValue &&
+      typeof localValue === "object" &&
+      !Array.isArray(localValue) &&
+      typeof (localValue as { start?: unknown }).start === "string"
+    ) {
+      return {
+        proposedValue: localValue as DocumentPropertyValue,
+        builderValueJson: JSON.stringify(
+          (localValue as { start: string }).start,
+        ),
+      };
+    }
+    return {
+      proposedValue: (localValue ?? null) as DocumentPropertyValue,
+      builderValueJson: JSON.stringify(localValue ?? null),
+    };
+  };
   for (const row of args.rowRows) {
     if (
       skipFixtureRows &&
@@ -2111,7 +2693,15 @@ export function buildBuilderLocalOutboundChangeSets(args: {
       continue;
     }
 
-    const sourceTitle = row.sourceDisplayKey.trim();
+    const rowSourceValues =
+      parseObject<Record<string, DocumentPropertyValue>>(
+        row.sourceValuesJson,
+      ) ?? {};
+    const sourceTitleValue = rowSourceValues["data.title"];
+    const sourceTitle =
+      typeof sourceTitleValue === "string" && sourceTitleValue.trim()
+        ? sourceTitleValue.trim()
+        : row.sourceDisplayKey.trim();
     const localTitle = args.documentTitleById.get(row.documentId)?.trim() ?? "";
     const fieldChanges: ContentDatabaseSourceFieldChange[] = [];
     if (localTitle && localTitle !== sourceTitle) {
@@ -2129,18 +2719,20 @@ export function buildBuilderLocalOutboundChangeSets(args: {
     // local value means "not loaded", not "cleared" — skip it.
     const rowLocalValues = args.localValuesByDocument?.get(row.documentId);
     if (rowLocalValues) {
-      const rowSourceValues =
-        parseObject<Record<string, DocumentPropertyValue>>(
-          row.sourceValuesJson,
-        ) ?? {};
       for (const field of args.writableFields ?? []) {
         if (!rowLocalValues.has(field.localFieldKey)) continue;
         const localValue = rowLocalValues.get(field.localFieldKey);
         const baseValue = rowSourceValues[field.sourceFieldKey];
+        const comparisonBaseValue =
+          field.sourceFieldType?.trim().toLowerCase() === "reference"
+            ? (rowSourceValues[
+                builderReferenceIdSourceValueKey(field.sourceFieldKey)
+              ] ?? baseValue)
+            : baseValue;
         if (
           sameMappedSourceFieldValue(
             localValue,
-            baseValue,
+            comparisonBaseValue,
             field.propertyType,
             field.propertyOptions,
           )
@@ -2159,7 +2751,7 @@ export function buildBuilderLocalOutboundChangeSets(args: {
                 field.propertyOptions,
               )
             : (baseValue ?? null)) as DocumentPropertyValue,
-          proposedValue: localValue as DocumentPropertyValue,
+          ...reviewableBuilderValue(field, localValue),
         });
       }
     }
@@ -2206,8 +2798,12 @@ export function buildBuilderLocalOutboundChangeSets(args: {
 
     const now = new Date().toISOString();
     const displayTitle = localTitle || sourceTitle;
-    pending.push({
-      id: `local-pending-${row.id}-${bodyChange ? "body" : "fields"}`,
+    const candidate: ContentDatabaseSourceChangeSet = {
+      // Keep the synthetic identity stable while body hydration catches up.
+      // The lightweight UI snapshot may initially see only field changes while
+      // the authoritative write snapshot also sees a body diff. The payload
+      // fingerprint, not an ID suffix, distinguishes material revisions.
+      id: `local-pending-${row.id}-change`,
       databaseItemId: row.databaseItemId,
       documentId: row.documentId,
       kind:
@@ -2234,7 +2830,8 @@ export function buildBuilderLocalOutboundChangeSets(args: {
       executions: [],
       createdAt: now,
       updatedAt: now,
-    });
+    };
+    if (!sameCancelledSnapshot(candidate)) pending.push(candidate);
   }
 
   // New-row creates: a local database item NOT linked to a Builder entry (no
@@ -2297,12 +2894,14 @@ export function buildBuilderLocalOutboundChangeSets(args: {
           localFieldKey: field.localFieldKey,
           sourceFieldKey: field.sourceFieldKey,
           currentValue: null,
-          proposedValue: (localValues.get(field.localFieldKey) ??
-            null) as DocumentPropertyValue,
+          ...reviewableBuilderValue(
+            field,
+            localValues.get(field.localFieldKey) ?? null,
+          ),
         });
       }
       const now = new Date().toISOString();
-      pending.push({
+      const candidate: ContentDatabaseSourceChangeSet = {
         id: `local-pending-create-${item.databaseItemId}`,
         databaseItemId: item.databaseItemId,
         documentId: item.documentId,
@@ -2323,7 +2922,8 @@ export function buildBuilderLocalOutboundChangeSets(args: {
         executions: [],
         createdAt: now,
         updatedAt: now,
-      });
+      };
+      if (!sameCancelledSnapshot(candidate)) pending.push(candidate);
     }
   }
 
@@ -2521,21 +3121,31 @@ async function readSourceSnapshotRowsOnce(args: {
       ...databaseItemRows.map((item) => item.documentId),
     ]),
   );
-  const rowDocuments =
+  const rowDocuments: Array<{
+    id: string;
+    title: string;
+    content?: string;
+  }> =
     allDocumentIds.length > 0
-      ? await db
-          .select({
-            id: schema.documents.id,
-            title: schema.documents.title,
-            content: schema.documents.content,
-          })
-          .from(schema.documents)
-          .where(
-            and(
-              inArray(schema.documents.id, allDocumentIds),
-              eq(schema.documents.ownerEmail, args.source.ownerEmail),
-            ),
-          )
+      ? args.includeHeavyBuilderBodyValues
+        ? await db
+            .select(sourceSnapshotDocumentSelection(true))
+            .from(schema.documents)
+            .where(
+              and(
+                inArray(schema.documents.id, allDocumentIds),
+                eq(schema.documents.ownerEmail, args.source.ownerEmail),
+              ),
+            )
+        : await db
+            .select(sourceSnapshotDocumentSelection(false))
+            .from(schema.documents)
+            .where(
+              and(
+                inArray(schema.documents.id, allDocumentIds),
+                eq(schema.documents.ownerEmail, args.source.ownerEmail),
+              ),
+            )
       : [];
   const propertyValueRows =
     args.isBuilderSource && allDocumentIds.length > 0
@@ -2687,13 +3297,19 @@ async function loadSourceSnapshot(
   const propertyOptionsById = new Map(
     propertyDefs.map((row) => [row.id, parsePropertyOptions(row.optionsJson)]),
   );
+  const builderModelFieldBySourceKey = new Map(
+    (
+      parseObject<SourceMetadataRecord>(source.metadataJson)
+        ?.builderModelFields ?? []
+    ).map((field) => [`data.${field.name.trim()}`, field]),
+  );
   const fields = fieldRows.map((row) =>
     serializeSourceField(
       row,
       row.propertyId ? (propertyNameById.get(row.propertyId) ?? null) : null,
     ),
   );
-  const storedChangeSets = changeRows.map(serializeSourceChangeSet);
+  let storedChangeSets = changeRows.map(serializeSourceChangeSet);
   const reviewEventsByChangeSetId = new Map<
     string,
     ContentDatabaseSourceReviewEvent[]
@@ -2765,6 +3381,9 @@ async function loadSourceSnapshot(
       propertyOptions: row.propertyId
         ? propertyOptionsById.get(row.propertyId)
         : undefined,
+      sourceFieldType: row.sourceFieldType,
+      sourceFieldModel: builderModelFieldBySourceKey.get(row.sourceFieldKey)
+        ?.model,
     }));
   // Row-union ownership scoping (Builder only). Determine which documents belong
   // to OTHER sources and whether this source is the primary (oldest), so the
@@ -2845,11 +3464,19 @@ async function loadSourceSnapshot(
     );
     await Promise.all(
       allDocumentIds.map(async (documentId) => {
-        if (!hydratedDocumentIds.has(documentId)) return;
         const row = sourceRowByDocumentId.get(documentId);
-        if (!row) return;
-        const bodyChange = await builderBodyChangeForLocalContent({
+        let bodyChange: ContentDatabaseSourceBodyChange | null = null;
+        // Only the primary source may adopt a genuinely local row with no source
+        // identity. Synthetic fixture rows already belong to this source, but
+        // still represent create_draft targets rather than imported baselines.
+        const allowUnsourcedCreate =
+          isPrimarySource &&
+          !otherSourceDocumentIds.has(documentId) &&
+          !taggedSourceByDocumentId.has(documentId);
+        bodyChange = await builderBodyChangeForSourceSnapshotDocument({
           row,
+          isHydrated: hydratedDocumentIds.has(documentId),
+          allowUnsourcedCreate,
           localContent: documentContentById.get(documentId),
         });
         if (bodyChange) bodyChangeByDocumentId.set(documentId, bodyChange);
@@ -2857,6 +3484,77 @@ async function loadSourceSnapshot(
     );
   }
 
+  // A locally blocked dry run never crossed the Builder dispatch boundary, so
+  // its approved body payload may be refreshed from the current document. This
+  // is deliberately narrower than ordinary "retryable" state: running,
+  // response-bearing, failed, reconciliatory, and otherwise ambiguous gates
+  // retain the exact body that was originally approved.
+  if (isBuilderSource && bodyChangeByDocumentId.size > 0) {
+    const executionRowsByChangeSetId = new Map<
+      string,
+      ContentDatabaseSourceExecutionRowDb[]
+    >();
+    for (const execution of executionRows) {
+      const rows = executionRowsByChangeSetId.get(execution.changeSetId) ?? [];
+      rows.push(execution);
+      executionRowsByChangeSetId.set(execution.changeSetId, rows);
+    }
+    storedChangeSets = storedChangeSets.map((changeSet) => {
+      // Rejected snapshots are durable review/audit evidence. In particular,
+      // a cancelled gate must retain the exact diff the user cancelled so a
+      // later local or remote body change can be distinguished from it.
+      if (changeSet.state !== "approved") return changeSet;
+      const currentBody = changeSet.documentId
+        ? bodyChangeByDocumentId.get(changeSet.documentId)
+        : null;
+      if (!currentBody) return changeSet;
+      const executions = executionRowsByChangeSetId.get(changeSet.id) ?? [];
+      if (!canRefreshLocallyBlockedBuilderReview(executions)) return changeSet;
+      return { ...changeSet, bodyChange: currentBody };
+    });
+  }
+
+  const cancellationReviewChangeSetIds = new Set(
+    reviewRows
+      .filter(
+        (review) =>
+          review.decision === "rejected" &&
+          review.stateTo === "rejected" &&
+          review.note?.startsWith(CANCELLED_BUILDER_REVIEW_NOTE_PREFIX),
+      )
+      .map((review) => review.changeSetId),
+  );
+  const executionRowsByChangeSetId = new Map<
+    string,
+    ContentDatabaseSourceExecutionRowDb[]
+  >();
+  for (const execution of executionRows) {
+    const rows = executionRowsByChangeSetId.get(execution.changeSetId) ?? [];
+    rows.push(execution);
+    executionRowsByChangeSetId.set(execution.changeSetId, rows);
+  }
+  const cancelledRejectedChangeSetIds = new Set(
+    storedChangeSets
+      .filter((changeSet) => {
+        if (
+          changeSet.state !== "rejected" ||
+          !cancellationReviewChangeSetIds.has(changeSet.id)
+        ) {
+          return false;
+        }
+        const executions = executionRowsByChangeSetId.get(changeSet.id) ?? [];
+        return (
+          executions.length > 0 &&
+          executions.every(
+            (execution) =>
+              execution.state === "blocked" &&
+              execution.summary === CANCELLED_BUILDER_EXECUTION_SUMMARY,
+          )
+        );
+      })
+      .map((changeSet) => changeSet.id),
+  );
+
   const localOutboundChangeSets = buildBuilderLocalOutboundChangeSets({
     source,
     rowRows,
@@ -2877,10 +3575,11 @@ async function loadSourceSnapshot(
         .filter((row) => row.provenance === "Builder CMS read adapter")
         .map((row) => row.documentId),
     ),
+    cancelledRejectedChangeSetIds,
   });
   const rowByDocumentId = new Map(rowRows.map((row) => [row.documentId, row]));
-  const changeSets = [...storedChangeSets, ...localOutboundChangeSets].map(
-    (changeSet) =>
+  const changeSets = [
+    ...storedChangeSets.map((changeSet) =>
       reviewedChangeSet({
         changeSet,
         source,
@@ -2888,7 +3587,20 @@ async function loadSourceSnapshot(
         reviewEvents: reviewEventsByChangeSetId.get(changeSet.id) ?? [],
         executions: executionsByChangeSetId.get(changeSet.id) ?? [],
       }),
-  );
+    ),
+    ...localOutboundChangeSets.map((changeSet) =>
+      reviewedChangeSet({
+        changeSet,
+        source,
+        rowByDocumentId,
+        // Synthetic current diffs deliberately reuse a stable identity. A
+        // closed stored revision with that ID is historical evidence, not the
+        // execution state of this new payload.
+        reviewEvents: [],
+        executions: [],
+      }),
+    ),
+  ];
   const metadata = parseObject<SourceMetadataRecord>(source.metadataJson) ?? {};
   const normalizedWriteMode =
     metadata.writeMode === "read_only" ||
@@ -2989,6 +3701,7 @@ async function loadSourceSnapshot(
             .map((mode) => normalizePushMode(mode))
             .filter((mode): mode is ContentDatabaseSourcePushMode => !!mode)
         : undefined,
+      builderModelFields: metadata.builderModelFields,
       federation: normalizeSourceFederation(metadata.federation),
     },
     fields,
@@ -3035,6 +3748,7 @@ async function sourceBodyHydrationSummary(args: {
     pending: 0,
     hydrating: 0,
     hydrated: 0,
+    unavailable: 0,
     error: 0,
     total: rows.length,
   };
@@ -3042,6 +3756,7 @@ async function sourceBodyHydrationSummary(args: {
     if (row.status === "pending" || (!row.status && row.queueId)) {
       summary.pending += 1;
     } else if (row.status === "hydrating") summary.hydrating += 1;
+    else if (row.status === "unavailable") summary.unavailable! += 1;
     else if (row.status === "error") summary.error += 1;
     else summary.hydrated += 1;
   }
@@ -3158,6 +3873,7 @@ export function serializeBuilderCmsSourceReadMetadataRecord(args: {
   );
   return JSON.stringify({
     ...builderCmsSourceMetadata(args.sourceTable),
+    ...existingMetadata,
     builderModelFields:
       args.builderModelFields ?? existingMetadata?.builderModelFields,
     readMode: args.readState === "live" ? "builder-api" : "fixture",
@@ -3259,6 +3975,41 @@ function normalizeBuilderCmsSourceFieldType(type: string) {
   return normalized || "text";
 }
 
+function isBuilderReferenceModelField(field: BuilderCmsModelFieldSummary) {
+  return [field.type, field.inputType]
+    .filter((value): value is string => typeof value === "string")
+    .some((value) => /\b(reference|relation)\b/i.test(value));
+}
+
+/**
+ * A raw Builder entry can teach required-field setup the reference model even
+ * when Builder's model endpoint omits it. Refreshes must not throw that
+ * provider-native enrichment away: the canonical local value is only an entry
+ * id, and dispatch needs the learned model to reconstruct a Builder reference.
+ */
+export function mergeBuilderCmsModelFieldsPreservingReferenceModels(args: {
+  existing?: BuilderCmsModelFieldSummary[];
+  refreshed?: BuilderCmsModelFieldSummary[];
+}) {
+  if (!args.refreshed || args.refreshed.length === 0) {
+    return args.existing ?? args.refreshed;
+  }
+  const existingByName = new Map(
+    (args.existing ?? []).map((field) => [field.name.trim(), field]),
+  );
+  return args.refreshed.map((field) => {
+    const existing = existingByName.get(field.name.trim());
+    if (
+      field.model?.trim() ||
+      !existing?.model?.trim() ||
+      !isBuilderReferenceModelField(field)
+    ) {
+      return field;
+    }
+    return { ...field, model: existing.model.trim() };
+  });
+}
+
 export async function seedMockSourceFields(args: {
   sourceId: string;
   ownerEmail: string;
@@ -3276,6 +4027,12 @@ export async function seedMockSourceFields(args: {
       .filter((field) => isBuilder && field.propertyId)
       .map((field) => [field.propertyId!, field]),
   );
+  const builderModelFieldBySourceKey = new Map(
+    (args.builderModelFields ?? []).map((field) => [
+      `data.${field.name.trim()}`,
+      field,
+    ]),
+  );
   const rows = [
     {
       id: crypto.randomUUID(),
@@ -3386,7 +4143,18 @@ export async function seedMockSourceFields(args: {
             ))
           : `fields.${slugifySourceField(property.definition.name)}`,
         sourceFieldLabel: property.definition.name,
-        sourceFieldType: property.definition.type,
+        sourceFieldType: isBuilder
+          ? normalizeBuilderCmsSourceFieldType(
+              builderModelFieldBySourceKey.get(
+                existingBuilderFieldByPropertyId.get(property.definition.id)
+                  ?.sourceFieldKey ??
+                  builderCmsSourceFieldKey(
+                    property.definition.id,
+                    property.definition.name,
+                  ),
+              )?.type ?? property.definition.type,
+            )
+          : property.definition.type,
         mappingType: "property",
         writeOwner:
           property.definition.type === "created_time" ||
@@ -3525,65 +4293,77 @@ export async function seedMockSourceRows(args: {
 }) {
   if (args.items.length === 0) return;
   const db = getDb();
-  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({
+  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,
-              existing: existingBuilderRow,
-              entry: builderEntry,
-            })
-          : null;
-      return {
-        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: builderIdentity
-          ? builderIdentity.sourceQualifiedId
-          : `${args.sourceType}://${args.sourceTable}/${item.document.id}`,
-        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,
-          }),
-        ),
-        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,
-      };
-    }),
-  );
+              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,
+        };
+      }),
+    )
+    .onConflictDoNothing();
 }
 
 export function sourceValuesForSeededSourceRow(args: {
@@ -3593,15 +4373,40 @@ export function sourceValuesForSeededSourceRow(args: {
   now: string;
   builderEntry?: BuilderCmsSourceEntry | null;
   existingSourceValuesJson?: string | null;
+  existingLastSourceUpdatedAt?: string | null;
 }): Record<string, DocumentPropertyValue> {
   const existingSourceValues = parseObject<
     Record<string, DocumentPropertyValue>
   >(args.existingSourceValuesJson);
   if (args.builderEntry?.sourceValues) {
-    return builderSourceValuesWithPreservedBodyBaseline({
+    const values = builderSourceValuesWithPreservedBodyBaseline({
       incoming: args.builderEntry.sourceValues,
       existing: existingSourceValues,
+      existingLastSourceUpdatedAt: args.existingLastSourceUpdatedAt,
     });
+    const rawData = args.builderEntry.rawEntry?.data;
+    if (rawData && typeof rawData === "object" && !Array.isArray(rawData)) {
+      for (const [name, rawValue] of Object.entries(rawData)) {
+        if (
+          !rawValue ||
+          typeof rawValue !== "object" ||
+          Array.isArray(rawValue)
+        )
+          continue;
+        const reference = rawValue as Record<string, unknown>;
+        if (
+          reference["@type"] !== "@builder.io/core:Reference" ||
+          typeof reference.id !== "string" ||
+          !reference.id.trim()
+        ) {
+          continue;
+        }
+        const sourceFieldKey = `data.${name}`;
+        values[builderReferenceIdSourceValueKey(sourceFieldKey)] =
+          reference.id.trim();
+      }
+    }
+    return values;
   }
   if (existingSourceValues) return existingSourceValues;
   if (args.sourceType !== "builder-cms") return {};
@@ -3615,6 +4420,7 @@ export function sourceValuesForSeededSourceRow(args: {
 function builderSourceValuesWithPreservedBodyBaseline(args: {
   incoming: Record<string, DocumentPropertyValue>;
   existing?: Record<string, DocumentPropertyValue> | null;
+  existingLastSourceUpdatedAt?: string | null;
 }) {
   const existing = args.existing;
   if (!existing) return args.incoming;
@@ -3634,24 +4440,66 @@ function builderSourceValuesWithPreservedBodyBaseline(args: {
     existing,
     BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
   );
-  if (
-    incomingContent?.trim() ||
-    !existingContent?.trim() ||
-    (incomingHash && existingHash && incomingHash !== existingHash)
-  ) {
-    return args.incoming;
-  }
-
+  const incomingLastUpdated =
+    stringSourceValue(args.incoming, "lastUpdated") ?? null;
+  const existingLastUpdated =
+    stringSourceValue(existing, BUILDER_CMS_BODY_LAST_UPDATED_KEY) ??
+    stringSourceValue(existing, "lastUpdated") ??
+    args.existingLastSourceUpdatedAt ??
+    null;
+  const incomingEpoch = builderTimestampEpoch(incomingLastUpdated);
+  const existingEpoch = builderTimestampEpoch(existingLastUpdated);
+  const sameRemoteVersion =
+    incomingEpoch !== null &&
+    existingEpoch !== null &&
+    incomingEpoch === existingEpoch;
   const next = { ...args.incoming };
-  for (const key of [
-    BUILDER_CMS_BODY_CONTENT_KEY,
-    BUILDER_CMS_BODY_LOSSLESS_CONTENT_KEY,
-    BUILDER_CMS_BODY_READABLE_MAP_KEY,
-    BUILDER_CMS_BODY_SIDECARS_KEY,
-    BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
-  ]) {
-    if (next[key] === undefined && existing[key] !== undefined) {
-      next[key] = existing[key];
+  const preserveExistingBody =
+    !incomingContent?.trim() &&
+    !!existingContent?.trim() &&
+    (sameRemoteVersion ||
+      !(incomingHash && existingHash && incomingHash !== existingHash));
+  if (preserveExistingBody) {
+    for (const key of [
+      BUILDER_CMS_BODY_CONTENT_KEY,
+      BUILDER_CMS_BODY_LOSSLESS_CONTENT_KEY,
+      BUILDER_CMS_BODY_READABLE_MAP_KEY,
+      BUILDER_CMS_BODY_SIDECARS_KEY,
+      BUILDER_CMS_BODY_BLOCKS_HASH_KEY,
+      BUILDER_CMS_BODY_LAST_UPDATED_KEY,
+    ]) {
+      if (existing[key] !== undefined) {
+        next[key] = existing[key];
+      }
+    }
+    if (
+      next[BUILDER_CMS_BODY_LAST_UPDATED_KEY] === undefined &&
+      args.existingLastSourceUpdatedAt
+    ) {
+      next[BUILDER_CMS_BODY_LAST_UPDATED_KEY] =
+        args.existingLastSourceUpdatedAt;
+    }
+  }
+  // Required-reference materialization stores the canonical Builder entry id
+  // beside the readable projection. Refresh receives only that projection, so
+  // retain the id while the projected value is unchanged. If the remote label
+  // changes, discard the old id instead of pairing stale identity with it.
+  const referenceIdPrefix = "__agent_native_builder_reference_id:";
+  for (const [key, value] of Object.entries(existing)) {
+    if (!key.startsWith(referenceIdPrefix)) continue;
+    const sourceFieldKey = key.slice(referenceIdPrefix.length);
+    if (
+      stableValueString(existing[sourceFieldKey]) ===
+      stableValueString(args.incoming[sourceFieldKey])
+    ) {
+      next[key] = value;
+    }
+  }
+  if (next[BUILDER_CMS_BODY_LAST_UPDATED_KEY] === undefined) {
+    const existingBaselineLastUpdated =
+      existing[BUILDER_CMS_BODY_LAST_UPDATED_KEY] ?? existing.lastUpdated;
+    if (existingBaselineLastUpdated !== undefined) {
+      next[BUILDER_CMS_BODY_LAST_UPDATED_KEY] = existingBaselineLastUpdated;
     }
   }
   return next;
@@ -4114,13 +4962,19 @@ export function mapBuilderCmsEntriesToLocalItems(args: {
       sourceTable: args.sourceTable,
       now: args.now,
     });
+    const exactIdentityMatch = existing
+      ? (entriesById.get(existing.sourceRowId) ??
+        entriesByQualifiedId.get(existing.sourceQualifiedId))
+      : null;
+    const allowNaturalKeyFallback =
+      !existing ||
+      builderCmsSourceRowIdentityState({ row: existing }).isSyntheticFixture;
     const match =
-      (existing
-        ? (entriesById.get(existing.sourceRowId) ??
-          entriesByQualifiedId.get(existing.sourceQualifiedId))
-        : null) ??
-      entriesByUrlPath.get(fixtureEntry.urlPath.toLowerCase()) ??
-      entriesByTitle.get(item.document.title.trim().toLowerCase());
+      exactIdentityMatch ??
+      (allowNaturalKeyFallback
+        ? (entriesByUrlPath.get(fixtureEntry.urlPath.toLowerCase()) ??
+          entriesByTitle.get(item.document.title.trim().toLowerCase()))
+        : null);
     if (match) entriesByDocumentId.set(item.document.id, match);
   }
 
@@ -4207,8 +5061,18 @@ export async function importBuilderCmsEntriesAsDatabaseItems(args: {
       eq(schema.documents.id, schema.contentDatabaseItems.documentId),
     )
     .where(eq(schema.contentDatabaseItems.databaseId, args.database.id));
-  const existingTitles = new Set(
-    currentItems.map((row) => row.document.title.trim().toLowerCase()),
+  const representedDocumentIds = new Set(
+    (args.existingSourceRows ?? [])
+      .map((row) => row.documentId)
+      .filter((documentId): documentId is string => Boolean(documentId)),
+  );
+  // Builder entry IDs, not titles, are the remote identity. Preserve every
+  // same-title entry in a collection while retaining the legacy guard against
+  // adopting an already-present local row during source replacement.
+  const existingUnlinkedTitles = new Set(
+    currentItems
+      .filter((row) => !representedDocumentIds.has(row.document.id))
+      .map((row) => row.document.title.trim().toLowerCase()),
   );
 
   // Reads MAX(position) for both `documents` and `content_database_items`
@@ -4257,11 +5121,24 @@ export async function importBuilderCmsEntriesAsDatabaseItems(args: {
 
             const title = entry.title.trim() || entry.id;
             const titleKey = title.toLowerCase();
-            if (!args.skipTitleDedup && existingTitles.has(titleKey)) continue;
-            existingTitles.add(titleKey);
+            if (!args.skipTitleDedup && existingUnlinkedTitles.has(titleKey)) {
+              continue;
+            }
 
-            const documentId = nanoid();
-            const itemId = nanoid();
+            const importIdentity = [
+              args.database.ownerEmail,
+              args.database.id,
+              args.sourceTable,
+              entry.id,
+            ];
+            const documentId = stableBuilderImportId(
+              "builder-doc",
+              importIdentity,
+            );
+            const itemId = stableBuilderImportId(
+              "builder-item",
+              importIdentity,
+            );
             documentRows.push({
               id: documentId,
               ownerEmail: args.database.ownerEmail,
@@ -4296,13 +5173,19 @@ export async function importBuilderCmsEntriesAsDatabaseItems(args: {
               documentRows,
               bulkChunkSizeForColumnCount(13),
             )) {
-              await tx.insert(schema.documents).values(chunk);
+              await tx
+                .insert(schema.documents)
+                .values(chunk)
+                .onConflictDoNothing();
             }
             for (const chunk of chunks(
               itemRows,
               bulkChunkSizeForColumnCount(10),
             )) {
-              await tx.insert(schema.contentDatabaseItems).values(chunk);
+              await tx
+                .insert(schema.contentDatabaseItems)
+                .values(chunk)
+                .onConflictDoNothing();
             }
           });
 
@@ -4346,6 +5229,10 @@ export async function resyncBuilderCmsSourceSnapshot(args: {
     builderModelFields = await readBuilderCmsModelFields({
       model: args.source.sourceTable,
     });
+    builderModelFields = mergeBuilderCmsModelFieldsPreservingReferenceModels({
+      existing: sourceMetadata.builderModelFields,
+      refreshed: builderModelFields,
+    });
   } catch (error) {
     builderModelFieldsReadFailed = true;
     const message = error instanceof Error ? error.message : String(error);