@taskforcehq/taskforce 0.3.301 → 0.3.303

package/dist/server/routes/sync.js

@@ -1,13 +1,19 @@
-import * as fs from 'fs';
 import * as path from 'path';
-import { createHash, randomUUID } from 'crypto';
 import { parseJsonBody } from '../routes.js';
 import { normalizeTaskDataRelativePath, ObjectStorageClient } from '../../storage/objectStorageClient.js';
-import { WorkspaceAssetStore } from '../../storage/workspaceAssetStore.js';
+import { WorkspaceAssetStore, } from '../../storage/workspaceAssetStore.js';
 import { resolveSessionCookieAttributesForRequest } from '../auth.js';
 import { decryptDocument, ENCRYPTION_PREFIX } from '../../sync/encryptionService.js';
 import { isAiProfileSurfaceType } from '../../shared/aiProfileSurfaceType.js';
-import { compareWorkspaceMutationOrdering, getTaskMutationTieBreak, getTaskMutationWatermark } from '../../sync/workspaceSyncSurface.js';
+import { getTaskMutationTieBreak, getTaskMutationWatermark } from '../../sync/workspaceSyncSurface.js';
+import { normalizeTaskSyncPayload, taskSyncPayloadToCoreTask } from '../../sync/taskSyncPayload.js';
+import { normalizeBinaryAssetDeleteSyncPayload, normalizeBinaryAssetSyncPayload, normalizeDocumentDeleteSyncPayload, normalizeDocumentSyncPayload, serializeBinaryAssetSyncPayload, serializeDocumentSyncPayload } from '../../sync/contentSyncPayload.js';
+import { createContentSyncState } from '../../sync/contentSyncState.js';
+import { normalizeAiProfileSyncPayload, normalizeAnnotatedAttachmentSessionSyncPayload, normalizeDeleteSyncPayload, normalizeDocumentReviewCommentSyncPayload, normalizeDocumentReviewSessionSyncPayload, } from '../../sync/collaborationSyncPayload.js';
+import { createCollaborationSyncState } from '../../sync/collaborationSyncState.js';
+import { buildWorkspacePullFeed } from '../../sync/workspacePullFeed.js';
+import { normalizeInitiativeSyncPayload, normalizeTaxonomySyncPayload, normalizeWorkstreamSyncPayload, } from '../../sync/planningSyncPayload.js';
+import { applyAiProfileAndMemberSyncChanges, applyCollaborationSyncChanges, applyContentSyncChanges, applyPlanningSyncChanges, resolveSyncConflictOrdering, } from '../../sync/syncApplyHandlers.js';
 import { applyWorkspaceRepair } from '../../sync/workspaceRepair.js';
 function decodeWorkspaceSyncCursor(raw) {
     const value = String(raw || '').trim();
@@ -174,790 +180,38 @@ export function registerSyncRoutes(deps) {
             return normalized;
         return null;
     };
-    const resolveCanonicalAssetSyncLinkState = (asset, workspaceId) => {
-        if (!workspaceAssetStore) {
-            return {
-                primaryLink: null,
-                effectiveUpdatedAt: String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString()
-            };
-        }
-        const links = workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId, { includeDeleted: true });
-        const activeLinks = links.filter((entry) => !entry.deletedAt);
-        const primaryLink = activeLinks[0] || null;
-        let effectiveUpdatedAt = String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString();
-        for (const link of links) {
-            const linkUpdatedAt = String(link.updatedAt || link.createdAt || '').trim();
-            if (linkUpdatedAt && linkUpdatedAt > effectiveUpdatedAt)
-                effectiveUpdatedAt = linkUpdatedAt;
-        }
-        return { primaryLink, effectiveUpdatedAt };
-    };
-    const getCanonicalSyncDocumentMetadata = (relativePath, workspaceId) => {
-        if (!workspaceAssetStore)
-            return {};
-        const asset = workspaceAssetStore.getByStorageKey(relativePath, workspaceId);
-        if (!asset || asset.kind !== 'document')
-            return {};
-        const { primaryLink } = resolveCanonicalAssetSyncLinkState(asset, workspaceId);
-        return {
-            assetId: asset.assetId,
-            documentId: asset.documentId,
-            referenceNumber: asset.referenceNumber,
-            version: asset.version,
-            taskId: primaryLink?.taskId || null,
-            logicalName: asset.logicalName || null,
-            caption: primaryLink?.displayName || null,
-            originalFilename: asset.originalFilename || path.basename(relativePath),
-            linkRole: primaryLink?.role === 'reference' ? 'reference' : 'attachment'
-        };
-    };
-    const hasDocumentSyncMetadataDrift = (workspaceId, doc, options) => {
-        if (!workspaceAssetStore)
-            return false;
-        const existingAsset = workspaceAssetStore.getByStorageKey(doc.path, workspaceId);
-        if (!existingAsset || existingAsset.kind !== 'document')
-            return false;
-        const { primaryLink } = resolveCanonicalAssetSyncLinkState(existingAsset, workspaceId);
-        const normalizedIncomingReference = Number.isFinite(Number(doc.referenceNumber))
-            ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
-            : null;
-        const normalizedIncomingVersion = Number.isFinite(Number(doc.version))
-            ? Math.max(1, Math.floor(Number(doc.version)))
-            : null;
-        const normalizedIncomingDocumentId = typeof doc.documentId === 'string' && doc.documentId.trim().length > 0
-            ? doc.documentId.trim()
-            : null;
-        const normalizedIncomingLogicalName = typeof doc.logicalName === 'string' && doc.logicalName.trim().length > 0
-            ? doc.logicalName.trim()
-            : null;
-        const normalizedIncomingCaption = typeof doc.caption === 'string' && doc.caption.trim().length > 0
-            ? doc.caption.trim()
-            : null;
-        const normalizedIncomingFilename = typeof doc.originalFilename === 'string' && doc.originalFilename.trim().length > 0
-            ? doc.originalFilename.trim()
-            : null;
-        const normalizedIncomingTaskId = typeof doc.taskId === 'string' && doc.taskId.trim().length > 0
-            ? doc.taskId.trim()
+    const contentSyncState = createContentSyncState({
+        core,
+        workspaceAssetStore,
+        getObjectStorageClient,
+        normalizeWorkspaceSyncDocumentPath,
+        normalizeTaskDataRelativePath: (rawPath) => normalizeTaskDataRelativePath(String(rawPath || '').trim()),
+        recordSyncDiagnostic,
+        workspaceDocumentSnapshotCache,
+    });
+    const collaborationSyncState = createCollaborationSyncState({ core });
+    const hasTaskReferenceNumberDrift = (workspaceId, task) => {
+        const taskId = String(task?.id || '').trim();
+        const incomingReferenceNumber = Number.isFinite(Number(task?.referenceNumber))
+            ? Math.max(1, Math.floor(Number(task?.referenceNumber)))
             : null;
-        const normalizedIncomingLinkRole = doc.linkRole === 'reference' ? 'reference' : 'attachment';
-        const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
-        if (!allowReferenceNumberReassignment
-            && existingAsset.referenceNumber
-            && normalizedIncomingReference
-            && existingAsset.referenceNumber !== normalizedIncomingReference) {
-            recordSyncDiagnostic(workspaceId, 'apply', 'Detected document reference number mismatch during normal sync.', {
-                source: 'documents.referenceNumber.mismatch',
-                path: doc.path,
-                assetId: existingAsset.assetId,
-                existingReferenceNumber: existingAsset.referenceNumber,
-                incomingReferenceNumber: normalizedIncomingReference
-            });
-        }
-        return (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
-            || existingAsset.version !== normalizedIncomingVersion
-            || (existingAsset.documentId || null) !== normalizedIncomingDocumentId
-            || (existingAsset.logicalName || null) !== normalizedIncomingLogicalName
-            || (existingAsset.originalFilename || null) !== normalizedIncomingFilename
-            || (primaryLink?.taskId || null) !== normalizedIncomingTaskId
-            || (primaryLink?.displayName || null) !== normalizedIncomingCaption
-            || ((primaryLink?.role === 'reference' ? 'reference' : 'attachment')) !== normalizedIncomingLinkRole;
-    };
-    const hasBinaryAssetSyncMetadataDrift = (workspaceId, asset, options) => {
-        if (!workspaceAssetStore)
+        if (!incomingReferenceNumber)
             return false;
-        const existingAsset = workspaceAssetStore.getByStorageKey(asset.path, workspaceId);
-        if (!existingAsset || (existingAsset.kind !== 'image' && existingAsset.kind !== 'file'))
+        const existingTask = core.resolveTaskIdentifier(`T-${incomingReferenceNumber}`, workspaceId);
+        if (!existingTask || existingTask.id === taskId)
             return false;
-        const { primaryLink } = resolveCanonicalAssetSyncLinkState(existingAsset, workspaceId);
-        const normalizedIncomingReference = Number.isFinite(Number(asset.referenceNumber))
-            ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
-            : null;
-        const normalizedIncomingLogicalName = typeof asset.logicalName === 'string' && asset.logicalName.trim().length > 0
-            ? asset.logicalName.trim()
-            : null;
-        const normalizedIncomingCaption = typeof asset.caption === 'string' && asset.caption.trim().length > 0
-            ? asset.caption.trim()
-            : null;
-        const normalizedIncomingFilename = typeof asset.originalFilename === 'string' && asset.originalFilename.trim().length > 0
-            ? asset.originalFilename.trim()
-            : null;
-        const normalizedIncomingTaskId = typeof asset.taskId === 'string' && asset.taskId.trim().length > 0
-            ? asset.taskId.trim()
-            : null;
-        const normalizedIncomingLinkRole = asset.linkRole === 'reference'
-            ? 'reference'
-            : asset.kind === 'image'
-                ? 'image'
-                : 'attachment';
-        const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
-        if (!allowReferenceNumberReassignment
-            && existingAsset.referenceNumber
-            && normalizedIncomingReference
-            && existingAsset.referenceNumber !== normalizedIncomingReference) {
-            recordSyncDiagnostic(workspaceId, 'apply', 'Detected asset reference number mismatch during normal sync.', {
-                source: 'assets.referenceNumber.mismatch',
-                path: asset.path,
-                assetId: existingAsset.assetId,
-                existingReferenceNumber: existingAsset.referenceNumber,
-                incomingReferenceNumber: normalizedIncomingReference
-            });
-        }
-        return (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
-            || (existingAsset.logicalName || null) !== normalizedIncomingLogicalName
-            || (existingAsset.originalFilename || null) !== normalizedIncomingFilename
-            || (primaryLink?.taskId || null) !== normalizedIncomingTaskId
-            || (primaryLink?.displayName || null) !== normalizedIncomingCaption
-            || ((primaryLink?.role === 'reference'
-                ? 'reference'
-                : existingAsset.kind === 'image'
-                    ? 'image'
-                    : 'attachment')) !== normalizedIncomingLinkRole;
-    };
-    const reconcileWorkspaceSyncLinks = (input) => {
-        if (!workspaceAssetStore)
-            return;
-        const workspaceId = String(input.workspaceId || '').trim() || 'default';
-        const assetId = String(input.assetId || '').trim();
-        if (!assetId)
-            return;
-        const desiredTaskId = String(input.taskId || '').trim();
-        const desiredRole = input.role === 'reference'
-            ? 'reference'
-            : input.role === 'image'
-                ? 'image'
-                : 'attachment';
-        const linkUpdatedAt = String(input.updatedAt || '').trim() || new Date().toISOString();
-        const existingLinks = workspaceAssetStore.listLinksForAsset(assetId, workspaceId, { includeDeleted: true });
-        if (desiredTaskId) {
-            workspaceAssetStore.upsertLink({
-                workspaceId,
-                assetId,
-                taskId: desiredTaskId,
-                role: desiredRole,
-                displayName: typeof input.displayName === 'string' && input.displayName.trim().length > 0 ? input.displayName.trim() : null,
-                updatedAt: linkUpdatedAt,
-                deletedAt: null
-            });
-        }
-        // Only clean up stale links when we have an explicit incoming taskId. If the incoming
-        // asset-upsert carries no taskId, there is no authoritative association to enforce, so
-        // preserve all existing links rather than wiping them.
-        if (desiredTaskId) {
-            for (const link of existingLinks) {
-                if (link.taskId === desiredTaskId && link.role === desiredRole)
-                    continue;
-                if (link.deletedAt)
-                    continue;
-                workspaceAssetStore.deleteLink({
-                    workspaceId,
-                    assetId,
-                    taskId: link.taskId,
-                    role: link.role
-                });
-            }
-        }
-    };
-    const listWorkspaceSyncDocumentDeletesSnapshot = (workspaceId = 'default') => {
-        if (!workspaceAssetStore)
-            return [];
-        const entries = workspaceAssetStore.listAllByWorkspace(workspaceId, {
-            includeDeleted: true,
-            kind: 'document'
-        })
-            .filter((asset) => typeof asset.deletedAt === 'string' && asset.deletedAt.trim().length > 0)
-            .map((asset) => {
-            const normalizedPath = normalizeWorkspaceSyncDocumentPath(asset.storageKey);
-            if (!normalizedPath)
-                return null;
-            return {
-                path: normalizedPath,
-                deletedAt: String(asset.deletedAt || '').trim(),
-                assetId: asset.assetId
-            };
-        });
-        return entries.filter((entry) => Boolean(entry && entry.path && entry.deletedAt));
-    };
-    const listWorkspaceSyncDocumentReviewSessionsSnapshot = (workspaceId = 'default') => {
-        return core.listDocumentReviewSessionsForSync({ workspaceId, includeDeleted: true })
-            .map((session) => ({
-            id: session.id,
-            assetId: session.assetId,
-            documentId: session.documentId,
-            documentVersion: session.documentVersion,
-            title: session.title,
-            status: session.status,
-            comments: session.comments,
-            createdByActorId: session.createdByActorId,
-            updatedByActorId: session.updatedByActorId,
-            createdAt: session.createdAt,
-            updatedAt: session.updatedAt,
-            deletedAt: session.deletedAt,
-        }))
-            .filter((session) => session.id.length > 0 && session.assetId.length > 0);
-    };
-    const listWorkspaceSyncDocumentReviewCommentsSnapshot = (workspaceId = 'default') => {
-        return core.listDocumentReviewCommentsForSync({ workspaceId, includeDeleted: true })
-            .map((comment) => ({
-            id: comment.id,
-            sessionId: comment.sessionId,
-            body: comment.body,
-            anchor: comment.anchor,
-            order: comment.order,
-            authorActorId: comment.authorActorId,
-            createdAt: comment.createdAt,
-            updatedAt: comment.updatedAt,
-            deletedAt: comment.deletedAt,
-        }))
-            .filter((comment) => comment.id.length > 0 && comment.sessionId.length > 0);
-    };
-    const listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot = (workspaceId = 'default') => {
-        return core.listAnnotatedAttachmentSessionsForSync({ workspaceId, includeDeleted: true })
-            .map((session) => ({
-            id: session.id,
-            workspaceId: session.workspaceId,
-            taskId: session.taskId,
-            baseImageAssetId: session.baseImageAssetId,
-            title: session.title,
-            globalInstruction: session.globalInstruction,
-            annotations: session.annotations,
-            createdByActorId: session.createdByActorId,
-            updatedByActorId: session.updatedByActorId,
-            createdAt: session.createdAt,
-            updatedAt: session.updatedAt,
-            deletedAt: session.deletedAt,
-        }))
-            .filter((session) => (session.id.length > 0
-            && session.workspaceId.length > 0
-            && session.baseImageAssetId.length > 0));
-    };
-    const listWorkspaceSyncDocumentsSnapshot = async (basePath, workspaceId = 'default') => {
-        const root = path.resolve(basePath);
-        const objectStorageClient = getObjectStorageClient();
-        const candidatePaths = new Set();
-        const docsRoot = path.join(root, 'docs');
-        const collectMarkdownPaths = (directory) => {
-            if (!fs.existsSync(directory))
-                return;
-            const entries = fs.readdirSync(directory, { withFileTypes: true });
-            for (const entry of entries) {
-                const absolutePath = path.join(directory, entry.name);
-                if (entry.isDirectory()) {
-                    collectMarkdownPaths(absolutePath);
-                    continue;
-                }
-                if (!entry.isFile())
-                    continue;
-                const relativeFromRoot = path.relative(root, absolutePath).replace(/\\/g, '/');
-                const normalized = normalizeWorkspaceSyncDocumentPath(relativeFromRoot);
-                if (normalized)
-                    candidatePaths.add(normalized);
-            }
-        };
-        collectMarkdownPaths(docsRoot);
-        if (workspaceAssetStore) {
-            const canonicalAssets = workspaceAssetStore.listAllByWorkspace(workspaceId, {
-                includeDeleted: false,
-                kind: 'document'
-            });
-            for (const asset of canonicalAssets) {
-                const normalized = normalizeWorkspaceSyncDocumentPath(asset.storageKey);
-                if (normalized)
-                    candidatePaths.add(normalized);
-            }
-        }
-        const uniquePaths = Array.from(candidatePaths).sort((a, b) => a.localeCompare(b));
-        const workspaceCache = workspaceDocumentSnapshotCache.get(workspaceId) || new Map();
-        workspaceDocumentSnapshotCache.set(workspaceId, workspaceCache);
-        const remainingPaths = new Set(uniquePaths);
-        const docs = [];
-        for (const relativePath of uniquePaths) {
-            try {
-                const canonicalAsset = workspaceAssetStore?.getByStorageKey(relativePath, workspaceId);
-                let stat = null;
-                let content = null;
-                let updatedAt = '';
-                if (canonicalAsset?.kind === 'document') {
-                    updatedAt = resolveCanonicalAssetSyncLinkState(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');
-                    }
-                }
-                else {
-                    const absPath = path.resolve(path.join(basePath, relativePath));
-                    const safeRoot = path.resolve(basePath);
-                    if (absPath !== safeRoot && !absPath.startsWith(`${safeRoot}${path.sep}`))
-                        continue;
-                    stat = fs.statSync(absPath);
-                    if (!stat.isFile())
-                        continue;
-                    content = fs.readFileSync(absPath, 'utf8');
-                }
-                if (content == null)
-                    continue;
-                const cached = workspaceCache.get(relativePath);
-                if (cached
-                    && cached.size === Buffer.byteLength(content, 'utf8')
-                    && (canonicalAsset
-                        ? cached.updatedAt === updatedAt
-                        : (stat != null && cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs))) {
-                    docs.push({
-                        path: relativePath,
-                        updatedAt: cached.updatedAt,
-                        content: cached.content,
-                        ...getCanonicalSyncDocumentMetadata(relativePath, workspaceId)
-                    });
-                    continue;
-                }
-                if (!canonicalAsset) {
-                    const contentHash = createHash('sha256').update(content).digest('hex');
-                    const existing = core.getDocumentWatermark(workspaceId, relativePath);
-                    if (existing && existing.contentHash === contentHash) {
-                        updatedAt = existing.updatedAt;
-                    }
-                    else {
-                        updatedAt = stat && Number.isFinite(stat.mtimeMs)
-                            ? new Date(stat.mtimeMs).toISOString()
-                            : new Date().toISOString();
-                        try {
-                            core.upsertDocumentWatermark(workspaceId, relativePath, contentHash, updatedAt);
-                        }
-                        catch (error) {
-                            recordSyncDiagnostic(workspaceId, 'pull', 'Failed to persist document watermark during snapshot.', {
-                                source: 'documents.snapshot.upsertWatermark',
-                                path: relativePath,
-                                error: String(error?.message || error || '')
-                            });
-                        }
-                    }
-                }
-                docs.push({
-                    path: relativePath,
-                    updatedAt,
-                    content,
-                    ...getCanonicalSyncDocumentMetadata(relativePath, workspaceId)
-                });
-                workspaceCache.set(relativePath, {
-                    path: relativePath,
-                    mtimeMs: stat?.mtimeMs ?? 0,
-                    ctimeMs: stat?.ctimeMs ?? 0,
-                    size: Buffer.byteLength(content, 'utf8'),
-                    updatedAt,
-                    content
-                });
-            }
-            catch (error) {
-                recordSyncDiagnostic(workspaceId, 'pull', 'Failed to read sync document snapshot entry.', {
-                    source: 'documents.snapshot.readEntry',
-                    path: relativePath,
-                    error: String(error?.message || error || '')
-                });
-            }
-        }
-        for (const cachedPath of Array.from(workspaceCache.keys())) {
-            if (!remainingPaths.has(cachedPath))
-                workspaceCache.delete(cachedPath);
-        }
-        return docs;
-    };
-    const listWorkspaceSyncBinaryAssetsSnapshot = async (basePath, workspaceId = 'default') => {
-        if (!workspaceAssetStore)
-            return [];
-        const root = path.resolve(basePath);
-        const objectStorageClient = getObjectStorageClient();
-        const assets = workspaceAssetStore.listAllByWorkspace(workspaceId, {
-            includeDeleted: false
-        });
-        const snapshots = [];
-        for (const asset of assets) {
-            if (asset.kind !== 'image' && asset.kind !== 'file')
-                continue;
-            // External references are not syncable binary payloads.
-            if (asset.storageProvider === 'external')
-                continue;
-            const storageKey = String(asset.storageKey || '').trim();
-            if (!storageKey)
-                continue;
-            // Skip legacy task-data assets — they cannot be received on the other end
-            if (!normalizeTaskDataRelativePath(storageKey))
-                continue;
-            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)) {
-                        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);
-                }
-                if (!buffer) {
-                    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
-                    });
-                    continue;
-                }
-                const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(asset, workspaceId);
-                snapshots.push({
-                    path: storageKey,
-                    updatedAt: effectiveUpdatedAt,
-                    contentBase64: buffer.toString('base64'),
-                    assetId: asset.assetId,
-                    kind: asset.kind,
-                    mimeType: asset.mimeType || 'application/octet-stream',
-                    referenceNumber: asset.referenceNumber,
-                    taskId: primaryLink?.taskId || null,
-                    logicalName: asset.logicalName || null,
-                    caption: primaryLink?.displayName || null,
-                    originalFilename: asset.originalFilename || path.basename(storageKey),
-                    linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment')
-                });
-            }
-            catch (error) {
-                recordSyncDiagnostic(workspaceId, 'pull', 'Failed to read binary asset snapshot entry.', {
-                    source: 'assets.snapshot.readEntry',
-                    path: storageKey,
-                    error: String(error?.message || error || '')
-                });
-            }
-        }
-        return snapshots;
-    };
-    const listWorkspaceSyncBinaryAssetDeletesSnapshot = (workspaceId = 'default') => {
-        if (!workspaceAssetStore)
-            return [];
-        const entries = workspaceAssetStore.listAllByWorkspace(workspaceId, {
-            includeDeleted: true
-        })
-            .filter((asset) => ((asset.kind === 'image' || asset.kind === 'file')
-            && asset.storageProvider !== 'external'
-            && typeof asset.deletedAt === 'string'
-            && asset.deletedAt.trim().length > 0))
-            .map((asset) => {
-            const normalizedPath = normalizeTaskDataRelativePath(asset.storageKey);
-            if (!normalizedPath)
-                return null;
-            return {
-                path: normalizedPath,
-                deletedAt: String(asset.deletedAt || '').trim(),
-                assetId: asset.assetId
-            };
+        recordSyncDiagnostic(workspaceId, 'apply', 'Detected task reference number mismatch during normal sync.', {
+            source: 'tasks.referenceNumber.mismatch',
+            taskId: taskId || null,
+            taskTitle: typeof task?.title === 'string' ? task.title.trim() || null : null,
+            existingTaskId: existingTask.id,
+            existingTaskTitle: existingTask.title || null,
+            referenceLabel: `T-${incomingReferenceNumber}`,
+            existingReferenceNumber: existingTask.referenceNumber ?? incomingReferenceNumber,
+            incomingReferenceNumber
         });
-        return entries.filter((entry) => Boolean(entry && entry.path && entry.deletedAt));
-    };
-    const writeWorkspaceSyncDocument = async (basePath, doc, workspaceId = 'default', options) => {
-        const normalizedPath = 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 = getObjectStorageClient();
-        const content = String(doc.content || '');
-        if (objectStorageClient) {
-            try {
-                await objectStorageClient.putObject(normalizedPath, Buffer.from(content, 'utf8'), 'text/markdown');
-            }
-            catch (error) {
-                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');
-        }
-        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);
-        }
-        // Persist content hash + timestamp to SQLite so the snapshot function uses a
-        // stable watermark instead of relying on non-deterministic filesystem mtime.
-        try {
-            const contentHash = createHash('sha256').update(content).digest('hex');
-            core.upsertDocumentWatermark(workspaceId, normalizedPath, contentHash, updatedAt || new Date().toISOString());
-            if (workspaceAssetStore) {
-                const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-                const effectiveUpdatedAt = updatedAt || new Date().toISOString();
-                const originalFilename = String(doc.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'document.md').trim() || 'document.md';
-                const asset = 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: objectStorageClient ? 'r2' : 'local',
-                    storageKey: normalizedPath,
-                    contentSha256: contentHash,
-                    sizeBytes: Buffer.byteLength(content, 'utf8'),
-                    documentId: String(doc.documentId || existing?.documentId || `doc-${randomUUID().replace(/-/g, '')}`),
-                    referenceNumber: Number.isFinite(Number(doc.referenceNumber))
-                        ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
-                        : existing?.referenceNumber || null,
-                    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: options?.allowReferenceNumberReassignment === true
-                });
-                const taskId = String(doc.taskId || '').trim();
-                reconcileWorkspaceSyncLinks({
-                    workspaceId,
-                    assetId: asset.assetId,
-                    taskId,
-                    displayName: typeof doc.caption === 'string' && doc.caption.trim().length > 0 ? doc.caption.trim() : null,
-                    role: doc.linkRole === 'reference' ? 'reference' : 'attachment',
-                    updatedAt: effectiveUpdatedAt
-                });
-            }
-        }
-        catch (error) {
-            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist document watermark after write.', {
-                source: 'documents.write.upsertWatermark',
-                path: normalizedPath,
-                error: String(error?.message || error || '')
-            });
-        }
-        workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
-    };
-    const writeWorkspaceSyncBinaryAsset = async (basePath, asset, workspaceId = 'default', options) => {
-        const normalizedPath = normalizeTaskDataRelativePath(asset.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 = getObjectStorageClient();
-        const buffer = Buffer.from(String(asset.contentBase64 || ''), 'base64');
-        if (objectStorageClient) {
-            try {
-                await objectStorageClient.putObject(normalizedPath, buffer, String(asset.mimeType || 'application/octet-stream').trim() || 'application/octet-stream');
-            }
-            catch (error) {
-                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to write binary asset to object storage.', {
-                    source: 'assets.write.putObject',
-                    path: normalizedPath,
-                    error: String(error?.message || error || '')
-                });
-                return;
-            }
-        }
-        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);
-        }
-        if (!workspaceAssetStore)
-            return;
-        try {
-            const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-            const effectiveUpdatedAt = updatedAt || new Date().toISOString();
-            const assetRecord = 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: Number.isFinite(Number(asset.referenceNumber))
-                    ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
-                    : existing?.referenceNumber || null,
-                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: options?.allowReferenceNumberReassignment === true
-            });
-            const taskId = String(asset.taskId || '').trim();
-            reconcileWorkspaceSyncLinks({
-                workspaceId,
-                assetId: assetRecord.assetId,
-                taskId,
-                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
-            });
-        }
-        catch (error) {
-            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 true;
     };
