@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/contentSyncState.js

@@ -1,72 +1,389 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash, randomUUID } from 'crypto';
-function decodeTaskforceContextPath(value, normalizePath) {
-    const normalized = String(value || '').trim();
-    if (!normalized.startsWith('/api/taskforce/context/'))
+import { listReferencedAiProfileAvatarAssetPaths } from './aiProfileAvatarSyncPaths.js';
+import { normalizeCanonicalAssetKind } from '../utils/canonicalAssetKind.js';
+import { WorkspaceSyncContentVersionStore } from './engine/workspaceSyncContentVersionStore.js';
+import { WorkspaceSyncPublishedContentResolver, verifyWorkspaceSyncPublishedContentBody, } from './engine/workspaceSyncPublishedContentResolver.js';
+import { compareWorkspaceMutationOrdering } from './workspaceSyncSurface.js';
+import { publishWorkspaceSyncLocalFileAtomically, WorkspaceSyncAtomicLocalPublicationError, } from './engine/workspaceSyncAtomicLocalPublisher.js';
+const referencedAvatarFingerprintCache = new Map();
+const publishedContentResolverCache = new WeakMap();
+const localFileFingerprintCache = new Map();
+function fingerprintLocalFile(absolutePath) {
+    if (!fs.existsSync(absolutePath))
         return null;
-    const encoded = normalized.slice('/api/taskforce/context/'.length).split(/[?#]/, 1)[0] || '';
-    if (!encoded)
+    const stat = fs.statSync(absolutePath);
+    if (!stat.isFile())
         return null;
-    try {
-        return normalizePath(decodeURIComponent(encoded));
+    const cached = localFileFingerprintCache.get(absolutePath);
+    if (cached && cached.sizeBytes === stat.size && cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs) {
+        return { contentSha256: cached.contentSha256, sizeBytes: cached.sizeBytes };
     }
-    catch {
+    const content = fs.readFileSync(absolutePath);
+    const fingerprint = {
+        contentSha256: createHash('sha256').update(content).digest('hex'),
+        sizeBytes: content.length,
+        mtimeMs: stat.mtimeMs,
+        ctimeMs: stat.ctimeMs,
+    };
+    localFileFingerprintCache.set(absolutePath, fingerprint);
+    return { contentSha256: fingerprint.contentSha256, sizeBytes: fingerprint.sizeBytes };
+}
+function getPublishedContentResolver(deps) {
+    if (deps.publishedContentResolver)
+        return deps.publishedContentResolver;
+    const core = deps.core;
+    const cacheKey = core;
+    const cached = publishedContentResolverCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const resolver = new WorkspaceSyncPublishedContentResolver(new WorkspaceSyncContentVersionStore(core.getDatabaseAdapter()));
+    publishedContentResolverCache.set(cacheKey, resolver);
+    return resolver;
+}
+function resolvePublishedContent(deps, input) {
+    return getPublishedContentResolver(deps).resolve({
+        tenantId: deps.core.getTenantId(),
+        ...input,
+    });
+}
+function publishedContentIdentity(content) {
+    return content.source === 'versioned'
+        ? `version:${content.versionId}`
+        : `legacy:${content.storageProvider}:${content.physicalKey}`;
+}
+async function readPublishedContentBuffer(deps, basePath, content, label) {
+    let buffer = null;
+    let stat = null;
+    if (content.storageProvider === 'r2') {
+        const objectStorageClient = deps.getObjectStorageClient();
+        if (!objectStorageClient)
+            return null;
+        buffer = (await objectStorageClient.getObject(content.physicalKey))?.body || null;
+    }
+    else {
+        const root = path.resolve(basePath);
+        const absolutePath = path.resolve(root, content.physicalKey);
+        if (absolutePath === root || !absolutePath.startsWith(`${root}${path.sep}`))
+            return null;
+        if (!fs.existsSync(absolutePath))
+            return null;
+        stat = fs.statSync(absolutePath);
+        if (!stat.isFile())
+            return null;
+        buffer = fs.readFileSync(absolutePath);
+    }
+    if (!buffer)
         return null;
+    if (content.source === 'versioned') {
+        verifyWorkspaceSyncPublishedContentBody(buffer, content, label);
     }
+    return { buffer, stat };
 }
-function isAiProfileAvatarAssetPath(value, workspaceId) {
-    const normalized = String(value || '').replace(/\\/g, '/');
-    return normalized.startsWith(`workspaces/${workspaceId}/assets/images/ai-profiles/`)
-        && normalized.includes('/avatar/');
+async function readReferencedAvatarBuffer(deps, basePath, content, label) {
+    const primary = await readPublishedContentBuffer(deps, basePath, content, label);
+    if (primary?.buffer)
+        return primary.buffer;
+    if (content.source !== 'legacy' || content.storageProvider !== 'r2')
+        return null;
+    return (await readPublishedContentBuffer(deps, basePath, {
+        ...content,
+        storageProvider: 'local',
+    }, label))?.buffer || null;
 }
-function inferBinaryAssetMimeType(assetPath) {
-    const ext = path.extname(assetPath).toLowerCase();
-    if (ext === '.png')
-        return 'image/png';
-    if (ext === '.jpg' || ext === '.jpeg')
-        return 'image/jpeg';
-    if (ext === '.webp')
-        return 'image/webp';
-    if (ext === '.gif')
-        return 'image/gif';
-    return 'application/octet-stream';
+function publishedContentAvailable(basePath, content) {
+    if (content.storageProvider === 'r2') {
+        return {
+            contentSha256: content.source === 'versioned' ? content.contentSha256 : '',
+            sizeBytes: content.source === 'versioned' ? content.sizeBytes : 0,
+            contentAvailable: content.source === 'versioned',
+        };
+    }
+    const root = path.resolve(basePath);
+    const absolutePath = path.resolve(root, content.physicalKey);
+    if (absolutePath === root || !absolutePath.startsWith(`${root}${path.sep}`)) {
+        return { contentSha256: '', sizeBytes: 0, contentAvailable: false };
+    }
+    if (content.source === 'versioned') {
+        if (!fs.existsSync(absolutePath)) {
+            return { contentSha256: '', sizeBytes: 0, contentAvailable: false };
+        }
+        const stat = fs.statSync(absolutePath);
+        return stat.isFile() && stat.size === content.sizeBytes
+            ? {
+                contentSha256: content.contentSha256,
+                sizeBytes: content.sizeBytes,
+                contentAvailable: true,
+            }
+            : { contentSha256: '', sizeBytes: 0, contentAvailable: false };
+    }
+    const fingerprint = fingerprintLocalFile(absolutePath);
+    if (!fingerprint)
+        return { contentSha256: '', sizeBytes: 0, contentAvailable: false };
+    return {
+        contentSha256: fingerprint.contentSha256,
+        sizeBytes: fingerprint.sizeBytes,
+        contentAvailable: true,
+    };
 }
-function inferAssetIdFromPath(assetPath) {
-    const match = String(assetPath || '').match(/(^|\/)(asset-[a-f0-9]{32})(?=[^/]*$)/i);
-    return match?.[2];
+function compareWorkspaceSyncContentCursor(left, right) {
+    if (left.u !== right.u)
+        return left.u < right.u ? -1 : 1;
+    return Buffer.compare(Buffer.from(left.id, 'utf8'), Buffer.from(right.id, 'utf8'));
 }
-function listReferencedAiProfileAvatarAssetPaths(deps, workspaceId) {
-    const profiles = typeof deps.core.listAiProfiles === 'function'
-        ? deps.core.listAiProfiles(workspaceId, { includeArchived: true })
-        : [];
-    const referenced = new Map();
-    for (const profile of Array.isArray(profiles) ? profiles : []) {
-        const updatedAt = String(profile?.updatedAt || profile?.createdAt || '').trim();
-        for (const url of [profile?.avatarUrl, profile?.avatarSourceUrl]) {
-            const assetPath = decodeTaskforceContextPath(url, deps.normalizeTaskDataRelativePath);
-            if (!assetPath || !isAiProfileAvatarAssetPath(assetPath, workspaceId))
-                continue;
-            if (referenced.has(assetPath))
+export function readWorkspaceSyncContentFrontier(deps, workspaceId = 'default') {
+    if (!deps.workspaceAssetStore) {
+        const avatars = listReferencedAiProfileAvatarAssets(deps, workspaceId);
+        let avatarFrontier = null;
+        for (const [assetPath, metadata] of avatars) {
+            const candidate = { u: metadata.updatedAt, id: `asset:${assetPath}` };
+            if (Number.isFinite(Date.parse(candidate.u))
+                && (!avatarFrontier || compareWorkspaceSyncContentCursor(candidate, avatarFrontier) > 0))
+                avatarFrontier = candidate;
+        }
+        return avatarFrontier;
+    }
+    const assets = deps.workspaceAssetStore.listAllNormalizedByWorkspace(workspaceId, {
+        includeDeleted: true,
+    });
+    const linksByAssetId = groupWorkspaceAssetLinksByAssetId(deps.workspaceAssetStore, workspaceId);
+    const referencedAvatarAssets = listReferencedAiProfileAvatarAssets(deps, workspaceId);
+    const activeBinaryAssetPaths = new Set();
+    let frontier = null;
+    const include = (candidate) => {
+        if (Number.isFinite(Date.parse(candidate.u))
+            && candidate.id.length > 0
+            && (!frontier || compareWorkspaceSyncContentCursor(candidate, frontier) > 0))
+            frontier = candidate;
+    };
+    for (const asset of assets) {
+        const rawPath = String(asset.storageKey || '').trim();
+        const isDocument = asset.kind === 'document';
+        const normalizedPath = isDocument
+            ? deps.normalizeWorkspaceSyncDocumentPath(rawPath)
+            : deps.normalizeTaskDataRelativePath(rawPath);
+        if (!normalizedPath)
+            continue;
+        const isReplicatedBinaryAsset = (asset.kind === 'image' || asset.kind === 'file')
+            && asset.storageProvider !== 'external';
+        if (!isDocument && !isReplicatedBinaryAsset)
+            continue;
+        if (asset.deletedAt) {
+            if (!isDocument && referencedAvatarAssets.has(normalizedPath))
                 continue;
-            referenced.set(assetPath, {
-                updatedAt,
-                assetId: inferAssetIdFromPath(assetPath),
-                originalFilename: path.basename(assetPath),
-                mimeType: inferBinaryAssetMimeType(assetPath)
+            include({
+                u: String(asset.deletedAt).trim(),
+                id: `${isDocument ? 'doc-delete' : 'asset-delete'}:${normalizedPath}:${String(asset.assetId || '').trim()}`,
             });
+            continue;
         }
+        const { effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkStateFromLinks(asset, linksByAssetId.get(asset.assetId) || []);
+        include({
+            u: effectiveUpdatedAt,
+            id: `${isDocument ? 'doc' : 'asset'}:${isDocument ? normalizedPath : rawPath}`,
+        });
+        if (!isDocument)
+            activeBinaryAssetPaths.add(rawPath);
     }
-    return referenced;
+    for (const [assetPath, metadata] of referencedAvatarAssets) {
+        if (activeBinaryAssetPaths.has(assetPath))
+            continue;
+        include({ u: metadata.updatedAt, id: `asset:${assetPath}` });
+    }
+    return frontier;
+}
+export function hasWorkspaceSyncContentAfter(deps, workspaceId, cursor) {
+    if (!cursor)
+        return true;
+    const db = deps.core.getDatabaseAdapter();
+    const tenantId = deps.core.getTenantId();
+    const threshold = cursor.u;
+    const rows = db.prepare(`
+        SELECT
+            asset.asset_id,
+            asset.kind,
+            asset.storage_provider,
+            asset.storage_key,
+            asset.original_filename,
+            asset.mime_type,
+            asset.deleted_at,
+            CASE
+                WHEN asset.deleted_at IS NOT NULL THEN asset.deleted_at
+                WHEN COALESCE((
+                    SELECT MAX(CASE
+                        WHEN link.updated_at > link.created_at THEN link.updated_at
+                        ELSE link.created_at
+                    END)
+                    FROM workspace_asset_links link
+                    WHERE link.tenant_id = asset.tenant_id
+                      AND link.workspace_id = asset.workspace_id
+                      AND link.asset_id = asset.asset_id
+                ), '') > COALESCE(asset.updated_at, asset.created_at, '')
+                THEN (
+                    SELECT MAX(CASE
+                        WHEN link.updated_at > link.created_at THEN link.updated_at
+                        ELSE link.created_at
+                    END)
+                    FROM workspace_asset_links link
+                    WHERE link.tenant_id = asset.tenant_id
+                      AND link.workspace_id = asset.workspace_id
+                      AND link.asset_id = asset.asset_id
+                )
+                ELSE COALESCE(asset.updated_at, asset.created_at, '')
+            END AS effective_updated_at
+        FROM workspace_assets asset
+        WHERE asset.tenant_id = ?
+          AND asset.workspace_id = ?
+          AND (
+              asset.kind = 'document'
+              OR (
+                  asset.kind IN ('image', 'file')
+                  AND asset.storage_provider <> 'external'
+              )
+          )
+          AND (
+              COALESCE(asset.deleted_at, asset.updated_at, asset.created_at, '') >= ?
+              OR EXISTS (
+                  SELECT 1
+                  FROM workspace_asset_links changed_link
+                  WHERE changed_link.tenant_id = asset.tenant_id
+                    AND changed_link.workspace_id = asset.workspace_id
+                    AND changed_link.asset_id = asset.asset_id
+                    AND (
+                        changed_link.updated_at >= ?
+                        OR changed_link.created_at >= ?
+                    )
+              )
+          )
+    `).all(tenantId, workspaceId, threshold, threshold, threshold);
+    const referencedAvatarAssets = listReferencedAiProfileAvatarAssets(deps, workspaceId);
+    const isAfter = (candidate) => (Number.isFinite(Date.parse(candidate.u))
+        && compareWorkspaceSyncContentCursor(candidate, cursor) > 0);
+    for (const row of rows) {
+        const kind = normalizeCanonicalAssetKind({
+            kind: String(row.kind || 'file'),
+            storageKey: String(row.storage_key || ''),
+            originalFilename: String(row.original_filename || ''),
+            mimeType: String(row.mime_type || ''),
+        });
+        const isDocument = kind === 'document';
+        const normalizedPath = isDocument
+            ? deps.normalizeWorkspaceSyncDocumentPath(row.storage_key)
+            : deps.normalizeTaskDataRelativePath(String(row.storage_key || ''));
+        if (!normalizedPath)
+            continue;
+        const rawPath = String(row.storage_key || '').trim();
+        const deletedAt = String(row.deleted_at || '').trim();
+        if (deletedAt && !isDocument && referencedAvatarAssets.has(normalizedPath))
+            continue;
+        if (isAfter({
+            u: deletedAt || String(row.effective_updated_at || '').trim(),
+            id: deletedAt
+                ? `${isDocument ? 'doc-delete' : 'asset-delete'}:${normalizedPath}:${String(row.asset_id || '').trim()}`
+                : `${isDocument ? 'doc' : 'asset'}:${isDocument ? normalizedPath : rawPath}`,
+        }))
+            return true;
+    }
+    const headRows = db.prepare(`
+        SELECT
+            head.kind,
+            head.logical_path,
+            head.source_updated_at,
+            asset.kind AS asset_kind,
+            asset.storage_provider,
+            asset.original_filename,
+            asset.mime_type
+        FROM workspace_sync_content_heads head
+        INNER JOIN workspace_assets asset
+            ON asset.tenant_id = head.tenant_id
+           AND asset.workspace_id = head.workspace_id
+           AND asset.storage_key = head.logical_path
+        WHERE head.tenant_id = ?
+          AND head.workspace_id = ?
+          AND head.deleted_at IS NULL
+          AND asset.deleted_at IS NULL
+          AND head.source_updated_at >= ?
+    `).all(tenantId, workspaceId, threshold);
+    for (const row of headRows) {
+        const normalizedKind = normalizeCanonicalAssetKind({
+            kind: String(row.asset_kind || 'file'),
+            storageKey: String(row.logical_path || ''),
+            originalFilename: String(row.original_filename || ''),
+            mimeType: String(row.mime_type || ''),
+        });
+        const isDocument = normalizedKind === 'document';
+        if (String(row.kind || '') !== (isDocument ? 'document' : 'asset')
+            || (!isDocument && String(row.storage_provider || '') === 'external'))
+            continue;
+        const normalizedPath = isDocument
+            ? deps.normalizeWorkspaceSyncDocumentPath(row.logical_path)
+            : deps.normalizeTaskDataRelativePath(String(row.logical_path || ''));
+        if (normalizedPath && isAfter({
+            u: String(row.source_updated_at || '').trim(),
+            id: `${isDocument ? 'doc' : 'asset'}:${isDocument ? normalizedPath : String(row.logical_path || '').trim()}`,
+        }))
+            return true;
+    }
+    for (const [assetPath, metadata] of referencedAvatarAssets) {
+        const canonicalAsset = deps.workspaceAssetStore?.getByStorageKey(assetPath, workspaceId);
+        if (canonicalAsset
+            && !canonicalAsset.deletedAt
+            && (canonicalAsset.kind === 'image' || canonicalAsset.kind === 'file')
+            && canonicalAsset.storageProvider !== 'external')
+            continue;
+        if (isAfter({ u: metadata.updatedAt, id: `asset:${assetPath}` }))
+            return true;
+    }
+    return false;
+}
+function runWorkspaceSyncContentMetadataMutation(deps, input, apply) {
+    return deps.core.getDatabaseAdapter().transaction(() => {
+        new WorkspaceSyncContentVersionStore(deps.core.getDatabaseAdapter()).lockLogicalHead({
+            tenantId: deps.core.getTenantId(),
+            workspaceId: input.workspaceId,
+            kind: input.kind,
+            logicalPath: input.logicalPath,
+        }, input.updatedAt);
+        return apply();
+    })();
+}
+function newestDocumentMetadata(watermark, asset) {
+    if (!watermark) {
+        return asset
+            ? { updatedAt: asset.updatedAt, contentHash: asset.contentSha256 }
+            : null;
+    }
+    if (!asset)
+        return watermark;
+    return compareWorkspaceMutationOrdering(asset.updatedAt, watermark.updatedAt, asset.contentSha256, watermark.contentHash) >= 0
+        ? { updatedAt: asset.updatedAt, contentHash: asset.contentSha256 }
+        : watermark;
+}
+function hasPublishedWorkspaceSyncContentHead(deps, input) {
+    return Boolean(new WorkspaceSyncContentVersionStore(deps.core.getDatabaseAdapter()).getHead({
+        tenantId: deps.core.getTenantId(),
+        ...input,
+    }));
+}
+function listReferencedAiProfileAvatarAssets(deps, workspaceId) {
+    const profiles = typeof deps.core.listAiProfiles === 'function'
+        ? deps.core.listAiProfiles(workspaceId, { includeArchived: true })
+        : [];
+    return listReferencedAiProfileAvatarAssetPaths(profiles, workspaceId, deps.normalizeTaskDataRelativePath);
 }
 export function resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId) {
     if (!deps.workspaceAssetStore) {
         return {
             primaryLink: null,
+            activeLinks: [],
             effectiveUpdatedAt: String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString()
         };
     }
     const links = deps.workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId, { includeDeleted: true });
+    return resolveCanonicalAssetSyncLinkStateFromLinks(asset, links);
+}
+function resolveCanonicalAssetSyncLinkStateFromLinks(asset, links) {
     const activeLinks = links.filter((entry) => !entry.deletedAt);
     const primaryLink = activeLinks[0] || null;
     let effectiveUpdatedAt = String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString();
@@ -75,7 +392,25 @@ export function resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId) {
         if (linkUpdatedAt && linkUpdatedAt > effectiveUpdatedAt)
             effectiveUpdatedAt = linkUpdatedAt;
     }
-    return { primaryLink, effectiveUpdatedAt };
+    return { primaryLink, activeLinks, effectiveUpdatedAt };
+}
+function groupWorkspaceAssetLinksByAssetId(store, workspaceId) {
+    const grouped = new Map();
+    for (const link of store.listLinksForWorkspace(workspaceId, { includeDeleted: true })) {
+        const current = grouped.get(link.assetId) || [];
+        current.push(link);
+        grouped.set(link.assetId, current);
+    }
+    return grouped;
+}
+function toSyncLinkPayloads(links) {
+    return links.map((link) => ({
+        targetType: link.targetType,
+        targetId: link.targetId,
+        role: link.role,
+        displayName: link.displayName,
+        updatedAt: link.updatedAt,
+    }));
 }
 function resolveSyncLinkTarget(primaryLink) {
     if (!primaryLink)
@@ -105,7 +440,10 @@ export function getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId
     const asset = deps.workspaceAssetStore.getByStorageKey(relativePath, workspaceId);
     if (!asset || asset.kind !== 'document')
         return {};
-    const { primaryLink } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+    const { primaryLink, activeLinks } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+    return getCanonicalSyncDocumentMetadataFromState(asset, primaryLink, activeLinks, relativePath);
+}
+function getCanonicalSyncDocumentMetadataFromState(asset, primaryLink, activeLinks, relativePath) {
     const linkTarget = resolveSyncLinkTarget(primaryLink);
     return {
         assetId: asset.assetId,
@@ -118,15 +456,19 @@ export function getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId
         logicalName: asset.logicalName || null,
         caption: primaryLink?.displayName || null,
         originalFilename: asset.originalFilename || path.basename(relativePath),
-        linkRole: primaryLink?.role === 'reference' ? 'reference' : 'attachment'
+        linkRole: primaryLink?.role === 'reference' ? 'reference' : 'attachment',
+        links: toSyncLinkPayloads(activeLinks),
     };
 }
 export function hasDocumentSyncMetadataDrift(deps, workspaceId, doc) {
     if (!deps.workspaceAssetStore)
         return false;
     const existingAsset = deps.workspaceAssetStore.getByStorageKey(doc.path, workspaceId);
+    const incomingAssetId = typeof doc.assetId === 'string' ? doc.assetId.trim() : '';
     if (!existingAsset || existingAsset.kind !== 'document')
-        return false;
+        return Boolean(incomingAssetId);
+    if (incomingAssetId && existingAsset.assetId !== incomingAssetId)
+        return true;
     const { primaryLink } = resolveCanonicalAssetSyncLinkState(deps, existingAsset, workspaceId);
     const normalizedIncomingReference = Number.isFinite(Number(doc.referenceNumber))
         ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
@@ -166,8 +508,11 @@ export function hasBinaryAssetSyncMetadataDrift(deps, workspaceId, asset) {
     if (!deps.workspaceAssetStore)
         return false;
     const existingAsset = deps.workspaceAssetStore.getByStorageKey(asset.path, workspaceId);
+    const incomingAssetId = typeof asset.assetId === 'string' ? asset.assetId.trim() : '';
     if (!existingAsset || (existingAsset.kind !== 'image' && existingAsset.kind !== 'file'))
-        return false;
+        return Boolean(incomingAssetId);
+    if (incomingAssetId && existingAsset.assetId !== incomingAssetId)
+        return true;
     const { primaryLink } = resolveCanonicalAssetSyncLinkState(deps, existingAsset, workspaceId);
     const normalizedIncomingReference = Number.isFinite(Number(asset.referenceNumber))
         ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
@@ -218,8 +563,43 @@ export function reconcileWorkspaceSyncLinks(deps, input) {
             : 'attachment';
     const linkUpdatedAt = String(input.updatedAt || '').trim() || new Date().toISOString();
     const existingLinks = deps.workspaceAssetStore.listLinksForAsset(assetId, workspaceId, { includeDeleted: true });
+    if (Array.isArray(input.links)) {
+        const desiredLinkKeys = new Set();
+        for (const link of input.links) {
+            const targetId = String(link.targetId || '').trim();
+            if (!targetId)
+                continue;
+            const key = `${link.targetType}:${targetId}:${link.role}`;
+            desiredLinkKeys.add(key);
+            deps.workspaceAssetStore.upsertLegacySyncLink({
+                workspaceId,
+                assetId,
+                targetType: link.targetType,
+                targetId,
+                role: link.role,
+                displayName: typeof link.displayName === 'string' && link.displayName.trim() ? link.displayName.trim() : null,
+                updatedAt: String(link.updatedAt || '').trim() || linkUpdatedAt,
+                deletedAt: null,
+            });
+        }
+        for (const link of existingLinks) {
+            if (link.deletedAt)
+                continue;
+            const key = `${link.targetType}:${link.targetId}:${link.role}`;
+            if (desiredLinkKeys.has(key))
+                continue;
+            deps.workspaceAssetStore.deleteLegacySyncLink({
+                workspaceId,
+                assetId,
+                targetType: link.targetType,
+                targetId: link.targetId,
+                role: link.role,
+            });
+        }
+        return;
+    }
     if (desiredLinkTarget) {
-        deps.workspaceAssetStore.upsertLink({
+        deps.workspaceAssetStore.upsertLegacySyncLink({
             workspaceId,
             assetId,
             targetType: desiredLinkTarget.targetType,
@@ -239,7 +619,7 @@ export function reconcileWorkspaceSyncLinks(deps, input) {
             }
             if (link.deletedAt)
                 continue;
-            deps.workspaceAssetStore.deleteLink({
+            deps.workspaceAssetStore.deleteLegacySyncLink({
                 workspaceId,
                 assetId,
                 targetType: link.targetType,
@@ -298,25 +678,23 @@ export async function listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspa
             let stat = null;
             let content = null;
             let updatedAt = '';
+            let contentIdentity = `legacy:local:${relativePath}`;
             if (canonicalAsset?.kind === 'document') {
                 updatedAt = resolveCanonicalAssetSyncLinkState(deps, canonicalAsset, workspaceId).effectiveUpdatedAt;
-                if (canonicalAsset.storageProvider === 'r2' && objectStorageClient) {
-                    const object = await objectStorageClient.getObject(relativePath);
-                    if (!object?.body)
-                        continue;
-                    content = object.body.toString('utf8');
-                }
-                else {
-                    const absPath = path.resolve(path.join(root, relativePath));
-                    if (absPath !== root && !absPath.startsWith(`${root}${path.sep}`))
-                        continue;
-                    if (!fs.existsSync(absPath))
-                        continue;
-                    stat = fs.statSync(absPath);
-                    if (!stat.isFile())
-                        continue;
-                    content = fs.readFileSync(absPath, 'utf8');
-                }
+                const published = resolvePublishedContent(deps, {
+                    workspaceId,
+                    kind: 'document',
+                    logicalPath: relativePath,
+                    legacyProvider: canonicalAsset.storageProvider === 'r2' ? 'r2' : 'local',
+                });
+                if (published.source === 'deleted')
+                    continue;
+                contentIdentity = publishedContentIdentity(published);
+                const read = await readPublishedContentBuffer(deps, root, published, `Workspace sync document ${relativePath}`);
+                if (!read)
+                    continue;
+                stat = read.stat;
+                content = read.buffer.toString('utf8');
             }
             else {
                 const absPath = path.resolve(path.join(basePath, relativePath));
@@ -332,6 +710,7 @@ export async function listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspa
                 continue;
             const cached = workspaceCache.get(relativePath);
             if (cached
+                && cached.contentIdentity === contentIdentity
                 && cached.size === Buffer.byteLength(content, 'utf8')
                 && (canonicalAsset
                     ? cached.updatedAt === updatedAt
@@ -374,6 +753,7 @@ export async function listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspa
             });
             workspaceCache.set(relativePath, {
                 path: relativePath,
+                contentIdentity,
                 mtimeMs: stat?.mtimeMs ?? 0,
                 ctimeMs: stat?.ctimeMs ?? 0,
                 size: Buffer.byteLength(content, 'utf8'),
@@ -396,15 +776,22 @@ export async function listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspa
     return docs;
 }
 export async function listWorkspaceSyncDocumentIndex(deps, basePath, workspaceId = 'default') {
+    const canonicalAssetByRawPath = new Map();
     const candidatePaths = new Set();
+    const linksByAssetId = deps.workspaceAssetStore
+        ? groupWorkspaceAssetLinksByAssetId(deps.workspaceAssetStore, workspaceId)
+        : new Map();
     // Keep the document index aligned with the snapshot invariant above: only
     // canonical workspace document assets may participate in shared document sync.
     if (deps.workspaceAssetStore) {
-        const canonicalAssets = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
+        const canonicalAssets = deps.workspaceAssetStore.listAllNormalizedByWorkspace(workspaceId, {
             includeDeleted: false,
             kind: 'document'
         });
         for (const asset of canonicalAssets) {
+            if (!canonicalAssetByRawPath.has(asset.storageKey)) {
+                canonicalAssetByRawPath.set(asset.storageKey, asset);
+            }
             const normalized = deps.normalizeWorkspaceSyncDocumentPath(asset.storageKey);
             if (normalized)
                 candidatePaths.add(normalized);
@@ -413,10 +800,34 @@ export async function listWorkspaceSyncDocumentIndex(deps, basePath, workspaceId
     const docs = [];
     for (const relativePath of Array.from(candidatePaths).sort((a, b) => a.localeCompare(b))) {
         try {
-            const canonicalAsset = deps.workspaceAssetStore?.getByStorageKey(relativePath, workspaceId);
+            const canonicalAsset = canonicalAssetByRawPath.get(relativePath);
             let updatedAt = '';
+            let contentSha256 = '';
+            let sizeBytes = 0;
+            let contentAvailable = false;
+            const linkState = canonicalAsset?.kind === 'document'
+                ? resolveCanonicalAssetSyncLinkStateFromLinks(canonicalAsset, linksByAssetId.get(canonicalAsset.assetId) || [])
+                : null;
             if (canonicalAsset?.kind === 'document') {
-                updatedAt = resolveCanonicalAssetSyncLinkState(deps, canonicalAsset, workspaceId).effectiveUpdatedAt;
+                updatedAt = linkState.effectiveUpdatedAt;
+                const published = resolvePublishedContent(deps, {
+                    workspaceId,
+                    kind: 'document',
+                    logicalPath: relativePath,
+                    legacyProvider: canonicalAsset.storageProvider === 'r2' ? 'r2' : 'local',
+                });
+                if (published.source === 'deleted')
+                    continue;
+                const availability = publishedContentAvailable(basePath, published);
+                contentSha256 = availability.contentSha256
+                    || String(canonicalAsset.contentSha256 || '').trim().toLowerCase();
+                sizeBytes = availability.contentAvailable
+                    ? availability.sizeBytes
+                    : Math.max(0, Math.floor(Number(canonicalAsset.sizeBytes || 0)));
+                contentAvailable = availability.contentAvailable
+                    || (published.source === 'legacy'
+                        && published.storageProvider === 'r2'
+                        && contentSha256.length === 64);
             }
             else {
                 const absPath = path.resolve(path.join(basePath, relativePath));
@@ -431,13 +842,21 @@ export async function listWorkspaceSyncDocumentIndex(deps, basePath, workspaceId
                 const existing = deps.core.getDocumentWatermark(workspaceId, relativePath);
                 updatedAt = existing?.updatedAt
                     || (Number.isFinite(stat.mtimeMs) ? new Date(stat.mtimeMs).toISOString() : new Date().toISOString());
+                contentSha256 = String(existing?.contentHash || '').trim().toLowerCase();
+                sizeBytes = stat.size;
+                contentAvailable = true;
             }
             if (!Number.isFinite(Date.parse(String(updatedAt || '').trim())))
                 continue;
             docs.push({
                 path: relativePath,
                 updatedAt: String(updatedAt || '').trim(),
-                ...getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId)
+                contentSha256,
+                sizeBytes,
+                contentAvailable,
+                ...(canonicalAsset?.kind === 'document' && linkState
+                    ? getCanonicalSyncDocumentMetadataFromState(canonicalAsset, linkState.primaryLink, linkState.activeLinks, relativePath)
+                    : {})
             });
         }
         catch (error) {
@@ -470,35 +889,26 @@ export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, work
             continue;
         emittedPaths.add(storageKey);
         try {
-            let buffer = null;
-            if (asset.storageProvider === 'r2' && objectStorageClient) {
-                const object = await objectStorageClient.getObject(storageKey);
-                buffer = object?.body || null;
-            }
-            else {
-                const absolutePath = path.resolve(root, storageKey);
-                if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`))
-                    continue;
-                if (!fs.existsSync(absolutePath)) {
-                    deps.recordSyncDiagnostic(workspaceId, 'push', 'Asset registered in DB but file missing from disk — skipped from sync payload.', {
-                        source: 'assets.snapshot.missingFile',
-                        assetId: asset.assetId,
-                        path: storageKey
-                    });
-                    continue;
-                }
-                buffer = fs.readFileSync(absolutePath);
-            }
+            const published = resolvePublishedContent(deps, {
+                workspaceId,
+                kind: 'asset',
+                logicalPath: storageKey,
+                legacyProvider: asset.storageProvider === 'r2' ? 'r2' : 'local',
+            });
+            if (published.source === 'deleted')
+                continue;
+            const read = await readPublishedContentBuffer(deps, root, published, `Workspace sync binary asset ${storageKey}`);
+            const buffer = read?.buffer || null;
             if (!buffer) {
                 deps.recordSyncDiagnostic(workspaceId, 'push', 'Asset registered in DB but content could not be read — skipped from sync payload.', {
                     source: 'assets.snapshot.emptyBuffer',
                     assetId: asset.assetId,
                     path: storageKey,
-                    storageProvider: asset.storageProvider
+                    storageProvider: published.storageProvider
                 });
                 continue;
             }
-            const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+            const { primaryLink, activeLinks, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
             const linkTarget = resolveSyncLinkTarget(primaryLink);
             snapshots.push({
                 path: storageKey,
@@ -514,7 +924,8 @@ export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, work
                 logicalName: asset.logicalName || null,
                 caption: primaryLink?.displayName || null,
                 originalFilename: asset.originalFilename || path.basename(storageKey),
-                linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment')
+                linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment'),
+                links: toSyncLinkPayloads(activeLinks),
             });
         }
         catch (error) {
@@ -525,7 +936,7 @@ export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, work
             });
         }
     }
-    const referencedAiAvatarAssets = listReferencedAiProfileAvatarAssetPaths(deps, workspaceId);
+    const referencedAiAvatarAssets = listReferencedAiProfileAvatarAssets(deps, workspaceId);
     for (const [assetPath, metadata] of referencedAiAvatarAssets.entries()) {
         if (emittedPaths.has(assetPath))
             continue;
@@ -533,14 +944,15 @@ export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, work
         if (absolutePath === root || !absolutePath.startsWith(`${root}${path.sep}`))
             continue;
         try {
-            let buffer = null;
-            if (objectStorageClient) {
-                const object = await objectStorageClient.getObject(assetPath);
-                buffer = object?.body || null;
-            }
-            else if (fs.existsSync(absolutePath)) {
-                buffer = fs.readFileSync(absolutePath);
-            }
+            const published = resolvePublishedContent(deps, {
+                workspaceId,
+                kind: 'asset',
+                logicalPath: assetPath,
+                legacyProvider: objectStorageClient ? 'r2' : 'local',
+            });
+            if (published.source === 'deleted')
+                continue;
+            const buffer = await readReferencedAvatarBuffer(deps, root, published, `Workspace sync AI profile avatar ${assetPath}`);
             if (!buffer)
                 continue;
             snapshots.push({
@@ -571,10 +983,13 @@ export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, work
     return snapshots;
 }
 export async function listWorkspaceSyncBinaryAssetIndex(deps, workspaceId = 'default') {
-    const assets = deps.workspaceAssetStore?.listAllByWorkspace(workspaceId, {
+    const assets = deps.workspaceAssetStore?.listAllNormalizedByWorkspace(workspaceId, {
         includeDeleted: false
     }) || [];
-    const indexed = assets
+    const linksByAssetId = deps.workspaceAssetStore
+        ? groupWorkspaceAssetLinksByAssetId(deps.workspaceAssetStore, workspaceId)
+        : new Map();
+    const indexCandidates = assets
         .filter((asset) => asset.kind === 'image' || asset.kind === 'file')
         .filter((asset) => asset.storageProvider !== 'external')
         .filter((asset) => {
@@ -583,10 +998,11 @@ export async function listWorkspaceSyncBinaryAssetIndex(deps, workspaceId = 'def
     })
         .map((asset) => {
         const storageKey = String(asset.storageKey || '').trim();
-        const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+        const { primaryLink, activeLinks, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkStateFromLinks(asset, linksByAssetId.get(asset.assetId) || []);
         const linkTarget = resolveSyncLinkTarget(primaryLink);
         const assetKind = asset.kind === 'image' ? 'image' : 'file';
         return {
+            asset,
             path: storageKey,
             updatedAt: effectiveUpdatedAt,
             assetId: asset.assetId,
@@ -599,16 +1015,114 @@ export async function listWorkspaceSyncBinaryAssetIndex(deps, workspaceId = 'def
             logicalName: asset.logicalName || null,
             caption: primaryLink?.displayName || null,
             originalFilename: asset.originalFilename || path.basename(storageKey),
-            linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment')
+            linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment'),
+            links: toSyncLinkPayloads(activeLinks),
         };
     })
         .filter((entry) => Number.isFinite(Date.parse(entry.updatedAt)) && entry.path.length > 0);
+    const indexed = [];
+    for (const candidate of indexCandidates) {
+        try {
+            const published = resolvePublishedContent(deps, {
+                workspaceId,
+                kind: 'asset',
+                logicalPath: candidate.path,
+                legacyProvider: candidate.asset.storageProvider === 'r2' ? 'r2' : 'local',
+            });
+            if (published.source === 'deleted')
+                continue;
+            const availability = publishedContentAvailable(deps.core.getPaths().basePath, published);
+            const { asset: _asset, ...entry } = candidate;
+            indexed.push({
+                ...entry,
+                contentSha256: availability.contentSha256
+                    || String(candidate.asset.contentSha256 || '').trim().toLowerCase(),
+                sizeBytes: availability.contentAvailable
+                    ? availability.sizeBytes
+                    : Math.max(0, Math.floor(Number(candidate.asset.sizeBytes || 0))),
+                contentAvailable: availability.contentAvailable
+                    || (published.source === 'legacy'
+                        && published.storageProvider === 'r2'
+                        && String(candidate.asset.contentSha256 || '').trim().length === 64),
+            });
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to index binary asset snapshot entry.', {
+                source: 'assets.snapshot.indexEntry',
+                path: candidate.path,
+                assetId: candidate.asset.assetId,
+                error: String(error?.message || error || '')
+            });
+        }
+    }
     const indexedPaths = new Set(indexed.map((entry) => entry.path));
-    for (const [assetPath, metadata] of listReferencedAiProfileAvatarAssetPaths(deps, workspaceId).entries()) {
+    for (const [assetPath, metadata] of listReferencedAiProfileAvatarAssets(deps, workspaceId).entries()) {
         if (indexedPaths.has(assetPath))
             continue;
         if (!Number.isFinite(Date.parse(metadata.updatedAt)))
             continue;
+        const fingerprintCacheKey = `${workspaceId}:${assetPath}`;
+        let published;
+        try {
+            published = resolvePublishedContent(deps, {
+                workspaceId,
+                kind: 'asset',
+                logicalPath: assetPath,
+                legacyProvider: deps.getObjectStorageClient() ? 'r2' : 'local',
+            });
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to resolve referenced AI profile avatar.', {
+                source: 'assets.index.aiProfileAvatar.resolve',
+                path: assetPath,
+                error: String(error?.message || error || '')
+            });
+            continue;
+        }
+        if (published.source === 'deleted')
+            continue;
+        const contentIdentity = publishedContentIdentity(published);
+        let fingerprint = referencedAvatarFingerprintCache.get(fingerprintCacheKey);
+        if (!fingerprint
+            || fingerprint.updatedAt !== metadata.updatedAt
+            || fingerprint.contentIdentity !== contentIdentity) {
+            if (published.source === 'versioned') {
+                const availability = publishedContentAvailable(deps.core.getPaths().basePath, published);
+                fingerprint = availability.contentAvailable
+                    ? {
+                        updatedAt: metadata.updatedAt,
+                        contentIdentity,
+                        contentSha256: availability.contentSha256,
+                        sizeBytes: availability.sizeBytes,
+                    }
+                    : undefined;
+            }
+            else {
+                let content = null;
+                try {
+                    content = await readReferencedAvatarBuffer(deps, deps.core.getPaths().basePath, published, `Workspace sync AI profile avatar index ${assetPath}`);
+                }
+                catch (error) {
+                    deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to fingerprint referenced AI profile avatar.', {
+                        source: 'assets.index.aiProfileAvatar',
+                        path: assetPath,
+                        error: String(error?.message || error || '')
+                    });
+                }
+                fingerprint = content
+                    ? {
+                        updatedAt: metadata.updatedAt,
+                        contentIdentity,
+                        contentSha256: createHash('sha256').update(content).digest('hex'),
+                        sizeBytes: content.length,
+                    }
+                    : undefined;
+            }
+            if (fingerprint)
+                referencedAvatarFingerprintCache.set(fingerprintCacheKey, fingerprint);
+            else
+                referencedAvatarFingerprintCache.delete(fingerprintCacheKey);
+        }
         indexed.push({
             path: assetPath,
             updatedAt: metadata.updatedAt,
@@ -622,7 +1136,10 @@ export async function listWorkspaceSyncBinaryAssetIndex(deps, workspaceId = 'def
             logicalName: null,
             caption: null,
             originalFilename: metadata.originalFilename,
-            linkRole: 'image'
+            linkRole: 'image',
+            contentSha256: fingerprint?.contentSha256 || '',
+            sizeBytes: fingerprint?.sizeBytes || 0,
+            contentAvailable: Boolean(fingerprint)
         });
     }
     return indexed;
@@ -635,16 +1152,26 @@ export async function loadWorkspaceSyncDocumentPayload(deps, basePath, workspace
     const absolutePath = path.resolve(path.join(root, normalizedPath));
     if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`))
         return null;
-    const objectStorageClient = deps.getObjectStorageClient();
     const canonicalAsset = deps.workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId);
     let content = '';
     let stat = null;
+    let contentIdentity = `legacy:local:${normalizedPath}`;
     try {
-        if (canonicalAsset?.kind === 'document' && canonicalAsset.storageProvider === 'r2' && objectStorageClient) {
-            const object = await objectStorageClient.getObject(normalizedPath);
-            if (!object?.body)
+        if (canonicalAsset?.kind === 'document') {
+            const published = resolvePublishedContent(deps, {
+                workspaceId,
+                kind: 'document',
+                logicalPath: normalizedPath,
+                legacyProvider: canonicalAsset.storageProvider === 'r2' ? 'r2' : 'local',
+            });
+            if (published.source === 'deleted')
+                return null;
+            contentIdentity = publishedContentIdentity(published);
+            const read = await readPublishedContentBuffer(deps, root, published, `Targeted workspace sync document ${normalizedPath}`);
+            if (!read)
                 return null;
-            content = object.body.toString('utf8');
+            content = read.buffer.toString('utf8');
+            stat = read.stat;
         }
         else {
             if (!fs.existsSync(absolutePath))
@@ -697,11 +1224,11 @@ export async function loadWorkspaceSyncDocumentPayload(deps, basePath, workspace
         }
     }
     if (cached
-        && stat
+        && cached.contentIdentity === contentIdentity
         && cached.size === Buffer.byteLength(content, 'utf8')
         && (canonicalAsset
             ? cached.updatedAt === updatedAt
-            : cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs)) {
+            : stat != null && cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs)) {
         return {
             path: normalizedPath,
             updatedAt: cached.updatedAt,
@@ -711,6 +1238,7 @@ export async function loadWorkspaceSyncDocumentPayload(deps, basePath, workspace
     }
     workspaceCache.set(normalizedPath, {
         path: normalizedPath,
+        contentIdentity,
         mtimeMs: stat?.mtimeMs ?? 0,
         ctimeMs: stat?.ctimeMs ?? 0,
         size: Buffer.byteLength(content, 'utf8'),
@@ -730,7 +1258,7 @@ export async function loadWorkspaceSyncBinaryAssetPayload(deps, basePath, worksp
         return null;
     const asset = deps.workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId) || null;
     const referencedAiAvatar = !asset
-        ? listReferencedAiProfileAvatarAssetPaths(deps, workspaceId).get(normalizedPath) || null
+        ? listReferencedAiProfileAvatarAssets(deps, workspaceId).get(normalizedPath) || null
         : null;
     if (!referencedAiAvatar
         && (!asset || (asset.kind !== 'image' && asset.kind !== 'file') || asset.storageProvider === 'external')) {
@@ -739,26 +1267,19 @@ export async function loadWorkspaceSyncBinaryAssetPayload(deps, basePath, worksp
     const objectStorageClient = deps.getObjectStorageClient();
     let buffer = null;
     try {
-        if ((asset?.storageProvider === 'r2' || referencedAiAvatar) && objectStorageClient) {
-            const object = await objectStorageClient.getObject(normalizedPath);
-            buffer = object?.body || null;
-        }
-        else {
-            const root = path.resolve(basePath);
-            const absolutePath = path.resolve(root, normalizedPath);
-            if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`))
-                return null;
-            if (!fs.existsSync(absolutePath))
-                return null;
-            buffer = fs.readFileSync(absolutePath);
-        }
-        if (!buffer && referencedAiAvatar && objectStorageClient) {
-            const root = path.resolve(basePath);
-            const absolutePath = path.resolve(root, normalizedPath);
-            if (absolutePath !== root && absolutePath.startsWith(`${root}${path.sep}`) && fs.existsSync(absolutePath)) {
-                buffer = fs.readFileSync(absolutePath);
-            }
-        }
+        const published = resolvePublishedContent(deps, {
+            workspaceId,
+            kind: 'asset',
+            logicalPath: normalizedPath,
+            legacyProvider: asset
+                ? (asset.storageProvider === 'r2' ? 'r2' : 'local')
+                : (objectStorageClient ? 'r2' : 'local'),
+        });
+        if (published.source === 'deleted')
+            return null;
+        buffer = referencedAiAvatar && !asset
+            ? await readReferencedAvatarBuffer(deps, basePath, published, `Targeted workspace sync binary asset ${normalizedPath}`)
+            : (await readPublishedContentBuffer(deps, basePath, published, `Targeted workspace sync binary asset ${normalizedPath}`))?.buffer || null;
     }
     catch (error) {
         deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to load targeted binary asset payload.', {
@@ -791,7 +1312,7 @@ export async function loadWorkspaceSyncBinaryAssetPayload(deps, basePath, worksp
     }
     if (!asset)
         return null;
-    const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+    const { primaryLink, activeLinks, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
     const linkTarget = resolveSyncLinkTarget(primaryLink);
     const assetKind = asset.kind === 'image' ? 'image' : 'file';
     return {
@@ -808,12 +1329,14 @@ export async function loadWorkspaceSyncBinaryAssetPayload(deps, basePath, worksp
         logicalName: asset.logicalName || null,
         caption: primaryLink?.displayName || null,
         originalFilename: asset.originalFilename || path.basename(normalizedPath),
-        linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment')
+        linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment'),
+        links: toSyncLinkPayloads(activeLinks),
     };
 }
 export function listWorkspaceSyncBinaryAssetDeletesSnapshot(deps, workspaceId = 'default') {
     if (!deps.workspaceAssetStore)
         return [];
+    const referencedAiAvatarAssets = listReferencedAiProfileAvatarAssets(deps, workspaceId);
     const entries = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
         includeDeleted: true
     })
@@ -825,6 +1348,8 @@ export function listWorkspaceSyncBinaryAssetDeletesSnapshot(deps, workspaceId =
         const normalizedPath = deps.normalizeTaskDataRelativePath(asset.storageKey);
         if (!normalizedPath)
             return null;
+        if (referencedAiAvatarAssets.has(normalizedPath))
+            return null;
         return {
             path: normalizedPath,
             deletedAt: String(asset.deletedAt || '').trim(),
@@ -833,71 +1358,159 @@ export function listWorkspaceSyncBinaryAssetDeletesSnapshot(deps, workspaceId =
     });
     return entries.filter((entry) => Boolean(entry && entry.path && entry.deletedAt));
 }
-export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceId = 'default', options) {
-    const normalizedPath = deps.normalizeWorkspaceSyncDocumentPath(doc.path);
-    if (!normalizedPath)
-        return;
-    const root = path.resolve(basePath);
-    const targetPath = path.resolve(root, normalizedPath);
-    if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
-        return;
-    const objectStorageClient = deps.getObjectStorageClient();
-    const content = String(doc.content || '');
-    if (objectStorageClient) {
-        try {
-            await objectStorageClient.putObject(normalizedPath, Buffer.from(content, 'utf8'), 'text/markdown');
-        }
-        catch (error) {
-            deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to write document to object storage.', {
-                source: 'documents.write.putObject',
-                path: normalizedPath,
-                error: String(error?.message || error || '')
-            });
-            return;
-        }
-    }
-    else {
-        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-        fs.writeFileSync(targetPath, content, 'utf8');
-    }
+export function persistWorkspaceSyncDocumentMetadata(deps, input) {
+    const { document: doc, normalizedPath, contentSha256, sizeBytes, storageProvider, workspaceId = 'default', options, } = input;
     const updatedAt = String(doc.updatedAt || '').trim();
-    const watermarkMs = Date.parse(updatedAt);
-    if (!objectStorageClient && Number.isFinite(watermarkMs) && watermarkMs > 0) {
-        const when = new Date(watermarkMs);
-        fs.utimesSync(targetPath, when, when);
+    const mutationUpdatedAt = updatedAt || new Date().toISOString();
+    try {
+        runWorkspaceSyncContentMetadataMutation(deps, {
+            workspaceId,
+            kind: 'document',
+            logicalPath: normalizedPath,
+            updatedAt: mutationUpdatedAt,
+        }, () => {
+            const current = newestDocumentMetadata(deps.core.getDocumentWatermark(workspaceId, normalizedPath), deps.workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId) || null);
+            if ((options?.strictOrdering === true
+                || hasPublishedWorkspaceSyncContentHead(deps, {
+                    workspaceId,
+                    kind: 'document',
+                    logicalPath: normalizedPath,
+                }))
+                &&
+                    current
+                && compareWorkspaceMutationOrdering(mutationUpdatedAt, current.updatedAt, contentSha256, current.contentHash) < 0)
+                return;
+            const persistWatermark = options?.strictWatermark === true
+                ? deps.core.upsertDocumentWatermarkStrict.bind(deps.core)
+                : deps.core.upsertDocumentWatermark.bind(deps.core);
+            persistWatermark(workspaceId, normalizedPath, contentSha256, mutationUpdatedAt);
+            if (deps.workspaceAssetStore) {
+                const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+                const effectiveUpdatedAt = mutationUpdatedAt;
+                const incomingReferenceNumber = Number.isFinite(Number(doc.referenceNumber))
+                    ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
+                    : null;
+                const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
+                const nextReferenceNumber = allowReferenceNumberReassignment
+                    ? (incomingReferenceNumber ?? existing?.referenceNumber ?? null)
+                    : (existing?.referenceNumber ?? incomingReferenceNumber ?? null);
+                const originalFilename = String(doc.originalFilename
+                    || existing?.originalFilename
+                    || path.basename(normalizedPath)
+                    || 'document.md').trim() || 'document.md';
+                const upsertedAsset = deps.workspaceAssetStore.upsertAsset({
+                    assetId: String(doc.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
+                    workspaceId,
+                    kind: 'document',
+                    logicalName: typeof doc.logicalName === 'string' && doc.logicalName.trim().length > 0
+                        ? doc.logicalName.trim()
+                        : existing?.logicalName || null,
+                    originalFilename,
+                    mimeType: existing?.mimeType || 'text/markdown',
+                    storageProvider,
+                    storageKey: normalizedPath,
+                    contentSha256,
+                    sizeBytes,
+                    documentId: String(doc.documentId || existing?.documentId || `doc-${randomUUID().replace(/-/g, '')}`),
+                    referenceNumber: nextReferenceNumber,
+                    version: Number.isFinite(Number(doc.version))
+                        ? Math.max(1, Math.floor(Number(doc.version)))
+                        : Math.max(1, Number(existing?.version || 0) + 1),
+                    isLatest: true,
+                    scanStatus: existing?.scanStatus || 'clean',
+                    scanEngine: existing?.scanEngine || null,
+                    scanDetails: existing?.scanDetails || null,
+                    createdByUserId: existing?.createdByUserId || null,
+                    createdAt: existing?.createdAt || effectiveUpdatedAt,
+                    updatedAt: effectiveUpdatedAt,
+                    deletedAt: null,
+                    purgeAfter: null,
+                    allowReferenceNumberReassignment
+                });
+                const asset = allowReferenceNumberReassignment && incomingReferenceNumber
+                    ? deps.workspaceAssetStore.adoptReadableReferenceNumber(workspaceId, upsertedAsset.assetId, incomingReferenceNumber)
+                    : upsertedAsset;
+                const linkTarget = resolveIncomingSyncLinkTarget(doc);
+                reconcileWorkspaceSyncLinks(deps, {
+                    workspaceId,
+                    assetId: asset.assetId,
+                    taskId: linkTarget?.targetType === 'task' ? linkTarget.targetId : null,
+                    linkTargetType: linkTarget?.targetType || null,
+                    linkTargetId: linkTarget?.targetId || null,
+                    displayName: typeof doc.caption === 'string' && doc.caption.trim().length > 0
+                        ? doc.caption.trim()
+                        : null,
+                    role: doc.linkRole === 'reference' ? 'reference' : 'attachment',
+                    updatedAt: effectiveUpdatedAt,
+                    links: doc.links,
+                });
+            }
+        });
+    }
+    catch (error) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist document watermark after write.', {
+            source: 'documents.write.upsertWatermark',
+            path: normalizedPath,
+            error: String(error?.message || error || '')
+        });
+        throw error;
     }
+    deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+}
+export function persistWorkspaceSyncBinaryAssetMetadata(deps, input) {
+    if (!deps.workspaceAssetStore)
+        return;
+    const workspaceAssetStore = deps.workspaceAssetStore;
+    const { asset, normalizedPath, contentSha256, sizeBytes, storageProvider, workspaceId = 'default', options, } = input;
+    const updatedAt = String(asset.updatedAt || '').trim();
+    const mutationUpdatedAt = updatedAt || new Date().toISOString();
     try {
-        const contentHash = createHash('sha256').update(content).digest('hex');
-        deps.core.upsertDocumentWatermark(workspaceId, normalizedPath, contentHash, updatedAt || new Date().toISOString());
-        if (deps.workspaceAssetStore) {
-            const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-            const effectiveUpdatedAt = updatedAt || new Date().toISOString();
-            const incomingReferenceNumber = Number.isFinite(Number(doc.referenceNumber))
-                ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
+        runWorkspaceSyncContentMetadataMutation(deps, {
+            workspaceId,
+            kind: 'asset',
+            logicalPath: normalizedPath,
+            updatedAt: mutationUpdatedAt,
+        }, () => {
+            const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+            if ((options?.strictOrdering === true
+                || hasPublishedWorkspaceSyncContentHead(deps, {
+                    workspaceId,
+                    kind: 'asset',
+                    logicalPath: normalizedPath,
+                }))
+                &&
+                    existing
+                && compareWorkspaceMutationOrdering(mutationUpdatedAt, existing.updatedAt, contentSha256, existing.contentSha256) < 0)
+                return;
+            const effectiveUpdatedAt = mutationUpdatedAt;
+            const incomingReferenceNumber = Number.isFinite(Number(asset.referenceNumber))
+                ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
                 : null;
             const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
             const nextReferenceNumber = allowReferenceNumberReassignment
                 ? (incomingReferenceNumber ?? existing?.referenceNumber ?? null)
                 : (existing?.referenceNumber ?? incomingReferenceNumber ?? null);
-            const originalFilename = String(doc.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'document.md').trim() || 'document.md';
-            const asset = deps.workspaceAssetStore.upsertAsset({
-                assetId: String(doc.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
+            const upsertedAssetRecord = workspaceAssetStore.upsertAsset({
+                assetId: String(asset.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
                 workspaceId,
-                kind: 'document',
-                logicalName: typeof doc.logicalName === 'string' && doc.logicalName.trim().length > 0
-                    ? doc.logicalName.trim()
+                kind: asset.kind === 'image' ? 'image' : 'file',
+                logicalName: typeof asset.logicalName === 'string' && asset.logicalName.trim().length > 0
+                    ? asset.logicalName.trim()
                     : existing?.logicalName || null,
-                originalFilename,
-                mimeType: existing?.mimeType || 'text/markdown',
-                storageProvider: objectStorageClient ? 'r2' : 'local',
+                originalFilename: String(asset.originalFilename
+                    || existing?.originalFilename
+                    || path.basename(normalizedPath)
+                    || 'asset').trim() || 'asset',
+                mimeType: String(asset.mimeType
+                    || existing?.mimeType
+                    || 'application/octet-stream').trim() || 'application/octet-stream',
+                storageProvider,
                 storageKey: normalizedPath,
-                contentSha256: contentHash,
-                sizeBytes: Buffer.byteLength(content, 'utf8'),
-                documentId: String(doc.documentId || existing?.documentId || `doc-${randomUUID().replace(/-/g, '')}`),
+                contentSha256,
+                sizeBytes,
+                documentId: null,
                 referenceNumber: nextReferenceNumber,
-                version: Number.isFinite(Number(doc.version))
-                    ? Math.max(1, Math.floor(Number(doc.version)))
-                    : Math.max(1, Number(existing?.version || 0) + 1),
+                version: null,
                 isLatest: true,
                 scanStatus: existing?.scanStatus || 'clean',
                 scanEngine: existing?.scanEngine || null,
@@ -909,27 +1522,106 @@ export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceI
                 purgeAfter: null,
                 allowReferenceNumberReassignment
             });
-            const linkTarget = resolveIncomingSyncLinkTarget(doc);
+            const assetRecord = allowReferenceNumberReassignment && incomingReferenceNumber
+                ? workspaceAssetStore.adoptReadableReferenceNumber(workspaceId, upsertedAssetRecord.assetId, incomingReferenceNumber)
+                : upsertedAssetRecord;
+            const linkTarget = resolveIncomingSyncLinkTarget(asset);
             reconcileWorkspaceSyncLinks(deps, {
                 workspaceId,
-                assetId: asset.assetId,
+                assetId: assetRecord.assetId,
                 taskId: linkTarget?.targetType === 'task' ? linkTarget.targetId : null,
                 linkTargetType: linkTarget?.targetType || null,
                 linkTargetId: linkTarget?.targetId || null,
-                displayName: typeof doc.caption === 'string' && doc.caption.trim().length > 0 ? doc.caption.trim() : null,
-                role: doc.linkRole === 'reference' ? 'reference' : 'attachment',
-                updatedAt: effectiveUpdatedAt
+                displayName: typeof asset.caption === 'string' && asset.caption.trim().length > 0
+                    ? asset.caption.trim()
+                    : null,
+                role: asset.linkRole === 'reference'
+                    ? 'reference'
+                    : asset.kind === 'image'
+                        ? 'image'
+                        : 'attachment',
+                updatedAt: effectiveUpdatedAt,
+                links: asset.links,
             });
-        }
+        });
     }
     catch (error) {
-        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist document watermark after write.', {
-            source: 'documents.write.upsertWatermark',
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist binary asset metadata after write.', {
+            source: 'assets.write.upsertAsset',
             path: normalizedPath,
+            assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
+            kind: asset.kind,
             error: String(error?.message || error || '')
         });
+        throw error;
     }
-    deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+}
+export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceId = 'default', options) {
+    const normalizedPath = deps.normalizeWorkspaceSyncDocumentPath(doc.path);
+    if (!normalizedPath)
+        return;
+    const root = path.resolve(basePath);
+    const targetPath = path.resolve(root, normalizedPath);
+    if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+        return;
+    const objectStorageClient = deps.getObjectStorageClient();
+    const content = String(doc.content || '');
+    const contentBuffer = Buffer.from(content, 'utf8');
+    const contentSha256 = createHash('sha256').update(contentBuffer).digest('hex');
+    const sizeBytes = contentBuffer.byteLength;
+    const updatedAt = String(doc.updatedAt || '').trim();
+    const watermarkMs = Date.parse(updatedAt);
+    if (objectStorageClient) {
+        try {
+            await objectStorageClient.putObject(normalizedPath, contentBuffer, 'text/markdown');
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to write document to object storage.', {
+                source: 'documents.write.putObject',
+                path: normalizedPath,
+                error: String(error?.message || error || '')
+            });
+            throw error;
+        }
+    }
+    else {
+        try {
+            publishWorkspaceSyncLocalFileAtomically({
+                targetPath,
+                body: contentBuffer,
+                expectedSha256: contentSha256,
+                expectedSizeBytes: sizeBytes,
+                sourceUpdatedAt: Number.isFinite(watermarkMs) && watermarkMs > 0
+                    ? new Date(watermarkMs)
+                    : null,
+            });
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to publish document atomically.', {
+                source: 'documents.write.atomicLocal',
+                path: normalizedPath,
+                error: String(error?.message || error || ''),
+                ...(error instanceof WorkspaceSyncAtomicLocalPublicationError
+                    ? {
+                        code: error.code,
+                        boundary: error.boundary,
+                        published: error.published,
+                    }
+                    : {}),
+            });
+            throw error;
+        }
+    }
+    const { content: _content, ...document } = doc;
+    persistWorkspaceSyncDocumentMetadata(deps, {
+        document,
+        normalizedPath,
+        contentSha256,
+        sizeBytes,
+        storageProvider: objectStorageClient ? 'r2' : 'local',
+        workspaceId,
+        options,
+    });
 }
 export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, workspaceId = 'default', options) {
     const normalizedPath = deps.normalizeTaskDataRelativePath(asset.path);
@@ -941,6 +1633,10 @@ export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, works
         return;
     const objectStorageClient = deps.getObjectStorageClient();
     const buffer = Buffer.from(String(asset.contentBase64 || ''), 'base64');
+    const contentSha256 = createHash('sha256').update(buffer).digest('hex');
+    const sizeBytes = buffer.byteLength;
+    const updatedAt = String(asset.updatedAt || '').trim();
+    const watermarkMs = Date.parse(updatedAt);
     if (objectStorageClient) {
         try {
             await objectStorageClient.putObject(normalizedPath, buffer, String(asset.mimeType || 'application/octet-stream').trim() || 'application/octet-stream');
@@ -951,84 +1647,121 @@ export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, works
                 path: normalizedPath,
                 error: String(error?.message || error || '')
             });
-            return;
+            throw error;
         }
     }
     else {
-        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-        fs.writeFileSync(targetPath, buffer);
-    }
-    const updatedAt = String(asset.updatedAt || '').trim();
-    const watermarkMs = Date.parse(updatedAt);
-    if (!objectStorageClient && Number.isFinite(watermarkMs) && watermarkMs > 0) {
-        const when = new Date(watermarkMs);
-        fs.utimesSync(targetPath, when, when);
+        try {
+            publishWorkspaceSyncLocalFileAtomically({
+                targetPath,
+                body: buffer,
+                expectedSha256: contentSha256,
+                expectedSizeBytes: sizeBytes,
+                sourceUpdatedAt: Number.isFinite(watermarkMs) && watermarkMs > 0
+                    ? new Date(watermarkMs)
+                    : null,
+            });
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to publish binary asset atomically.', {
+                source: 'assets.write.atomicLocal',
+                path: normalizedPath,
+                error: String(error?.message || error || ''),
+                ...(error instanceof WorkspaceSyncAtomicLocalPublicationError
+                    ? {
+                        code: error.code,
+                        boundary: error.boundary,
+                        published: error.published,
+                    }
+                    : {}),
+            });
+            throw error;
+        }
     }
-    if (!deps.workspaceAssetStore)
-        return;
-    try {
-        const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-        const effectiveUpdatedAt = updatedAt || new Date().toISOString();
-        const incomingReferenceNumber = Number.isFinite(Number(asset.referenceNumber))
-            ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
-            : null;
-        const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
-        const nextReferenceNumber = allowReferenceNumberReassignment
-            ? (incomingReferenceNumber ?? existing?.referenceNumber ?? null)
-            : (existing?.referenceNumber ?? incomingReferenceNumber ?? null);
-        const assetRecord = deps.workspaceAssetStore.upsertAsset({
-            assetId: String(asset.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
-            workspaceId,
-            kind: asset.kind === 'image' ? 'image' : 'file',
-            logicalName: typeof asset.logicalName === 'string' && asset.logicalName.trim().length > 0
-                ? asset.logicalName.trim()
-                : existing?.logicalName || null,
-            originalFilename: String(asset.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'asset').trim() || 'asset',
-            mimeType: String(asset.mimeType || existing?.mimeType || 'application/octet-stream').trim() || 'application/octet-stream',
-            storageProvider: objectStorageClient ? 'r2' : 'local',
-            storageKey: normalizedPath,
-            contentSha256: createHash('sha256').update(buffer).digest('hex'),
-            sizeBytes: buffer.length,
-            documentId: null,
-            referenceNumber: nextReferenceNumber,
-            version: null,
-            isLatest: true,
-            scanStatus: existing?.scanStatus || 'clean',
-            scanEngine: existing?.scanEngine || null,
-            scanDetails: existing?.scanDetails || null,
-            createdByUserId: existing?.createdByUserId || null,
-            createdAt: existing?.createdAt || effectiveUpdatedAt,
-            updatedAt: effectiveUpdatedAt,
-            deletedAt: null,
-            purgeAfter: null,
-            allowReferenceNumberReassignment
-        });
-        const linkTarget = resolveIncomingSyncLinkTarget(asset);
-        reconcileWorkspaceSyncLinks(deps, {
-            workspaceId,
-            assetId: assetRecord.assetId,
-            taskId: linkTarget?.targetType === 'task' ? linkTarget.targetId : null,
-            linkTargetType: linkTarget?.targetType || null,
-            linkTargetId: linkTarget?.targetId || null,
-            displayName: typeof asset.caption === 'string' && asset.caption.trim().length > 0 ? asset.caption.trim() : null,
-            role: asset.linkRole === 'reference' ? 'reference' : asset.kind === 'image' ? 'image' : 'attachment',
-            updatedAt: effectiveUpdatedAt
+    const { contentBase64: _contentBase64, ...bodylessAsset } = asset;
+    persistWorkspaceSyncBinaryAssetMetadata(deps, {
+        asset: bodylessAsset,
+        normalizedPath,
+        contentSha256,
+        sizeBytes,
+        storageProvider: objectStorageClient ? 'r2' : 'local',
+        workspaceId,
+        options,
+    });
+}
+function beginWorkspaceSyncBinaryAssetMetadataDeletion(deps, input) {
+    const { normalizedPath, deletedAt, workspaceId = 'default', } = input;
+    if (!canDeleteWorkspaceSyncBinaryAssetMetadata(deps, normalizedPath, workspaceId)) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Skipped deleting a referenced AI profile avatar asset.', {
+            source: 'assets.delete.aiProfileAvatarReference',
+            path: normalizedPath
         });
+        return null;
     }
-    catch (error) {
-        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist binary asset metadata after write.', {
-            source: 'assets.write.upsertAsset',
-            path: normalizedPath,
-            assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
-            kind: asset.kind,
-            error: String(error?.message || error || '')
+    return () => {
+        runWorkspaceSyncContentMetadataMutation(deps, {
+            workspaceId,
+            kind: 'asset',
+            logicalPath: normalizedPath,
+            updatedAt: deletedAt,
+        }, () => {
+            if (!canDeleteWorkspaceSyncBinaryAssetMetadata(deps, normalizedPath, workspaceId))
+                return;
+            const existingCanonicalAsset = deps.workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId) || null;
+            if (!deps.workspaceAssetStore || !existingCanonicalAsset)
+                return;
+            if ((input.strictOrdering === true
+                || hasPublishedWorkspaceSyncContentHead(deps, {
+                    workspaceId,
+                    kind: 'asset',
+                    logicalPath: normalizedPath,
+                }))
+                &&
+                    compareWorkspaceMutationOrdering(deletedAt, existingCanonicalAsset.updatedAt, `delete:${normalizedPath}`, existingCanonicalAsset.contentSha256) < 0)
+                return;
+            deps.workspaceAssetStore.markDeleted(existingCanonicalAsset.assetId, workspaceId, deletedAt);
+            if (existingCanonicalAsset.kind === 'image') {
+                deps.core.deleteAnnotatedAttachmentSessionsForImage({
+                    workspaceId,
+                    imageAssetId: existingCanonicalAsset.assetId,
+                    deletedAt,
+                });
+            }
+            const links = deps.workspaceAssetStore.listLinksForAsset(existingCanonicalAsset.assetId, workspaceId, { includeDeleted: true });
+            for (const link of links) {
+                deps.workspaceAssetStore.deleteLink({
+                    workspaceId,
+                    assetId: existingCanonicalAsset.assetId,
+                    targetType: link.targetType,
+                    targetId: link.targetId,
+                    role: link.role
+                });
+            }
         });
-    }
+    };
+}
+export function canDeleteWorkspaceSyncBinaryAssetMetadata(deps, normalizedPath, workspaceId = 'default') {
+    return !listReferencedAiProfileAvatarAssets(deps, workspaceId).has(normalizedPath);
+}
+export function deleteWorkspaceSyncBinaryAssetMetadata(deps, input) {
+    const complete = beginWorkspaceSyncBinaryAssetMetadataDeletion(deps, input);
+    if (!complete)
+        return false;
+    complete();
+    return true;
 }
 export function deleteWorkspaceSyncBinaryAsset(deps, basePath, assetPath, workspaceId = 'default') {
     const normalizedPath = deps.normalizeTaskDataRelativePath(assetPath);
     if (!normalizedPath)
         return;
+    const deletedAt = new Date().toISOString();
+    const completeMetadataDeletion = beginWorkspaceSyncBinaryAssetMetadataDeletion(deps, {
+        normalizedPath,
+        deletedAt,
+        workspaceId,
+    });
+    if (!completeMetadataDeletion)
+        return;
     const root = path.resolve(basePath);
     const targetPath = path.resolve(root, normalizedPath);
     const objectStorageClient = deps.getObjectStorageClient();
@@ -1048,29 +1781,72 @@ export function deleteWorkspaceSyncBinaryAsset(deps, basePath, assetPath, worksp
             error: String(error?.message || error || '')
         });
     }
-    if (deps.workspaceAssetStore) {
-        const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-        if (existing) {
-            const deletedAt = new Date().toISOString();
-            deps.workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
-            if (existing.kind === 'image') {
-                deps.core.deleteAnnotatedAttachmentSessionsForImage({
+    completeMetadataDeletion();
+}
+function beginWorkspaceSyncDocumentMetadataDeletion(deps, input) {
+    const { normalizedPath, deletedAt, workspaceId = 'default', } = input;
+    return () => {
+        runWorkspaceSyncContentMetadataMutation(deps, {
+            workspaceId,
+            kind: 'document',
+            logicalPath: normalizedPath,
+            updatedAt: deletedAt,
+        }, () => {
+            const existingCanonicalAsset = deps.workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId) || null;
+            const current = newestDocumentMetadata(deps.core.getDocumentWatermark(workspaceId, normalizedPath), existingCanonicalAsset);
+            if ((input.strictOrdering === true
+                || hasPublishedWorkspaceSyncContentHead(deps, {
                     workspaceId,
-                    imageAssetId: existing.assetId,
-                    deletedAt,
-                });
+                    kind: 'document',
+                    logicalPath: normalizedPath,
+                }))
+                &&
+                    current
+                && compareWorkspaceMutationOrdering(deletedAt, current.updatedAt, `delete:${normalizedPath}`, current.contentHash) < 0)
+                return;
+            if (existingCanonicalAsset)
+                deps.workspaceAssetStore.markDeleted(existingCanonicalAsset.assetId, workspaceId, deletedAt);
+            if (input.strictWatermark === true) {
+                deps.core.deleteDocumentWatermarkStrict(workspaceId, normalizedPath);
             }
-            const links = deps.workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
-            for (const link of links) {
-                deps.workspaceAssetStore.deleteLink({
-                    workspaceId,
-                    assetId: existing.assetId,
-                    targetType: link.targetType,
-                    targetId: link.targetId,
-                    role: link.role
-                });
+            else {
+                deps.core.deleteDocumentWatermark(workspaceId, normalizedPath);
             }
-        }
+            if (deps.workspaceAssetStore && existingCanonicalAsset) {
+                if (existingCanonicalAsset.kind === 'image') {
+                    deps.core.deleteAnnotatedAttachmentSessionsForImage({
+                        workspaceId,
+                        imageAssetId: existingCanonicalAsset.assetId,
+                        deletedAt,
+                    });
+                }
+                const links = deps.workspaceAssetStore.listLinksForAsset(existingCanonicalAsset.assetId, workspaceId, { includeDeleted: true });
+                for (const link of links) {
+                    deps.workspaceAssetStore.deleteLink({
+                        workspaceId,
+                        assetId: existingCanonicalAsset.assetId,
+                        targetType: link.targetType,
+                        targetId: link.targetId,
+                        role: link.role
+                    });
+                }
+            }
+        });
+        deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+    };
+}
+export function deleteWorkspaceSyncDocumentMetadata(deps, input) {
+    const complete = beginWorkspaceSyncDocumentMetadataDeletion(deps, input);
+    try {
+        complete();
+    }
+    catch (error) {
+        deps.recordSyncDiagnostic(input.workspaceId || 'default', 'apply', 'Failed to delete document watermark.', {
+            source: 'documents.delete.watermark',
+            path: input.normalizedPath,
+            error: String(error?.message || error || '')
+        });
+        throw error;
     }
 }
 export function deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId = 'default') {
@@ -1081,6 +1857,12 @@ export function deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId
     const targetPath = path.resolve(root, normalizedPath);
     if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
         return;
+    const deletedAt = new Date().toISOString();
+    const completeMetadataDeletion = beginWorkspaceSyncDocumentMetadataDeletion(deps, {
+        normalizedPath,
+        deletedAt,
+        workspaceId,
+    });
     const objectStorageClient = deps.getObjectStorageClient();
     try {
         if (objectStorageClient) {
@@ -1098,31 +1880,7 @@ export function deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId
         });
     }
     try {
-        deps.core.deleteDocumentWatermark(workspaceId, normalizedPath);
-        if (deps.workspaceAssetStore) {
-            const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-            if (existing) {
-                const deletedAt = new Date().toISOString();
-                deps.workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
-                if (existing.kind === 'image') {
-                    deps.core.deleteAnnotatedAttachmentSessionsForImage({
-                        workspaceId,
-                        imageAssetId: existing.assetId,
-                        deletedAt,
-                    });
-                }
-                const links = deps.workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
-                for (const link of links) {
-                    deps.workspaceAssetStore.deleteLink({
-                        workspaceId,
-                        assetId: existing.assetId,
-                        targetType: link.targetType,
-                        targetId: link.targetId,
-                        role: link.role
-                    });
-                }
-            }
-        }
+        completeMetadataDeletion();
     }
     catch (error) {
         deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document watermark.', {
@@ -1130,11 +1888,13 @@ export function deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId
             path: normalizedPath,
             error: String(error?.message || error || '')
         });
+        deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
     }
-    deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
 }
 export function createContentSyncState(deps) {
     return {
+        readWorkspaceSyncContentFrontier: (workspaceId = 'default') => readWorkspaceSyncContentFrontier(deps, workspaceId),
+        hasWorkspaceSyncContentAfter: (workspaceId, cursor) => hasWorkspaceSyncContentAfter(deps, workspaceId, cursor),
         resolveCanonicalAssetSyncLinkState: (asset, workspaceId) => resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId),
         getCanonicalSyncDocumentMetadata: (relativePath, workspaceId) => getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId),
         hasDocumentSyncMetadataDrift: (workspaceId, doc, _options) => hasDocumentSyncMetadataDrift(deps, workspaceId, doc),
@@ -1150,6 +1910,46 @@ export function createContentSyncState(deps) {
         listWorkspaceSyncBinaryAssetDeletesSnapshot: (workspaceId = 'default') => listWorkspaceSyncBinaryAssetDeletesSnapshot(deps, workspaceId),
         writeWorkspaceSyncDocument: (basePath, doc, workspaceId = 'default', options) => writeWorkspaceSyncDocument(deps, basePath, doc, workspaceId, options),
         writeWorkspaceSyncBinaryAsset: (basePath, asset, workspaceId = 'default', options) => writeWorkspaceSyncBinaryAsset(deps, basePath, asset, workspaceId, options),
+        persistWorkspaceSyncDocumentMetadata: (document, workspaceId, metadata) => persistWorkspaceSyncDocumentMetadata(deps, {
+            document,
+            normalizedPath: document.path,
+            contentSha256: metadata.contentSha256,
+            sizeBytes: metadata.sizeBytes,
+            storageProvider: metadata.storageProvider,
+            workspaceId,
+            options: {
+                allowReferenceNumberReassignment: metadata.allowReferenceNumberReassignment,
+                strictWatermark: metadata.strictWatermark,
+                strictOrdering: metadata.strictOrdering,
+            },
+        }),
+        persistWorkspaceSyncBinaryAssetMetadata: (asset, workspaceId, metadata) => persistWorkspaceSyncBinaryAssetMetadata(deps, {
+            asset,
+            normalizedPath: asset.path,
+            contentSha256: metadata.contentSha256,
+            sizeBytes: metadata.sizeBytes,
+            storageProvider: metadata.storageProvider,
+            workspaceId,
+            options: {
+                allowReferenceNumberReassignment: metadata.allowReferenceNumberReassignment,
+                strictWatermark: metadata.strictWatermark,
+                strictOrdering: metadata.strictOrdering,
+            },
+        }),
+        deleteWorkspaceSyncBinaryAssetMetadata: (normalizedPath, workspaceId, deletedAt) => deleteWorkspaceSyncBinaryAssetMetadata(deps, {
+            normalizedPath,
+            workspaceId,
+            deletedAt,
+            strictOrdering: true,
+        }),
+        canDeleteWorkspaceSyncBinaryAssetMetadata: (normalizedPath, workspaceId) => canDeleteWorkspaceSyncBinaryAssetMetadata(deps, normalizedPath, workspaceId),
+        deleteWorkspaceSyncDocumentMetadata: (normalizedPath, workspaceId, deletedAt) => deleteWorkspaceSyncDocumentMetadata(deps, {
+            normalizedPath,
+            workspaceId,
+            deletedAt,
+            strictWatermark: true,
+            strictOrdering: true,
+        }),
         deleteWorkspaceSyncBinaryAsset: (basePath, assetPath, workspaceId = 'default') => deleteWorkspaceSyncBinaryAsset(deps, basePath, assetPath, workspaceId),
         deleteWorkspaceSyncDocument: (basePath, docPath, workspaceId = 'default') => deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId),
     };