-    const deleteWorkspaceSyncBinaryAsset = (basePath, assetPath, workspaceId = 'default') => {
-        const normalizedPath = normalizeTaskDataRelativePath(assetPath);
-        if (!normalizedPath)
-            return;
-        const root = path.resolve(basePath);
-        const targetPath = path.resolve(root, normalizedPath);
-        const objectStorageClient = getObjectStorageClient();
-        try {
-            if (objectStorageClient) {
-                void objectStorageClient.deleteObject(normalizedPath);
-            }
-            else if (targetPath === root || targetPath.startsWith(`${root}${path.sep}`)) {
-                if (fs.existsSync(targetPath))
-                    fs.unlinkSync(targetPath);
-            }
-        }
-        catch (error) {
-            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete workspace sync binary asset.', {
-                source: 'assets.delete.file',
-                path: normalizedPath,
-                error: String(error?.message || error || '')
-            });
-        }
-        if (workspaceAssetStore) {
-            const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-            if (existing) {
-                const deletedAt = new Date().toISOString();
-                workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
-                if (existing.kind === 'image') {
-                    core.deleteAnnotatedAttachmentSessionsForImage({
-                        workspaceId,
-                        imageAssetId: existing.assetId,
-                        deletedAt,
-                    });
-                }
-                const links = workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
-                for (const link of links) {
-                    workspaceAssetStore.deleteLink({
-                        workspaceId,
-                        assetId: existing.assetId,
-                        taskId: link.taskId,
-                        role: link.role
-                    });
-                }
-            }
-        }
-    };
-    const deleteWorkspaceSyncDocument = (basePath, docPath, workspaceId = 'default') => {
-        const normalizedPath = normalizeWorkspaceSyncDocumentPath(docPath);
-        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 = getObjectStorageClient();
-        try {
-            if (objectStorageClient) {
-                void objectStorageClient.deleteObject(normalizedPath);
-            }
-            else if (fs.existsSync(targetPath)) {
-                fs.unlinkSync(targetPath);
-            }
-        }
-        catch (error) {
-            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete workspace sync document.', {
-                source: 'documents.delete.file',
-                path: normalizedPath,
-                error: String(error?.message || error || '')
-            });
-        }
-        try {
-            core.deleteDocumentWatermark(workspaceId, normalizedPath);
-            if (workspaceAssetStore) {
-                const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
-                if (existing) {
-                    const deletedAt = new Date().toISOString();
-                    workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
-                    if (existing.kind === 'image') {
-                        core.deleteAnnotatedAttachmentSessionsForImage({
-                            workspaceId,
-                            imageAssetId: existing.assetId,
-                            deletedAt,
-                        });
-                    }
-                    const links = workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
-                    for (const link of links) {
-                        workspaceAssetStore.deleteLink({
-                            workspaceId,
-                            assetId: existing.assetId,
-                            taskId: link.taskId,
-                            role: link.role
-                        });
-                    }
-                }
-            }
-        }
-        catch (error) {
-            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document watermark.', {
-                source: 'documents.delete.watermark',
-                path: normalizedPath,
-                error: String(error?.message || error || '')
-            });
-        }
-        workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
-    };
-    const resolveConflictOrdering = (incomingWatermark, existingWatermark, incomingTieBreak, existingTieBreak) => (compareWorkspaceMutationOrdering(incomingWatermark, existingWatermark, incomingTieBreak, existingTieBreak));
     const dispatchWorkspaceSyncChanges = async (workspaceId, incomingChanges, options) => {
         const tasks = [];
         const archived = [];
@@ -992,72 +246,32 @@ export function registerSyncRoutes(deps) {
                 const raw = change;
                 const op = String(raw.op || '').trim().toLowerCase();
                 if (op === 'taxonomy-upsert') {
-                    if (raw.taxonomyState && typeof raw.taxonomyState === 'object' && !Array.isArray(raw.taxonomyState)) {
-                        incomingTaxonomyState = raw.taxonomyState;
-                        incomingTaxonomiesUpdatedAt = String(raw.updatedAt || raw.watermark || '').trim();
-                    }
-                    else if (Array.isArray(raw.taxonomies)) {
-                        incomingTaxonomies = raw.taxonomies;
-                        incomingTaxonomiesUpdatedAt = String(raw.updatedAt || raw.watermark || '').trim();
-                    }
+                    const taxonomy = normalizeTaxonomySyncPayload(raw);
+                    if (taxonomy?.taxonomyState)
+                        incomingTaxonomyState = taxonomy.taxonomyState;
+                    if (Array.isArray(taxonomy?.taxonomies))
+                        incomingTaxonomies = taxonomy.taxonomies;
+                    if (taxonomy?.updatedAt)
+                        incomingTaxonomiesUpdatedAt = taxonomy.updatedAt;
                     continue;
                 }
                 if (op === 'initiative-upsert') {
-                    const initiative = raw.initiative && typeof raw.initiative === 'object'
-                        ? raw.initiative
-                        : null;
-                    const initiativeId = String(initiative?.id || '').trim();
-                    if (initiativeId) {
-                        incomingInitiatives.set(initiativeId, {
-                            id: initiativeId,
-                            referenceNumber: Number.isFinite(Number(initiative?.referenceNumber))
-                                ? Math.max(1, Math.floor(Number(initiative?.referenceNumber)))
-                                : null,
-                            referenceLabel: typeof initiative?.referenceLabel === 'string' ? initiative.referenceLabel.trim() : undefined,
-                            title: String(initiative?.title || '').trim(),
-                            description: typeof initiative?.description === 'string' ? initiative.description : null,
-                            ownerId: typeof initiative?.ownerId === 'string' ? initiative.ownerId.trim() : null,
-                            createdAt: String(initiative?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
-                            updatedAt: String(initiative?.updatedAt || raw.updatedAt || raw.watermark || initiative?.createdAt || '').trim(),
-                            order: Number.isFinite(Number(initiative?.order)) ? Math.floor(Number(initiative?.order)) : null,
-                            isArchived: Boolean(initiative?.isArchived)
-                        });
-                    }
+                    const initiative = normalizeInitiativeSyncPayload(raw.initiative, String(raw.updatedAt || raw.watermark || '').trim());
+                    if (initiative)
+                        incomingInitiatives.set(initiative.id, initiative);
                     continue;
                 }
                 if (op === 'workstream-upsert') {
-                    const workstream = raw.workstream && typeof raw.workstream === 'object'
-                        ? raw.workstream
-                        : null;
-                    const workstreamId = String(workstream?.id || '').trim();
-                    if (workstreamId) {
-                        incomingWorkstreams.set(workstreamId, {
-                            id: workstreamId,
-                            referenceNumber: Number.isFinite(Number(workstream?.referenceNumber))
-                                ? Math.max(1, Math.floor(Number(workstream?.referenceNumber)))
-                                : null,
-                            referenceLabel: typeof workstream?.referenceLabel === 'string' ? workstream.referenceLabel.trim() : undefined,
-                            initiativeId: typeof workstream?.initiativeId === 'string' && workstream.initiativeId.trim().length > 0
-                                ? workstream.initiativeId.trim()
-                                : null,
-                            title: String(workstream?.title || '').trim(),
-                            description: typeof workstream?.description === 'string' ? workstream.description : null,
-                            ownerId: typeof workstream?.ownerId === 'string' ? workstream.ownerId.trim() : null,
-                            createdAt: String(workstream?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
-                            updatedAt: String(workstream?.updatedAt || raw.updatedAt || raw.watermark || workstream?.createdAt || '').trim(),
-                            order: Number.isFinite(Number(workstream?.order)) ? Math.floor(Number(workstream?.order)) : null,
-                            isArchived: Boolean(workstream?.isArchived)
-                        });
-                    }
+                    const workstream = normalizeWorkstreamSyncPayload(raw.workstream, String(raw.updatedAt || raw.watermark || '').trim());
+                    if (workstream)
+                        incomingWorkstreams.set(workstream.id, workstream);
                     continue;
                 }
                 if (op === 'ai-profile-upsert') {
-                    const profile = raw.profile && typeof raw.profile === 'object'
-                        ? raw.profile
-                        : null;
+                    const profile = normalizeAiProfileSyncPayload(raw.profile, workspaceId, normalizeIncomingAiProfileSurfaceType, 'apply.aiProfileUpsert');
                     const profileId = String(profile?.id || '').trim();
-                    if (profileId) {
-                        const profileWorkspaceId = String(profile?.workspaceId || '').trim();
+                    if (profileId && profile) {
+                        const profileWorkspaceId = String(profile.workspaceId || '').trim();
                         if (profileWorkspaceId && profileWorkspaceId !== workspaceId) {
                             recordSyncDiagnostic(workspaceId, 'apply', `Rejected ai-profile-upsert for profile ${profileId}: workspace mismatch (expected ${workspaceId}, got ${profileWorkspaceId}).`, {
                                 source: 'apply.aiProfileWorkspaceMismatch',
@@ -1069,185 +283,77 @@ export function registerSyncRoutes(deps) {
                             continue;
                         }
                         incomingAiProfiles.set(profileId, {
-                            id: profileId,
+                            ...profile,
                             workspaceId,
-                            profileToken: String(profile?.profileToken || '').trim(),
-                            name: String(profile?.name || '').trim(),
-                            username: String(profile?.username || '').trim(),
-                            icon: String(profile?.icon || 'Bot').trim() || 'Bot',
-                            color: String(profile?.color || '#8b5cf6').trim() || '#8b5cf6',
-                            surfaceType: normalizeIncomingAiProfileSurfaceType(profile?.surfaceType, {
-                                source: 'apply.aiProfileUpsert',
-                                profileId,
-                                workspaceId
-                            }),
-                            providerMetadata: profile?.providerMetadata && typeof profile.providerMetadata === 'object' && !Array.isArray(profile.providerMetadata)
-                                ? profile.providerMetadata
-                                : null,
-                            createdAt: String(profile?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
-                            updatedAt: String(profile?.updatedAt || raw.updatedAt || raw.watermark || '').trim(),
-                            lastActiveAt: typeof profile?.lastActiveAt === 'string' && profile.lastActiveAt.trim().length > 0
-                                ? profile.lastActiveAt.trim()
-                                : null
+                            createdAt: profile.createdAt || String(raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: profile.updatedAt || String(raw.updatedAt || raw.watermark || '').trim(),
                         });
                     }
                     continue;
                 }
                 if (op === 'document-upsert') {
-                    const normalizedPath = normalizeWorkspaceSyncDocumentPath(raw.path);
-                    if (normalizedPath) {
-                        incomingDocuments.push({
-                            path: normalizedPath,
-                            updatedAt: String(raw.updatedAt || raw.watermark || '').trim(),
-                            content: typeof raw.content === 'string' ? raw.content : '',
-                            assetId: typeof raw.assetId === 'string' ? raw.assetId.trim() : undefined,
-                            documentId: typeof raw.documentId === 'string' ? raw.documentId.trim() : null,
-                            referenceNumber: Number.isFinite(Number(raw.referenceNumber))
-                                ? Math.max(1, Math.floor(Number(raw.referenceNumber)))
-                                : null,
-                            version: Number.isFinite(Number(raw.version)) ? Math.max(1, Math.floor(Number(raw.version))) : null,
-                            taskId: typeof raw.taskId === 'string' ? raw.taskId.trim() : null,
-                            logicalName: typeof raw.logicalName === 'string' ? raw.logicalName.trim() : null,
-                            caption: typeof raw.caption === 'string' ? raw.caption.trim() : null,
-                            originalFilename: typeof raw.originalFilename === 'string' ? raw.originalFilename.trim() : null,
-                            linkRole: raw.linkRole === 'reference' ? 'reference' : 'attachment'
-                        });
-                    }
+                    const document = normalizeDocumentSyncPayload(raw, normalizeWorkspaceSyncDocumentPath);
+                    if (document)
+                        incomingDocuments.push(document);
                     continue;
                 }
                 if (op === 'document-delete') {
-                    const normalizedPath = normalizeWorkspaceSyncDocumentPath(raw.path);
-                    if (normalizedPath) {
-                        incomingDocumentDeletes.set(normalizedPath, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
-                    }
+                    const deletedDocument = normalizeDocumentDeleteSyncPayload(raw, normalizeWorkspaceSyncDocumentPath);
+                    if (deletedDocument)
+                        incomingDocumentDeletes.set(deletedDocument.path, deletedDocument.deletedAt);
                     continue;
                 }
                 if (op === 'asset-upsert') {
-                    const normalizedPath = normalizeTaskDataRelativePath(String(raw.path || '').trim());
-                    if (normalizedPath) {
-                        incomingAssets.push({
-                            path: normalizedPath,
-                            updatedAt: String(raw.updatedAt || raw.watermark || '').trim(),
-                            contentBase64: typeof raw.contentBase64 === 'string' ? raw.contentBase64 : '',
-                            assetId: typeof raw.assetId === 'string' ? raw.assetId.trim() : undefined,
-                            kind: raw.kind === 'image' ? 'image' : 'file',
-                            mimeType: typeof raw.mimeType === 'string' ? raw.mimeType.trim() : 'application/octet-stream',
-                            referenceNumber: Number.isFinite(Number(raw.referenceNumber))
-                                ? Math.max(1, Math.floor(Number(raw.referenceNumber)))
-                                : null,
-                            taskId: typeof raw.taskId === 'string' ? raw.taskId.trim() : null,
-                            logicalName: typeof raw.logicalName === 'string' ? raw.logicalName.trim() : null,
-                            caption: typeof raw.caption === 'string' ? raw.caption.trim() : null,
-                            originalFilename: typeof raw.originalFilename === 'string' ? raw.originalFilename.trim() : null,
-                            linkRole: raw.linkRole === 'reference' ? 'reference' : raw.linkRole === 'image' ? 'image' : 'attachment'
-                        });
-                    }
+                    const asset = normalizeBinaryAssetSyncPayload(raw, (rawPath) => normalizeTaskDataRelativePath(String(rawPath || '').trim()));
+                    if (asset)
+                        incomingAssets.push(asset);
                     continue;
                 }
                 if (op === 'asset-delete') {
-                    const normalizedPath = normalizeTaskDataRelativePath(String(raw.path || '').trim());
-                    if (normalizedPath) {
-                        incomingAssetDeletes.set(normalizedPath, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
-                    }
+                    const deletedAsset = normalizeBinaryAssetDeleteSyncPayload(raw, (rawPath) => normalizeTaskDataRelativePath(String(rawPath || '').trim()));
+                    if (deletedAsset)
+                        incomingAssetDeletes.set(deletedAsset.path, deletedAsset.deletedAt);
                     continue;
                 }
                 if (op === 'document-review-session-upsert') {
-                    const session = raw.session && typeof raw.session === 'object'
-                        ? raw.session
-                        : null;
-                    const sessionId = String(session?.id || '').trim();
-                    const assetId = String(session?.assetId || '').trim();
-                    if (sessionId && assetId) {
-                        incomingDocumentReviewSessions.set(sessionId, {
-                            id: sessionId,
-                            assetId,
-                            documentId: typeof session?.documentId === 'string' ? session.documentId.trim() : null,
-                            documentVersion: Number.isFinite(Number(session?.documentVersion)) ? Math.max(1, Math.floor(Number(session?.documentVersion))) : null,
-                            title: typeof session?.title === 'string' ? session.title.trim() : null,
-                            status: session?.status === 'resolved' ? 'resolved' : 'open',
-                            comments: Array.isArray(session?.comments) ? session.comments : [],
-                            createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
-                            updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
-                            createdAt: String(session?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
-                            updatedAt: String(session?.updatedAt || raw.updatedAt || raw.watermark || session?.createdAt || '').trim(),
-                            deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null,
-                        });
-                    }
+                    const session = normalizeDocumentReviewSessionSyncPayload(raw.session, String(raw.updatedAt || raw.watermark || '').trim());
+                    if (session)
+                        incomingDocumentReviewSessions.set(session.id, session);
                     continue;
                 }
                 if (op === 'document-review-session-delete') {
-                    const sessionId = String(raw.sessionId || raw.id || '').trim();
-                    if (sessionId) {
-                        incomingDocumentReviewSessionDeletes.set(sessionId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
-                    }
+                    const deletedSession = normalizeDeleteSyncPayload(raw, 'sessionId');
+                    if (deletedSession)
+                        incomingDocumentReviewSessionDeletes.set(deletedSession.id, deletedSession.deletedAt);
                     continue;
                 }
                 if (op === 'document-review-comment-upsert') {
-                    const comment = raw.comment && typeof raw.comment === 'object'
-                        ? raw.comment
-                        : null;
-                    const commentId = String(comment?.id || '').trim();
-                    const sessionId = String(comment?.sessionId || '').trim();
-                    if (commentId && sessionId) {
-                        incomingDocumentReviewComments.set(commentId, {
-                            id: commentId,
-                            sessionId,
-                            body: typeof comment?.body === 'string' ? comment.body : '',
-                            anchor: comment?.anchor ?? null,
-                            order: Number.isFinite(Number(comment?.order)) ? Math.max(0, Math.floor(Number(comment?.order))) : 0,
-                            authorActorId: typeof comment?.authorActorId === 'string' ? comment.authorActorId.trim() : null,
-                            createdAt: String(comment?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
-                            updatedAt: String(comment?.updatedAt || raw.updatedAt || raw.watermark || comment?.createdAt || '').trim(),
-                            deletedAt: typeof comment?.deletedAt === 'string' && comment.deletedAt.trim().length > 0 ? comment.deletedAt.trim() : null,
-                        });
-                    }
+                    const comment = normalizeDocumentReviewCommentSyncPayload(raw.comment, { sourceWatermark: String(raw.updatedAt || raw.watermark || '').trim() });
+                    if (comment)
+                        incomingDocumentReviewComments.set(comment.id, comment);
                     continue;
                 }
                 if (op === 'document-review-comment-delete') {
-                    const commentId = String(raw.commentId || raw.id || '').trim();
-                    if (commentId) {
-                        incomingDocumentReviewCommentDeletes.set(commentId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
-                    }
+                    const deletedComment = normalizeDeleteSyncPayload(raw, 'commentId');
+                    if (deletedComment)
+                        incomingDocumentReviewCommentDeletes.set(deletedComment.id, deletedComment.deletedAt);
                     continue;
                 }
                 if (op === 'annotated-attachment-session-upsert') {
-                    const session = raw.session && typeof raw.session === 'object'
-                        ? raw.session
-                        : null;
-                    const sessionId = String(session?.id || '').trim();
-                    const sessionWorkspaceId = String(session?.workspaceId || '').trim();
-                    const taskId = String(session?.taskId || '').trim();
-                    const baseImageAssetId = String(session?.baseImageAssetId || '').trim();
-                    if (sessionId
-                        && sessionWorkspaceId === workspaceId
-                        && baseImageAssetId) {
-                        incomingAnnotatedAttachmentSessions.set(sessionId, {
-                            id: sessionId,
-                            workspaceId: sessionWorkspaceId,
-                            taskId,
-                            baseImageAssetId,
-                            title: typeof session?.title === 'string' ? session.title.trim() : null,
-                            globalInstruction: typeof session?.globalInstruction === 'string' ? session.globalInstruction.trim() : null,
-                            annotations: Array.isArray(session?.annotations) ? session.annotations : [],
-                            createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
-                            updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
-                            createdAt: String(session?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
-                            updatedAt: String(session?.updatedAt || raw.updatedAt || raw.watermark || session?.createdAt || '').trim(),
-                            deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null,
-                        });
-                    }
+                    const session = normalizeAnnotatedAttachmentSessionSyncPayload(raw.session, workspaceId, String(raw.updatedAt || raw.watermark || '').trim());
+                    if (session)
+                        incomingAnnotatedAttachmentSessions.set(session.id, session);
                     continue;
                 }
                 if (op === 'annotated-attachment-session-delete') {
-                    const sessionId = String(raw.sessionId || raw.id || '').trim();
-                    if (sessionId) {
-                        incomingAnnotatedAttachmentSessionDeletes.set(sessionId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
-                    }
+                    const deletedSession = normalizeDeleteSyncPayload(raw, 'sessionId');
+                    if (deletedSession)
+                        incomingAnnotatedAttachmentSessionDeletes.set(deletedSession.id, deletedSession.deletedAt);
                     continue;
                 }
                 if (op !== 'delete')
                     continue;
-                const task = raw.task;
+                const task = normalizeTaskSyncPayload(raw.task);
                 const deleteTaskId = String(raw.taskId || raw.id || task?.id || '').trim();
                 if (deleteTaskId) {
                     incomingTaskDeletes.set(deleteTaskId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
@@ -1270,13 +376,14 @@ export function registerSyncRoutes(deps) {
                     || op === 'annotated-attachment-session-upsert'
                     || op === 'annotated-attachment-session-delete')
                     continue;
-                const task = raw.task && typeof raw.task === 'object' ? raw.task : null;
+                const task = normalizeTaskSyncPayload(raw.task);
                 if (!task)
                     continue;
                 const taskId = String(task.id || '').trim();
+                hasTaskReferenceNumberDrift(workspaceId, task);
                 const deleteWatermark = taskId ? String(incomingTaskDeletes.get(taskId) || '').trim() : '';
                 if (taskId && deleteWatermark) {
-                    const compareAgainstDelete = resolveConflictOrdering(deleteWatermark, String(task.updatedAt || task.createdAt || '').trim(), `delete:${taskId}`, getTaskMutationTieBreak(task, raw.archived === true || task?.isArchived === true));
+                    const compareAgainstDelete = resolveSyncConflictOrdering(deleteWatermark, String(task.updatedAt || task.createdAt || '').trim(), `delete:${taskId}`, getTaskMutationTieBreak(task, raw.archived === true || task?.isArchived === true));
                     if (compareAgainstDelete >= 0)
                         continue;
                 }
@@ -1290,7 +397,7 @@ export function registerSyncRoutes(deps) {
                 try {
                     const existingTask = core.getTask(taskId, workspaceId);
                     if (existingTask) {
-                        const compareAgainstExisting = resolveConflictOrdering(deleteWatermark, getTaskMutationWatermark(existingTask), `delete:${taskId}`, getTaskMutationTieBreak(existingTask, Boolean(existingTask.isArchived)));
+                        const compareAgainstExisting = resolveSyncConflictOrdering(deleteWatermark, getTaskMutationWatermark(existingTask), `delete:${taskId}`, getTaskMutationTieBreak(existingTask, Boolean(existingTask.isArchived)));
                         if (compareAgainstExisting < 0)
                             continue;
                     }
@@ -1304,435 +411,62 @@ export function registerSyncRoutes(deps) {
                     });
                 }
             }
-            if (incomingInitiatives.size > 0) {
-                for (const initiative of incomingInitiatives.values()) {
-                    try {
-                        core.upsertInitiativeForSync({
-                            id: initiative.id,
-                            referenceNumber: initiative.referenceNumber,
-                            referenceLabel: initiative.referenceLabel,
-                            title: initiative.title,
-                            description: initiative.description,
-                            ownerId: initiative.ownerId,
-                            createdAt: initiative.createdAt,
-                            updatedAt: initiative.updatedAt,
-                            order: initiative.order,
-                            isArchived: initiative.isArchived
-                        }, workspaceId);
-                    }
-                    catch (error) {
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert initiative during sync apply.', {
-                            source: 'apply.initiativeUpsert',
-                            initiativeId: initiative.id,
-                            error: String(error?.message || error || '')
-                        });
-                        throw error;
-                    }
-                }
-            }
-            if (incomingWorkstreams.size > 0) {
-                for (const workstream of incomingWorkstreams.values()) {
-                    try {
-                        core.upsertWorkstreamForSync({
-                            id: workstream.id,
-                            referenceNumber: workstream.referenceNumber,
-                            referenceLabel: workstream.referenceLabel,
-                            initiativeId: workstream.initiativeId,
-                            title: workstream.title,
-                            description: workstream.description,
-                            ownerId: workstream.ownerId,
-                            createdAt: workstream.createdAt,
-                            updatedAt: workstream.updatedAt,
-                            order: workstream.order,
-                            isArchived: workstream.isArchived
-                        }, workspaceId);
-                    }
-                    catch (error) {
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert workstream during sync apply.', {
-                            source: 'apply.workstreamUpsert',
-                            workstreamId: workstream.id,
-                            error: String(error?.message || error || '')
-                        });
-                        throw error;
-                    }
-                }
-            }
-            if (incomingTaxonomyState || Array.isArray(incomingTaxonomies)) {
-                const nextTaxonomyState = incomingTaxonomyState || { taxonomies: incomingTaxonomies || [] };
-                if (!incomingTaxonomiesUpdatedAt) {
-                    if (typeof core.updateTaxonomyState === 'function') {
-                        core.updateTaxonomyState(nextTaxonomyState, workspaceId);
-                    }
-                    else {
-                        core.updateTaxonomies(Array.isArray(incomingTaxonomies) ? incomingTaxonomies : []);
-                    }
-                    const fallbackHash = createHash('sha256').update(JSON.stringify(nextTaxonomyState)).digest('hex');
-                    workspaceTaxonomySyncMeta.set(workspaceId, {
-                        updatedAt: new Date().toISOString(),
-                        hash: fallbackHash
-                    });
-                }
-                else {
-                    const incomingTaxonomyHash = createHash('sha256').update(JSON.stringify(nextTaxonomyState)).digest('hex');
-                    const currentMeta = workspaceTaxonomySyncMeta.get(workspaceId) || { updatedAt: '', hash: '' };
-                    const compare = resolveConflictOrdering(incomingTaxonomiesUpdatedAt, currentMeta.updatedAt, incomingTaxonomyHash, currentMeta.hash);
-                    if (compare >= 0) {
-                        if (typeof core.updateTaxonomyState === 'function') {
-                            core.updateTaxonomyState(nextTaxonomyState, workspaceId);
-                        }
-                        else {
-                            core.updateTaxonomies(Array.isArray(incomingTaxonomies) ? incomingTaxonomies : []);
-                        }
-                        workspaceTaxonomySyncMeta.set(workspaceId, {
-                            updatedAt: incomingTaxonomiesUpdatedAt,
-                            hash: incomingTaxonomyHash
-                        });
-                    }
-                }
-            }
-            if (incomingAiProfiles.size > 0) {
-                for (const profile of incomingAiProfiles.values()) {
-                    try {
-                        core.upsertAiProfileForSync({
-                            id: profile.id,
-                            workspaceId: workspaceId,
-                            profileToken: profile.profileToken,
-                            name: profile.name,
-                            username: profile.username,
-                            icon: profile.icon,
-                            color: profile.color,
-                            surfaceType: profile.surfaceType,
-                            providerMetadata: profile.providerMetadata,
-                            createdAt: profile.createdAt,
-                            updatedAt: profile.updatedAt,
-                            lastActiveAt: profile.lastActiveAt
-                        });
-                    }
-                    catch (error) {
-                        const details = {
-                            source: 'apply.aiProfileUpsert',
-                            workspaceId,
-                            profileId: profile.id,
-                            error: String(error?.message || error || ''),
-                            errorCode: String(error?.code || '').trim() || null
-                        };
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert AI profile during sync apply.', details);
-                        throw createSyncRouteError(`Failed to persist AI profile ${profile.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'AI_PROFILE_SYNC_APPLY_FAILED', statusCode: 500 });
-                    }
-                }
-                assertSyncedAiProfilesPersisted(workspaceId, incomingAiProfiles);
-            }
-            if (Array.isArray(options?.workspaceMembers)) {
-                core.replaceWorkspaceUsersForSync({
-                    workspaceId,
-                    users: options.workspaceMembers
-                        .filter((member) => String(member?.workspaceId || workspaceId).trim() === workspaceId)
-                        .map((member) => ({
-                        userId: member.userId,
-                        email: member.email,
-                        displayName: member.displayName,
-                        role: member.role,
-                        permissionMode: member.permissionMode,
-                        betaAccess: member.betaAccess,
-                        status: member.status,
-                        disabled: member.disabled,
-                        createdAt: member.createdAt,
-                        updatedAt: member.updatedAt,
-                        emailVerifiedAt: member.emailVerifiedAt
-                    }))
-                });
-            }
+            applyPlanningSyncChanges({
+                core,
+                workspaceId,
+                incomingInitiatives,
+                incomingWorkstreams,
+                incomingTaxonomies,
+                incomingTaxonomyState,
+                incomingTaxonomiesUpdatedAt,
+                workspaceTaxonomySyncMeta,
+                recordSyncDiagnostic,
+            });
+            applyAiProfileAndMemberSyncChanges({
+                core,
+                workspaceId,
+                incomingAiProfiles,
+                workspaceMembers: options?.workspaceMembers,
+                recordSyncDiagnostic,
+                assertSyncedAiProfilesPersisted,
+                createSyncRouteError,
+            });
             validateTaskActorAssignments(workspaceId, tasks, archived);
-            if (incomingDocuments.length > 0) {
-                for (const doc of incomingDocuments) {
-                    try {
-                        const existingDoc = core.getDocumentWatermark(workspaceId, doc.path);
-                        const incomingHash = createHash('sha256').update(String(doc.content || '')).digest('hex');
-                        const existingUpdatedAt = String(existingDoc?.updatedAt || '').trim();
-                        const existingHash = String(existingDoc?.contentHash || '').trim();
-                        const compare = resolveConflictOrdering(doc.updatedAt, existingUpdatedAt, incomingHash, existingHash);
-                        const metadataDrift = hasDocumentSyncMetadataDrift(workspaceId, doc, options);
-                        if (compare < 0)
-                            continue;
-                        if (compare === 0 && existingHash === incomingHash && !metadataDrift)
-                            continue;
-                        await writeWorkspaceSyncDocument(core.getPaths().basePath, doc, workspaceId, options);
-                    }
-                    catch (error) {
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to apply synced document change.', {
-                            source: 'documents.apply.write',
-                            path: doc.path,
-                            assetId: typeof doc.assetId === 'string' ? doc.assetId : null,
-                            error: String(error?.message || error || '')
-                        });
-                    }
-                }
-            }
-            if (incomingDocumentDeletes.size > 0) {
-                for (const [docPath, deletedAt] of incomingDocumentDeletes.entries()) {
-                    const existingDoc = core.getDocumentWatermark(workspaceId, docPath);
-                    const existingUpdatedAt = String(existingDoc?.updatedAt || '').trim();
-                    const existingHash = String(existingDoc?.contentHash || '').trim();
-                    const compare = resolveConflictOrdering(deletedAt, existingUpdatedAt, `delete:${docPath}`, existingHash);
-                    if (existingDoc && compare < 0)
-                        continue;
-                    deleteWorkspaceSyncDocument(core.getPaths().basePath, docPath, workspaceId);
-                }
-            }
-            if (incomingAssets.length > 0) {
-                for (const asset of incomingAssets) {
-                    try {
-                        const existing = workspaceAssetStore?.getByStorageKey(asset.path, workspaceId);
-                        const incomingHash = createHash('sha256').update(Buffer.from(String(asset.contentBase64 || ''), 'base64')).digest('hex');
-                        const existingUpdatedAt = String(existing?.updatedAt || '').trim();
-                        const existingHash = String(existing?.contentSha256 || '').trim();
-                        const assetPath = path.resolve(core.getPaths().basePath, asset.path);
-                        const localFileMissing = !getObjectStorageClient() && !fs.existsSync(assetPath);
-                        const compare = resolveConflictOrdering(asset.updatedAt, existingUpdatedAt, incomingHash, existingHash);
-                        const metadataDrift = hasBinaryAssetSyncMetadataDrift(workspaceId, asset, options);
-                        if (compare < 0)
-                            continue;
-                        if (compare === 0 && existingHash === incomingHash && !localFileMissing && !metadataDrift)
-                            continue;
-                        await writeWorkspaceSyncBinaryAsset(core.getPaths().basePath, asset, workspaceId, options);
-                    }
-                    catch (error) {
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to apply synced asset change.', {
-                            source: 'assets.apply.write',
-                            path: asset.path,
-                            assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
-                            kind: asset.kind,
-                            error: String(error?.message || error || '')
-                        });
-                    }
-                }
-            }
-            if (incomingAssetDeletes.size > 0) {
-                for (const [assetPath, deletedAt] of incomingAssetDeletes.entries()) {
-                    const existing = workspaceAssetStore?.getByStorageKey(assetPath, workspaceId);
-                    const existingUpdatedAt = String(existing?.updatedAt || '').trim();
-                    const existingHash = String(existing?.contentSha256 || '').trim();
-                    const compare = resolveConflictOrdering(deletedAt, existingUpdatedAt, `delete:${assetPath}`, existingHash);
-                    if (existing && compare < 0)
-                        continue;
-                    deleteWorkspaceSyncBinaryAsset(core.getPaths().basePath, assetPath, workspaceId);
-                }
-            }
-            if (incomingDocumentReviewSessions.size > 0) {
-                for (const session of incomingDocumentReviewSessions.values()) {
-                    try {
-                        const existing = core.getDocumentReviewSession({
-                            workspaceId,
-                            sessionId: session.id,
-                            includeDeleted: true
-                        });
-                        const incomingTieBreak = createHash('sha256').update(JSON.stringify(session.comments || [])).digest('hex');
-                        const existingTieBreak = existing
-                            ? createHash('sha256').update(JSON.stringify(existing.comments || [])).digest('hex')
-                            : '';
-                        const compare = resolveConflictOrdering(session.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
-                        if (compare < 0)
-                            continue;
-                        core.upsertDocumentReviewSessionForSync({
-                            id: session.id,
-                            tenantId: core.getTenantId(),
-                            workspaceId,
-                            assetId: session.assetId,
-                            documentId: session.documentId,
-                            documentVersion: session.documentVersion,
-                            title: session.title,
-                            status: session.status,
-                            comments: [],
-                            createdByActorId: session.createdByActorId,
-                            updatedByActorId: session.updatedByActorId,
-                            createdAt: session.createdAt,
-                            updatedAt: session.updatedAt,
-                            deletedAt: session.deletedAt,
-                        });
-                    }
-                    catch (error) {
-                        const details = {
-                            source: 'apply.documentReviewUpsert',
-                            sessionId: session.id,
-                            error: String(error?.message || error || ''),
-                            errorCode: String(error?.code || '').trim() || null
-                        };
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert document review session during sync apply.', details);
-                        throw createSyncRouteError(`Failed to persist document review session ${session.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'DOCUMENT_REVIEW_SESSION_SYNC_APPLY_FAILED', statusCode: 500 });
-                    }
-                }
-            }
-            if (incomingDocumentReviewComments.size > 0) {
-                for (const comment of incomingDocumentReviewComments.values()) {
-                    try {
-                        const existingComments = core.listDocumentReviewCommentsForSync({
-                            workspaceId,
-                            includeDeleted: true
-                        });
-                        const existing = existingComments.find((entry) => entry.id === comment.id) || null;
-                        const incomingTieBreak = createHash('sha256')
-                            .update(JSON.stringify({ body: comment.body, anchor: comment.anchor, deletedAt: comment.deletedAt }))
-                            .digest('hex');
-                        const existingTieBreak = existing
-                            ? createHash('sha256')
-                                .update(JSON.stringify({ body: existing.body, anchor: existing.anchor, deletedAt: existing.deletedAt }))
-                                .digest('hex')
-                            : '';
-                        const compare = resolveConflictOrdering(comment.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
-                        if (compare < 0)
-                            continue;
-                        core.upsertDocumentReviewCommentForSync({
-                            id: comment.id,
-                            tenantId: core.getTenantId(),
-                            workspaceId,
-                            sessionId: comment.sessionId,
-                            body: comment.body,
-                            anchor: comment.anchor,
-                            order: comment.order,
-                            authorActorId: comment.authorActorId,
-                            createdAt: comment.createdAt,
-                            updatedAt: comment.updatedAt,
-                            deletedAt: comment.deletedAt,
-                        });
-                    }
-                    catch (error) {
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert document review comment during sync apply.', {
-                            source: 'apply.documentReviewCommentUpsert',
-                            commentId: comment.id,
-                            error: String(error?.message || error || '')
-                        });
-                        throw error;
-                    }
-                }
-            }
-            if (incomingDocumentReviewSessionDeletes.size > 0) {
-                for (const [sessionId, deletedAt] of incomingDocumentReviewSessionDeletes.entries()) {
-                    try {
-                        const existing = core.getDocumentReviewSession({
-                            workspaceId,
-                            sessionId,
-                            includeDeleted: true
-                        });
-                        const compare = resolveConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${sessionId}`, String(existing?.id || '').trim());
-                        if (existing && compare < 0)
-                            continue;
-                        core.deleteDocumentReviewSessionForSync({ workspaceId, sessionId, deletedAt });
-                    }
-                    catch (error) {
-                        const details = {
-                            source: 'apply.documentReviewDelete',
-                            sessionId,
-                            error: String(error?.message || error || ''),
-                            errorCode: String(error?.code || '').trim() || null
-                        };
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document review session during sync apply.', details);
-                        throw createSyncRouteError(`Failed to delete document review session ${sessionId} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'DOCUMENT_REVIEW_SESSION_SYNC_DELETE_FAILED', statusCode: 500 });
-                    }
-                }
-            }
-            if (incomingDocumentReviewCommentDeletes.size > 0) {
-                for (const [commentId, deletedAt] of incomingDocumentReviewCommentDeletes.entries()) {
-                    try {
-                        const existing = core.listDocumentReviewCommentsForSync({
-                            workspaceId,
-                            includeDeleted: true
-                        }).find((entry) => entry.id === commentId) || null;
-                        const compare = resolveConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${commentId}`, String(existing?.id || '').trim());
-                        if (existing && compare < 0)
-                            continue;
-                        core.deleteDocumentReviewCommentForSync({ workspaceId, commentId, deletedAt });
-                    }
-                    catch (error) {
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document review comment during sync apply.', {
-                            source: 'apply.documentReviewCommentDelete',
-                            commentId,
-                            error: String(error?.message || error || '')
-                        });
-                        throw error;
-                    }
-                }
-            }
-            if (incomingAnnotatedAttachmentSessions.size > 0) {
-                for (const session of incomingAnnotatedAttachmentSessions.values()) {
-                    try {
-                        const existing = core.getAnnotatedAttachmentSession({
-                            workspaceId,
-                            sessionId: session.id,
-                            includeDeleted: true
-                        });
-                        const incomingTieBreak = createHash('sha256').update(JSON.stringify(session.annotations || [])).digest('hex');
-                        const existingTieBreak = existing
-                            ? createHash('sha256').update(JSON.stringify(existing.annotations || [])).digest('hex')
-                            : '';
-                        const compare = resolveConflictOrdering(session.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
-                        if (compare < 0)
-                            continue;
-                        core.upsertAnnotatedAttachmentSessionForSync({
-                            id: session.id,
-                            tenantId: core.getTenantId(),
-                            workspaceId,
-                            taskId: session.taskId,
-                            baseImageAssetId: session.baseImageAssetId,
-                            title: session.title,
-                            globalInstruction: session.globalInstruction,
-                            annotations: session.annotations,
-                            createdByActorId: session.createdByActorId,
-                            updatedByActorId: session.updatedByActorId,
-                            createdAt: session.createdAt,
-                            updatedAt: session.updatedAt,
-                            deletedAt: session.deletedAt,
-                        });
-                    }
-                    catch (error) {
-                        const details = {
-                            source: 'apply.annotatedAttachmentUpsert',
-                            sessionId: session.id,
-                            error: String(error?.message || error || ''),
-                            errorCode: String(error?.code || '').trim() || null
-                        };
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert annotated attachment session during sync apply.', details);
-                        throw createSyncRouteError(`Failed to persist annotated attachment session ${session.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'ANNOTATED_ATTACHMENT_SESSION_SYNC_APPLY_FAILED', statusCode: 500 });
-                    }
-                }
-            }
-            if (incomingAnnotatedAttachmentSessionDeletes.size > 0) {
-                for (const [sessionId, deletedAt] of incomingAnnotatedAttachmentSessionDeletes.entries()) {
-                    try {
-                        const existing = core.getAnnotatedAttachmentSession({
-                            workspaceId,
-                            sessionId,
-                            includeDeleted: true
-                        });
-                        const compare = resolveConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${sessionId}`, String(existing?.id || '').trim());
-                        if (existing && compare < 0)
-                            continue;
-                        core.deleteAnnotatedAttachmentSessionForSync({ workspaceId, sessionId, deletedAt });
-                    }
-                    catch (error) {
-                        const details = {
-                            source: 'apply.annotatedAttachmentDelete',
-                            sessionId,
-                            error: String(error?.message || error || ''),
-                            errorCode: String(error?.code || '').trim() || null
-                        };
-                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete annotated attachment session during sync apply.', details);
-                        throw createSyncRouteError(`Failed to delete annotated attachment session ${sessionId} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'ANNOTATED_ATTACHMENT_SESSION_SYNC_DELETE_FAILED', statusCode: 500 });
-                    }
-                }
-            }
-            if (incomingDocuments.length > 0 || incomingAssets.length > 0) {
-                core.notifyDocumentMetadataMutation(workspaceId, [
-                    ...incomingDocuments.map((entry) => entry.path),
-                    ...incomingAssets.map((entry) => entry.path)
-                ], 'upsert');
-            }
-            if (incomingDocumentDeletes.size > 0 || incomingAssetDeletes.size > 0) {
-                core.notifyDocumentMetadataMutation(workspaceId, [
-                    ...Array.from(incomingDocumentDeletes.keys()),
-                    ...Array.from(incomingAssetDeletes.keys())
-                ], 'delete');
-            }
-            const result = core.applyWorkspaceSyncSnapshot({ tasks, archived }, workspaceId);
+            await applyContentSyncChanges({
+                core,
+                workspaceId,
+                incomingDocuments,
+                incomingDocumentDeletes,
+                incomingAssets,
+                incomingAssetDeletes,
+                basePath: core.getPaths().basePath,
+                hasObjectStorageClient: () => Boolean(getObjectStorageClient()),
+                hasDocumentSyncMetadataDrift: contentSyncState.hasDocumentSyncMetadataDrift,
+                hasBinaryAssetSyncMetadataDrift: contentSyncState.hasBinaryAssetSyncMetadataDrift,
+                writeWorkspaceSyncDocument: contentSyncState.writeWorkspaceSyncDocument,
+                deleteWorkspaceSyncDocument: contentSyncState.deleteWorkspaceSyncDocument,
+                writeWorkspaceSyncBinaryAsset: contentSyncState.writeWorkspaceSyncBinaryAsset,
+                deleteWorkspaceSyncBinaryAsset: contentSyncState.deleteWorkspaceSyncBinaryAsset,
+                getExistingBinaryAsset: (assetPath, targetWorkspaceId) => workspaceAssetStore?.getByStorageKey(assetPath, targetWorkspaceId) || null,
+                recordSyncDiagnostic,
+                options,
+            });
+            applyCollaborationSyncChanges({
+                core,
+                workspaceId,
+                incomingDocumentReviewSessions,
+                incomingDocumentReviewSessionDeletes,
+                incomingDocumentReviewComments,
+                incomingDocumentReviewCommentDeletes,
+                incomingAnnotatedAttachmentSessions,
+                incomingAnnotatedAttachmentSessionDeletes,
+                recordSyncDiagnostic,
+                createSyncRouteError,
+            });
+            const result = core.applyWorkspaceSyncSnapshot({
+                tasks: tasks.map(taskSyncPayloadToCoreTask),
+                archived: archived.map(taskSyncPayloadToCoreTask)
+            }, workspaceId);
             return { result, deleteCount: incomingTaskDeletes.size, emittedEventIds: Array.from(emittedEventIds) };
         }
         finally {
@@ -2000,135 +734,62 @@ export function registerSyncRoutes(deps) {
         const incomingAssets = Array.isArray(body?.assets) ? body.assets : [];
         try {
             const bootstrapChanges = [
-                ...((incomingTaxonomyState || incomingTaxonomies) ? [{
+                ...((incomingTaxonomyState || incomingTaxonomies)
+                    ? [normalizeTaxonomySyncPayload({
+                            taxonomies: incomingTaxonomies,
+                            taxonomyState: incomingTaxonomyState || undefined,
+                            updatedAt: new Date().toISOString()
+                        })]
+                        .filter((entry) => Boolean(entry))
+                        .map((entry) => ({
                         op: 'taxonomy-upsert',
-                        taxonomies: incomingTaxonomies,
-                        taxonomyState: incomingTaxonomyState || undefined,
-                        updatedAt: new Date().toISOString()
-                    }] : []),
+                        taxonomies: entry.taxonomies,
+                        taxonomyState: entry.taxonomyState,
+                        updatedAt: entry.updatedAt
+                    }))
+                    : []),
                 ...incomingInitiatives
+                    .map((initiative) => normalizeInitiativeSyncPayload(initiative))
+                    .filter((initiative) => Boolean(initiative && initiative.id.length > 0))
                     .map((initiative) => ({
                     op: 'initiative-upsert',
-                    initiative: {
-                        id: String(initiative?.id || '').trim(),
-                        referenceNumber: Number.isFinite(Number(initiative?.referenceNumber))
-                            ? Math.max(1, Math.floor(Number(initiative.referenceNumber)))
-                            : null,
-                        referenceLabel: typeof initiative?.referenceLabel === 'string' ? initiative.referenceLabel.trim() : undefined,
-                        title: String(initiative?.title || '').trim(),
-                        description: typeof initiative?.description === 'string' ? initiative.description : null,
-                        ownerId: typeof initiative?.ownerId === 'string' ? initiative.ownerId.trim() : null,
-                        createdAt: String(initiative?.createdAt || '').trim(),
-                        updatedAt: String(initiative?.updatedAt || initiative?.createdAt || '').trim(),
-                        order: Number.isFinite(Number(initiative?.order)) ? Math.floor(Number(initiative.order)) : null,
-                        isArchived: Boolean(initiative?.isArchived)
-                    }
-                }))
-                    .filter((change) => change.initiative.id.length > 0),
+                    initiative
+                })),
                 ...incomingWorkstreams
+                    .map((workstream) => normalizeWorkstreamSyncPayload(workstream))
+                    .filter((workstream) => Boolean(workstream && workstream.id.length > 0))
                     .map((workstream) => ({
                     op: 'workstream-upsert',
-                    workstream: {
-                        id: String(workstream?.id || '').trim(),
-                        referenceNumber: Number.isFinite(Number(workstream?.referenceNumber))
-                            ? Math.max(1, Math.floor(Number(workstream.referenceNumber)))
-                            : null,
-                        referenceLabel: typeof workstream?.referenceLabel === 'string' ? workstream.referenceLabel.trim() : undefined,
-                        initiativeId: typeof workstream?.initiativeId === 'string' ? workstream.initiativeId.trim() : null,
-                        title: String(workstream?.title || '').trim(),
-                        description: typeof workstream?.description === 'string' ? workstream.description : null,
-                        ownerId: typeof workstream?.ownerId === 'string' ? workstream.ownerId.trim() : null,
-                        createdAt: String(workstream?.createdAt || '').trim(),
-                        updatedAt: String(workstream?.updatedAt || workstream?.createdAt || '').trim(),
-                        order: Number.isFinite(Number(workstream?.order)) ? Math.floor(Number(workstream.order)) : null,
-                        isArchived: Boolean(workstream?.isArchived)
-                    }
-                }))
-                    .filter((change) => change.workstream.id.length > 0),
+                    workstream
+                })),
                 ...incomingAiProfiles
+                    .map((profile) => normalizeAiProfileSyncPayload(profile, cloudWorkspaceId, normalizeIncomingAiProfileSurfaceType, 'push.aiProfileUpsert'))
+                    .filter((profile) => Boolean(profile && profile.id.length > 0))
                     .map((profile) => ({
                     op: 'ai-profile-upsert',
-                    profile: {
-                        id: String(profile?.id || '').trim(),
-                        workspaceId: cloudWorkspaceId,
-                        profileToken: String(profile?.profileToken || '').trim(),
-                        name: String(profile?.name || '').trim(),
-                        username: String(profile?.username || '').trim(),
-                        icon: String(profile?.icon || 'Bot').trim() || 'Bot',
-                        color: String(profile?.color || '#8b5cf6').trim() || '#8b5cf6',
-                        surfaceType: normalizeIncomingAiProfileSurfaceType(profile?.surfaceType, {
-                            source: 'push.aiProfileUpsert',
-                            profileId: String(profile?.id || '').trim(),
-                            workspaceId: cloudWorkspaceId
-                        }),
-                        providerMetadata: profile?.providerMetadata && typeof profile.providerMetadata === 'object' && !Array.isArray(profile.providerMetadata)
-                            ? profile.providerMetadata
-                            : null,
-                        createdAt: String(profile?.createdAt || '').trim(),
-                        updatedAt: String(profile?.updatedAt || profile?.createdAt || '').trim(),
-                        lastActiveAt: typeof profile?.lastActiveAt === 'string' && profile.lastActiveAt.trim().length > 0
-                            ? profile.lastActiveAt.trim()
-                            : null
-                    }
-                }))
-                    .filter((change) => change.profile.id.length > 0),
+                    profile: { ...profile, workspaceId: cloudWorkspaceId }
+                })),
                 ...incomingDocuments
+                    .map((doc) => serializeDocumentSyncPayload(doc))
+                    .filter((doc) => Boolean(doc && doc.path.length > 0))
                     .map((doc) => ({
                     op: 'document-upsert',
-                    path: String(doc?.path || '').trim(),
-                    updatedAt: String(doc?.updatedAt || '').trim(),
-                    content: typeof doc?.content === 'string' ? doc.content : '',
-                    assetId: typeof doc?.assetId === 'string' ? doc.assetId.trim() : undefined,
-                    documentId: typeof doc?.documentId === 'string' ? doc.documentId.trim() : null,
-                    referenceNumber: Number.isFinite(Number(doc?.referenceNumber)) ? Math.max(1, Math.floor(Number(doc.referenceNumber))) : null,
-                    version: Number.isFinite(Number(doc?.version)) ? Math.max(1, Math.floor(Number(doc.version))) : null,
-                    taskId: typeof doc?.taskId === 'string' ? doc.taskId.trim() : null,
-                    logicalName: typeof doc?.logicalName === 'string' ? doc.logicalName.trim() : null,
-                    caption: typeof doc?.caption === 'string' ? doc.caption.trim() : null,
-                    originalFilename: typeof doc?.originalFilename === 'string' ? doc.originalFilename.trim() : null,
-                    linkRole: (doc?.linkRole === 'reference' ? 'reference' : 'attachment')
-                }))
-                    .filter((doc) => doc.path.length > 0),
+                    ...doc
+                })),
                 ...incomingAssets
+                    .map((asset) => serializeBinaryAssetSyncPayload(asset))
+                    .filter((asset) => Boolean(asset && asset.path.length > 0 && asset.contentBase64.length > 0))
                     .map((asset) => ({
                     op: 'asset-upsert',
-                    path: String(asset?.path || '').trim(),
-                    updatedAt: String(asset?.updatedAt || '').trim(),
-                    contentBase64: typeof asset?.contentBase64 === 'string' ? asset.contentBase64 : '',
-                    assetId: typeof asset?.assetId === 'string' ? asset.assetId.trim() : undefined,
-                    kind: asset?.kind === 'image' ? 'image' : 'file',
-                    mimeType: typeof asset?.mimeType === 'string' ? asset.mimeType.trim() : 'application/octet-stream',
-                    referenceNumber: Number.isFinite(Number(asset?.referenceNumber)) ? Math.max(1, Math.floor(Number(asset.referenceNumber))) : null,
-                    taskId: typeof asset?.taskId === 'string' ? asset.taskId.trim() : null,
-                    logicalName: typeof asset?.logicalName === 'string' ? asset.logicalName.trim() : null,
-                    caption: typeof asset?.caption === 'string' ? asset.caption.trim() : null,
-                    originalFilename: typeof asset?.originalFilename === 'string' ? asset.originalFilename.trim() : null,
-                    linkRole: asset?.linkRole === 'reference'
-                        ? 'reference'
-                        : asset?.kind === 'image'
-                            ? 'image'
-                            : 'attachment'
-                }))
-                    .filter((asset) => asset.path.length > 0 && asset.contentBase64.length > 0),
+                    ...asset
+                })),
                 ...incomingDocumentReviewSessions
+                    .map((session) => normalizeDocumentReviewSessionSyncPayload(session))
+                    .filter((session) => Boolean(session && session.id.length > 0 && session.assetId.length > 0))
                     .map((session) => ({
                     op: 'document-review-session-upsert',
-                    session: {
-                        id: String(session?.id || '').trim(),
-                        assetId: String(session?.assetId || '').trim(),
-                        documentId: typeof session?.documentId === 'string' ? session.documentId.trim() : null,
-                        documentVersion: Number.isFinite(Number(session?.documentVersion)) ? Math.max(1, Math.floor(Number(session.documentVersion))) : null,
-                        title: typeof session?.title === 'string' ? session.title.trim() : null,
-                        status: session?.status === 'resolved' ? 'resolved' : 'open',
-                        comments: [],
-                        createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
-                        updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
-                        createdAt: String(session?.createdAt || '').trim(),
-                        updatedAt: String(session?.updatedAt || session?.createdAt || '').trim(),
-                        deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null
-                    }
-                }))
-                    .filter((change) => change.session.id.length > 0 && change.session.assetId.length > 0),
+                    session: { ...session, comments: [] }
+                })),
                 ...(incomingDocumentReviewComments.length > 0
                     ? incomingDocumentReviewComments
                     : incomingDocumentReviewSessions.flatMap((session) => {
@@ -2144,43 +805,22 @@ export function registerSyncRoutes(deps) {
                     const sessionId = isLegacyNested
                         ? String(entry.sessionId || '').trim()
                         : String(comment?.sessionId || '').trim();
-                    return {
-                        op: 'document-review-comment-upsert',
-                        comment: {
-                            id: String(comment?.id || '').trim(),
-                            sessionId,
-                            body: typeof comment?.body === 'string' ? comment.body : '',
-                            anchor: comment?.anchor ?? null,
-                            order: Number.isFinite(Number(comment?.order)) ? Math.max(0, Math.floor(Number(comment?.order))) : 0,
-                            authorActorId: typeof comment?.authorActorId === 'string' ? comment.authorActorId.trim() : null,
-                            createdAt: String(comment?.createdAt || '').trim(),
-                            updatedAt: String(comment?.updatedAt || comment?.createdAt || '').trim(),
-                            deletedAt: typeof comment?.deletedAt === 'string' && comment.deletedAt.trim().length > 0 ? comment.deletedAt.trim() : null,
+                    const normalized = normalizeDocumentReviewCommentSyncPayload(comment, { sessionId });
+                    return normalized
+                        ? {
+                            op: 'document-review-comment-upsert',
+                            comment: normalized
                         }
-                    };
+                        : null;
                 })
-                    .filter((change) => change.comment.id.length > 0 && change.comment.sessionId.length > 0),
+                    .filter((change) => Boolean(change && change.comment.id.length > 0 && change.comment.sessionId.length > 0)),
                 ...incomingAnnotatedAttachmentSessions
+                    .map((session) => normalizeAnnotatedAttachmentSessionSyncPayload(session, cloudWorkspaceId))
+                    .filter((session) => Boolean(session && session.id.length > 0 && session.workspaceId.length > 0 && session.baseImageAssetId.length > 0))
                     .map((session) => ({
                     op: 'annotated-attachment-session-upsert',
-                    session: {
-                        id: String(session?.id || '').trim(),
-                        workspaceId: cloudWorkspaceId,
-                        taskId: typeof session?.taskId === 'string' ? session.taskId.trim() : '',
-                        baseImageAssetId: typeof session?.baseImageAssetId === 'string' ? session.baseImageAssetId.trim() : '',
-                        title: typeof session?.title === 'string' ? session.title.trim() : null,
-                        globalInstruction: typeof session?.globalInstruction === 'string' ? session.globalInstruction.trim() : null,
-                        annotations: Array.isArray(session?.annotations) ? session.annotations : [],
-                        createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
-                        updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
-                        createdAt: String(session?.createdAt || '').trim(),
-                        updatedAt: String(session?.updatedAt || session?.createdAt || '').trim(),
-                        deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null
-                    }
-                }))
-                    .filter((change) => (change.session.id.length > 0
-                    && change.session.workspaceId.length > 0
-                    && change.session.baseImageAssetId.length > 0)),
+                    session
+                })),
                 ...tasks.map((task) => ({ op: 'upsert', archived: false, task })),
                 ...archived.map((task) => ({ op: 'upsert', archived: true, task }))
             ];
@@ -2235,7 +875,7 @@ export function registerSyncRoutes(deps) {
         }
         const workspaceId = requestWorkspaceId(req) || 'default';
         const basePath = core.getPaths().basePath;
-        const documents = await listWorkspaceSyncDocumentsSnapshot(basePath, workspaceId);
+        const documents = await contentSyncState.listWorkspaceSyncDocumentsSnapshot(basePath, workspaceId);
         const fingerprint = JSON.stringify(documents.map((doc) => [
             doc.path,
             doc.updatedAt,
@@ -2293,8 +933,8 @@ export function registerSyncRoutes(deps) {
             }
         }
         const workspaceId = requestWorkspaceId(req) || 'default';
-        const sessions = listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId);
-        const comments = listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId);
+        const sessions = collaborationSyncState.listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId);
+        const comments = collaborationSyncState.listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId);
         const fingerprint = JSON.stringify([
             ...sessions.map((session) => [
                 'session',
@@ -2331,7 +971,7 @@ export function registerSyncRoutes(deps) {
             }
         }
         const workspaceId = requestWorkspaceId(req) || 'default';
-        const sessions = listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId);
+        const sessions = collaborationSyncState.listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId);
         const fingerprint = JSON.stringify(sessions.map((session) => [
             session.id,
             session.updatedAt,
@@ -2361,7 +1001,7 @@ export function registerSyncRoutes(deps) {
         }
         const workspaceId = requestWorkspaceId(req) || 'default';
         const basePath = core.getPaths().basePath;
-        const assets = await listWorkspaceSyncBinaryAssetsSnapshot(basePath, workspaceId);
+        const assets = await contentSyncState.listWorkspaceSyncBinaryAssetsSnapshot(basePath, workspaceId);
         const fingerprint = JSON.stringify(assets.map((asset) => [
             asset.path,
             asset.updatedAt,
@@ -2428,379 +1068,30 @@ export function registerSyncRoutes(deps) {
         const pageSize = Number.isFinite(requestedLimit) && requestedLimit > 0
             ? Math.max(1, Math.min(500, Math.floor(requestedLimit)))
             : 200;
-        // Use watermark-indexed queries to avoid full table scans (Finding 12).
-        // Fetch up to pageSize * 2 tasks/deletes from DB since the cursor, then merge with
-        // small in-memory collections (taxonomy, documents) before slicing to pageSize.
-        const syncCursor = cursor ? { watermark: cursor.u, id: cursor.id } : null;
-        const dbFetchLimit = pageSize * 2 + 10;
-        const taskRows = core.listTasksForSync(targetWorkspaceId, syncCursor, dbFetchLimit);
-        const upsertEntries = taskRows
-            .map((entry) => {
-            const watermark = String(entry.task?.updatedAt || entry.task?.createdAt || '').trim();
-            const taskId = String(entry.task?.id || '').trim();
-            return {
-                kind: 'upsert',
-                watermark,
-                sortId: taskId,
-                task: entry.task,
-                archived: Boolean(entry.archived)
-            };
-        })
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
-        const rawDeleteEntries = core.listWorkspaceSyncDeletesSince(targetWorkspaceId, syncCursor, dbFetchLimit);
-        const deleteEntries = rawDeleteEntries
-            .map((entry) => ({
-            kind: 'delete',
-            watermark: String(entry.deletedAt || '').trim(),
-            sortId: String(entry.taskId || '').trim(),
-            taskId: String(entry.taskId || '').trim()
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
-        const taxonomySnapshot = core.getTaxonomiesSyncSnapshot(targetWorkspaceId);
-        const taxonomyEntries = (taxonomySnapshot
-            && Array.isArray(taxonomySnapshot.taxonomies)
-            && Number.isFinite(Date.parse(String(taxonomySnapshot.updatedAt || '').trim())))
-            ? [{
-                    kind: 'taxonomy',
-                    watermark: String(taxonomySnapshot.updatedAt || '').trim(),
-                    sortId: '__taxonomy_config__',
-                    taxonomies: taxonomySnapshot.taxonomies,
-                    taxonomyState: taxonomySnapshot.taxonomyState || null
-                }]
-            : [];
-        const initiativeEntries = core.listInitiatives(targetWorkspaceId)
-            .map((initiative) => ({
-            kind: 'initiative',
-            watermark: String(initiative.updatedAt || initiative.createdAt || '').trim(),
-            sortId: `initiative:${String(initiative.id || '').trim()}`,
-            initiative
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.initiative.id.length > 0);
-        const workstreamEntries = core.listWorkstreams(targetWorkspaceId)
-            .map((workstream) => ({
-            kind: 'workstream',
-            watermark: String(workstream.updatedAt || workstream.createdAt || '').trim(),
-            sortId: `workstream:${String(workstream.id || '').trim()}`,
-            workstream
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.workstream.id.length > 0);
-        const aiProfileEntries = core.listAiProfiles(targetWorkspaceId)
-            .map((profile) => ({
-            kind: 'ai-profile',
-            watermark: String(profile.updatedAt || profile.createdAt || '').trim(),
-            sortId: `ai-profile:${String(profile.id || '').trim()}`,
-            profile
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
-        const documentEntries = (await listWorkspaceSyncDocumentsSnapshot(core.getPaths().basePath, targetWorkspaceId))
-            .map((doc) => ({
-            kind: 'document',
-            watermark: String(doc.updatedAt || '').trim(),
-            sortId: `doc:${String(doc.path || '').trim()}`,
-            path: String(doc.path || '').trim(),
-            content: String(doc.content || ''),
-            assetId: doc.assetId,
-            documentId: doc.documentId,
-            referenceNumber: doc.referenceNumber,
-            version: doc.version,
-            taskId: doc.taskId,
-            logicalName: doc.logicalName,
-            caption: doc.caption,
-            originalFilename: doc.originalFilename,
-            linkRole: doc.linkRole
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
-        const documentDeleteEntries = listWorkspaceSyncDocumentDeletesSnapshot(targetWorkspaceId)
-            .map((doc) => ({
-            kind: 'document-delete',
-            watermark: String(doc.deletedAt || '').trim(),
-            sortId: `doc-delete:${String(doc.path || '').trim()}:${String(doc.assetId || '').trim()}`,
-            path: String(doc.path || '').trim(),
-            assetId: typeof doc.assetId === 'string' && doc.assetId.trim().length > 0 ? doc.assetId.trim() : undefined
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
-        const documentReviewSessionEntries = listWorkspaceSyncDocumentReviewSessionsSnapshot(targetWorkspaceId)
-            .filter((session) => !session.deletedAt)
-            .map((session) => ({
-            kind: 'document-review-session',
-            watermark: String(session.updatedAt || session.createdAt || '').trim(),
-            sortId: `document-review-session:${String(session.id || '').trim()}`,
-            session
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.session.id.length > 0 && entry.session.assetId.length > 0);
-        const documentReviewSessionDeleteEntries = listWorkspaceSyncDocumentReviewSessionsSnapshot(targetWorkspaceId)
-            .filter((session) => typeof session.deletedAt === 'string' && session.deletedAt.trim().length > 0)
-            .map((session) => ({
-            kind: 'document-review-session-delete',
-            watermark: String(session.deletedAt || session.updatedAt || '').trim(),
-            sortId: `document-review-session-delete:${String(session.id || '').trim()}`,
-            sessionId: String(session.id || '').trim()
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sessionId.length > 0);
-        const documentReviewCommentEntries = listWorkspaceSyncDocumentReviewCommentsSnapshot(targetWorkspaceId)
-            .filter((comment) => !comment.deletedAt)
-            .map((comment) => ({
-            kind: 'document-review-comment',
-            watermark: String(comment.updatedAt || comment.createdAt || '').trim(),
-            sortId: `document-review-comment:${String(comment.id || '').trim()}`,
-            comment
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.comment.id.length > 0 && entry.comment.sessionId.length > 0);
-        const documentReviewCommentDeleteEntries = listWorkspaceSyncDocumentReviewCommentsSnapshot(targetWorkspaceId)
-            .filter((comment) => typeof comment.deletedAt === 'string' && comment.deletedAt.trim().length > 0)
-            .map((comment) => ({
-            kind: 'document-review-comment-delete',
-            watermark: String(comment.deletedAt || comment.updatedAt || '').trim(),
-            sortId: `document-review-comment-delete:${String(comment.id || '').trim()}`,
-            commentId: String(comment.id || '').trim()
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.commentId.length > 0);
-        const annotatedAttachmentSessionEntries = listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(targetWorkspaceId)
-            .filter((session) => !session.deletedAt)
-            .map((session) => ({
-            kind: 'annotated-attachment-session',
-            watermark: String(session.updatedAt || session.createdAt || '').trim(),
-            sortId: `annotated-attachment-session:${String(session.id || '').trim()}`,
-            session
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.session.id.length > 0 && entry.session.baseImageAssetId.length > 0);
-        const annotatedAttachmentSessionDeleteEntries = listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(targetWorkspaceId)
-            .filter((session) => typeof session.deletedAt === 'string' && session.deletedAt.trim().length > 0)
-            .map((session) => ({
-            kind: 'annotated-attachment-session-delete',
-            watermark: String(session.deletedAt || session.updatedAt || '').trim(),
-            sortId: `annotated-attachment-session-delete:${String(session.id || '').trim()}`,
-            sessionId: String(session.id || '').trim()
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sessionId.length > 0);
-        const assetEntries = (await listWorkspaceSyncBinaryAssetsSnapshot(core.getPaths().basePath, targetWorkspaceId))
-            .map((asset) => ({
-            kind: 'asset',
-            watermark: String(asset.updatedAt || '').trim(),
-            sortId: `asset:${String(asset.path || '').trim()}`,
-            path: String(asset.path || '').trim(),
-            contentBase64: String(asset.contentBase64 || ''),
-            assetId: asset.assetId,
-            kindValue: asset.kind,
-            mimeType: asset.mimeType,
-            referenceNumber: asset.referenceNumber,
-            taskId: asset.taskId,
-            logicalName: asset.logicalName,
-            caption: asset.caption,
-            originalFilename: asset.originalFilename,
-            linkRole: asset.linkRole
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0 && entry.contentBase64.length > 0);
-        const assetDeleteEntries = listWorkspaceSyncBinaryAssetDeletesSnapshot(targetWorkspaceId)
-            .map((asset) => ({
-            kind: 'asset-delete',
-            watermark: String(asset.deletedAt || '').trim(),
-            sortId: `asset-delete:${String(asset.path || '').trim()}:${String(asset.assetId || '').trim()}`,
-            path: String(asset.path || '').trim(),
-            assetId: typeof asset.assetId === 'string' && asset.assetId.trim().length > 0 ? asset.assetId.trim() : undefined
-        }))
-            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
-        const all = [
-            ...upsertEntries,
-            ...deleteEntries,
-            ...taxonomyEntries,
-            ...initiativeEntries,
-            ...workstreamEntries,
-            ...aiProfileEntries,
-            ...documentEntries,
-            ...documentDeleteEntries,
-            ...documentReviewSessionEntries,
-            ...documentReviewSessionDeleteEntries,
-            ...documentReviewCommentEntries,
-            ...documentReviewCommentDeleteEntries,
-            ...annotatedAttachmentSessionEntries,
-            ...annotatedAttachmentSessionDeleteEntries,
-            ...assetEntries,
-            ...assetDeleteEntries
-        ];
-        const afterCursor = all.filter((entry) => {
-            if (!cursor)
-                return true;
-            const watermark = entry.watermark;
-            const sortId = entry.sortId;
-            if (watermark > cursor.u)
-                return true;
-            if (watermark < cursor.u)
-                return false;
-            return sortId > cursor.id;
-        });
-        afterCursor.sort((a, b) => {
-            if (a.watermark !== b.watermark)
-                return a.watermark.localeCompare(b.watermark);
-            return String(a.sortId || '').localeCompare(String(b.sortId || ''));
-        });
-        const page = afterCursor.slice(0, pageSize);
-        const hasMore = afterCursor.length > pageSize;
-        const last = page.length > 0 ? page[page.length - 1] : null;
-        const nextCursor = encodeWorkspaceSyncCursor(last
-            ? { u: last.watermark, id: String(last.sortId || '') }
-            : cursor);
-        const workspaceMembers = core.listWorkspaceUsers(targetWorkspaceId).map((member) => ({
-            userId: member.userId,
+        const { workspaceMembers, changes, nextCursor, hasMore, diagnostics } = await buildWorkspacePullFeed({
+            core,
             workspaceId: targetWorkspaceId,
-            email: member.email,
-            displayName: member.displayName || null,
-            role: member.role,
-            permissionMode: member.permissionMode,
-            betaAccess: member.betaAccess,
-            status: member.status,
-            disabled: member.disabled,
-            createdAt: member.createdAt || null,
-            updatedAt: member.updatedAt || null,
-            emailVerifiedAt: member.emailVerifiedAt || null
-        }));
+            cursor,
+            pageSize,
+            encodeWorkspaceSyncCursor,
+            contentSyncState,
+            collaborationSyncState,
+        });
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
             success: true,
             workspaceId: targetWorkspaceId,
             workspaceMembers,
-            changes: page.map((entry) => (entry.kind === 'delete'
-                ? {
-                    op: 'delete',
-                    taskId: entry.taskId,
-                    deletedAt: entry.watermark,
-                    watermark: entry.watermark
-                }
-                : entry.kind === 'taxonomy'
-                    ? {
-                        op: 'taxonomy-upsert',
-                        taxonomies: entry.taxonomies,
-                        taxonomyState: entry.taxonomyState,
-                        watermark: entry.watermark
-                    }
-                    : entry.kind === 'initiative'
-                        ? {
-                            op: 'initiative-upsert',
-                            initiative: entry.initiative,
-                            updatedAt: entry.watermark,
-                            watermark: entry.watermark
-                        }
-                        : entry.kind === 'workstream'
-                            ? {
-                                op: 'workstream-upsert',
-                                workstream: entry.workstream,
-                                updatedAt: entry.watermark,
-                                watermark: entry.watermark
-                            }
-                            : entry.kind === 'ai-profile'
-                                ? {
-                                    op: 'ai-profile-upsert',
-                                    profile: entry.profile,
-                                    updatedAt: entry.watermark,
-                                    watermark: entry.watermark
-                                }
-                                : entry.kind === 'document-review-session'
-                                    ? {
-                                        op: 'document-review-session-upsert',
-                                        session: entry.session,
-                                        updatedAt: entry.watermark,
-                                        watermark: entry.watermark
-                                    }
-                                    : entry.kind === 'document-review-session-delete'
-                                        ? {
-                                            op: 'document-review-session-delete',
-                                            sessionId: entry.sessionId,
-                                            deletedAt: entry.watermark,
-                                            watermark: entry.watermark
-                                        }
-                                        : entry.kind === 'document-review-comment'
-                                            ? {
-                                                op: 'document-review-comment-upsert',
-                                                comment: entry.comment,
-                                                updatedAt: entry.watermark,
-                                                watermark: entry.watermark
-                                            }
-                                            : entry.kind === 'document-review-comment-delete'
-                                                ? {
-                                                    op: 'document-review-comment-delete',
-                                                    commentId: entry.commentId,
-                                                    deletedAt: entry.watermark,
-                                                    watermark: entry.watermark
-                                                }
-                                                : entry.kind === 'annotated-attachment-session'
-                                                    ? {
-                                                        op: 'annotated-attachment-session-upsert',
-                                                        session: entry.session,
-                                                        updatedAt: entry.watermark,
-                                                        watermark: entry.watermark
-                                                    }
-                                                    : entry.kind === 'annotated-attachment-session-delete'
-                                                        ? {
-                                                            op: 'annotated-attachment-session-delete',
-                                                            sessionId: entry.sessionId,
-                                                            deletedAt: entry.watermark,
-                                                            watermark: entry.watermark
-                                                        }
-                                                        // Keep markdown and binary assets on separate ops so the protocol stays explicit:
-                                                        // document-* carries markdown content + document identity, asset-* carries image/file bytes.
-                                                        : entry.kind === 'document'
-                                                            ? {
-                                                                op: 'document-upsert',
-                                                                path: entry.path,
-                                                                updatedAt: entry.watermark,
-                                                                content: entry.content,
-                                                                assetId: entry.assetId,
-                                                                documentId: entry.documentId,
-                                                                referenceNumber: entry.referenceNumber,
-                                                                version: entry.version,
-                                                                taskId: entry.taskId,
-                                                                logicalName: entry.logicalName,
-                                                                caption: entry.caption,
-                                                                originalFilename: entry.originalFilename,
-                                                                linkRole: entry.linkRole,
-                                                                watermark: entry.watermark
-                                                            }
-                                                            : entry.kind === 'document-delete'
-                                                                ? {
-                                                                    op: 'document-delete',
-                                                                    path: entry.path,
-                                                                    assetId: entry.assetId,
-                                                                    deletedAt: entry.watermark,
-                                                                    watermark: entry.watermark
-                                                                }
-                                                                : entry.kind === 'asset'
-                                                                    ? {
-                                                                        op: 'asset-upsert',
-                                                                        path: entry.path,
-                                                                        updatedAt: entry.watermark,
-                                                                        contentBase64: entry.contentBase64,
-                                                                        assetId: entry.assetId,
-                                                                        kind: entry.kindValue,
-                                                                        mimeType: entry.mimeType,
-                                                                        referenceNumber: entry.referenceNumber,
-                                                                        taskId: entry.taskId,
-                                                                        logicalName: entry.logicalName,
-                                                                        caption: entry.caption,
-                                                                        originalFilename: entry.originalFilename,
-                                                                        linkRole: entry.linkRole,
-                                                                        watermark: entry.watermark
-                                                                    }
-                                                                    : entry.kind === 'asset-delete'
-                                                                        ? {
-                                                                            op: 'asset-delete',
-                                                                            path: entry.path,
-                                                                            assetId: entry.assetId,
-                                                                            deletedAt: entry.watermark,
-                                                                            watermark: entry.watermark
-                                                                        }
-                                                                        : {
-                                                                            op: 'upsert',
-                                                                            task: entry.task,
-                                                                            archived: Boolean(entry.archived),
-                                                                            watermark: entry.watermark
-                                                                        })),
+            changes,
             nextCursor,
-            hasMore
+            hasMore,
+            diagnostics
         }));
         auditAuthAction(req, 'sync-workspace-pull-success', {
             workspaceId: targetWorkspaceId,
-            returnedChanges: page.length,
-            hasMore
+            returnedChanges: changes.length,
+            hasMore,
+            diagnostics
         });
     });
     // POST /api/taskforce/sync/workspace/apply-local - Apply pulled cloud deltas into local workspace store
@@ -2995,6 +1286,27 @@ export function registerSyncRoutes(deps) {
             }
             incomingChanges = decryptedChanges;
         }
+        const receivedAtBaseMs = Date.now();
+        incomingChanges = incomingChanges.map((change, index) => {
+            if (change.op !== 'upsert')
+                return change;
+            const task = change.task;
+            const rawReferenceNumber = task.referenceNumber;
+            const incomingReferenceNumber = rawReferenceNumber === undefined || rawReferenceNumber === null
+                ? null
+                : (Number.isFinite(Number(rawReferenceNumber))
+                    ? Math.max(1, Math.floor(Number(rawReferenceNumber)))
+                    : null);
+            if (incomingReferenceNumber)
+                return change;
+            return {
+                ...change,
+                task: {
+                    ...task,
+                    updatedAt: new Date(receivedAtBaseMs + index).toISOString()
+                }
+            };
+        });
         try {
             const { result, deleteCount, emittedEventIds } = await dispatchWorkspaceSyncChanges(targetWorkspaceId, incomingChanges, {
                 allowReferenceNumberReassignment