@taskforcehq/taskforce 0.3.301 → 0.3.303

package/dist/sync/contentSyncState.js

@@ -0,0 +1,1004 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash, randomUUID } from 'crypto';
+export function resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId) {
+    if (!deps.workspaceAssetStore) {
+        return {
+            primaryLink: null,
+            effectiveUpdatedAt: String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString()
+        };
+    }
+    const links = deps.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 };
+}
+export function getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId) {
+    if (!deps.workspaceAssetStore)
+        return {};
+    const asset = deps.workspaceAssetStore.getByStorageKey(relativePath, workspaceId);
+    if (!asset || asset.kind !== 'document')
+        return {};
+    const { primaryLink } = resolveCanonicalAssetSyncLinkState(deps, 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'
+    };
+}
+export function hasDocumentSyncMetadataDrift(deps, workspaceId, doc, options) {
+    if (!deps.workspaceAssetStore)
+        return false;
+    const existingAsset = deps.workspaceAssetStore.getByStorageKey(doc.path, workspaceId);
+    if (!existingAsset || existingAsset.kind !== 'document')
+        return false;
+    const { primaryLink } = resolveCanonicalAssetSyncLinkState(deps, 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()
+        : null;
+    const normalizedIncomingLinkRole = doc.linkRole === 'reference' ? 'reference' : 'attachment';
+    const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
+    const referenceNumberMismatch = Boolean(existingAsset.referenceNumber
+        && normalizedIncomingReference
+        && existingAsset.referenceNumber !== normalizedIncomingReference);
+    if (referenceNumberMismatch) {
+        deps.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 referenceNumberMismatch
+        || (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;
+}
+export function hasBinaryAssetSyncMetadataDrift(deps, workspaceId, asset, options) {
+    if (!deps.workspaceAssetStore)
+        return false;
+    const existingAsset = deps.workspaceAssetStore.getByStorageKey(asset.path, workspaceId);
+    if (!existingAsset || (existingAsset.kind !== 'image' && existingAsset.kind !== 'file'))
+        return false;
+    const { primaryLink } = resolveCanonicalAssetSyncLinkState(deps, 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;
+    const referenceNumberMismatch = Boolean(existingAsset.referenceNumber
+        && normalizedIncomingReference
+        && existingAsset.referenceNumber !== normalizedIncomingReference);
+    if (referenceNumberMismatch) {
+        deps.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 referenceNumberMismatch
+        || (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;
+}
+export function reconcileWorkspaceSyncLinks(deps, input) {
+    if (!deps.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 = deps.workspaceAssetStore.listLinksForAsset(assetId, workspaceId, { includeDeleted: true });
+    if (desiredTaskId) {
+        deps.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
+        });
+    }
+    if (desiredTaskId) {
+        for (const link of existingLinks) {
+            if (link.taskId === desiredTaskId && link.role === desiredRole)
+                continue;
+            if (link.deletedAt)
+                continue;
+            deps.workspaceAssetStore.deleteLink({
+                workspaceId,
+                assetId,
+                taskId: link.taskId,
+                role: link.role
+            });
+        }
+    }
+}
+export function listWorkspaceSyncDocumentDeletesSnapshot(deps, workspaceId = 'default') {
+    if (!deps.workspaceAssetStore)
+        return [];
+    const entries = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
+        includeDeleted: true,
+        kind: 'document'
+    })
+        .filter((asset) => typeof asset.deletedAt === 'string' && asset.deletedAt.trim().length > 0)
+        .map((asset) => {
+        const normalizedPath = deps.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));
+}
+export async function listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspaceId = 'default') {
+    const root = path.resolve(basePath);
+    const objectStorageClient = deps.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 = deps.normalizeWorkspaceSyncDocumentPath(relativeFromRoot);
+            if (normalized)
+                candidatePaths.add(normalized);
+        }
+    };
+    collectMarkdownPaths(docsRoot);
+    if (deps.workspaceAssetStore) {
+        const canonicalAssets = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
+            includeDeleted: false,
+            kind: 'document'
+        });
+        for (const asset of canonicalAssets) {
+            const normalized = deps.normalizeWorkspaceSyncDocumentPath(asset.storageKey);
+            if (normalized)
+                candidatePaths.add(normalized);
+        }
+    }
+    const uniquePaths = Array.from(candidatePaths).sort((a, b) => a.localeCompare(b));
+    const workspaceCache = deps.workspaceDocumentSnapshotCache.get(workspaceId) || new Map();
+    deps.workspaceDocumentSnapshotCache.set(workspaceId, workspaceCache);
+    const remainingPaths = new Set(uniquePaths);
+    const docs = [];
+    for (const relativePath of uniquePaths) {
+        try {
+            const canonicalAsset = deps.workspaceAssetStore?.getByStorageKey(relativePath, workspaceId);
+            let stat = null;
+            let content = null;
+            let updatedAt = '';
+            if (canonicalAsset?.kind === 'document') {
+                updatedAt = resolveCanonicalAssetSyncLinkState(deps, canonicalAsset, workspaceId).effectiveUpdatedAt;
+                if (canonicalAsset.storageProvider === 'r2' && objectStorageClient) {
+                    const object = await objectStorageClient.getObject(relativePath);
+                    if (!object?.body)
+                        continue;
+                    content = object.body.toString('utf8');
+                }
+                else {
+                    const absPath = path.resolve(path.join(root, relativePath));
+                    if (absPath !== root && !absPath.startsWith(`${root}${path.sep}`))
+                        continue;
+                    if (!fs.existsSync(absPath))
+                        continue;
+                    stat = fs.statSync(absPath);
+                    if (!stat.isFile())
+                        continue;
+                    content = fs.readFileSync(absPath, 'utf8');
+                }
+            }
+            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(deps, relativePath, workspaceId)
+                });
+                continue;
+            }
+            if (!canonicalAsset) {
+                const contentHash = createHash('sha256').update(content).digest('hex');
+                const existing = deps.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 {
+                        deps.core.upsertDocumentWatermark(workspaceId, relativePath, contentHash, updatedAt);
+                    }
+                    catch (error) {
+                        deps.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(deps, relativePath, workspaceId)
+            });
+            workspaceCache.set(relativePath, {
+                path: relativePath,
+                mtimeMs: stat?.mtimeMs ?? 0,
+                ctimeMs: stat?.ctimeMs ?? 0,
+                size: Buffer.byteLength(content, 'utf8'),
+                updatedAt,
+                content
+            });
+        }
+        catch (error) {
+            deps.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;
+}
+export async function listWorkspaceSyncDocumentIndex(deps, basePath, workspaceId = 'default') {
+    const root = path.resolve(basePath);
+    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 = deps.normalizeWorkspaceSyncDocumentPath(relativeFromRoot);
+            if (normalized)
+                candidatePaths.add(normalized);
+        }
+    };
+    collectMarkdownPaths(docsRoot);
+    if (deps.workspaceAssetStore) {
+        const canonicalAssets = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
+            includeDeleted: false,
+            kind: 'document'
+        });
+        for (const asset of canonicalAssets) {
+            const normalized = deps.normalizeWorkspaceSyncDocumentPath(asset.storageKey);
+            if (normalized)
+                candidatePaths.add(normalized);
+        }
+    }
+    const docs = [];
+    for (const relativePath of Array.from(candidatePaths).sort((a, b) => a.localeCompare(b))) {
+        try {
+            const canonicalAsset = deps.workspaceAssetStore?.getByStorageKey(relativePath, workspaceId);
+            let updatedAt = '';
+            if (canonicalAsset?.kind === 'document') {
+                updatedAt = resolveCanonicalAssetSyncLinkState(deps, canonicalAsset, workspaceId).effectiveUpdatedAt;
+            }
+            else {
+                const absPath = path.resolve(path.join(basePath, relativePath));
+                const safeRoot = path.resolve(basePath);
+                if (absPath !== safeRoot && !absPath.startsWith(`${safeRoot}${path.sep}`))
+                    continue;
+                if (!fs.existsSync(absPath))
+                    continue;
+                const stat = fs.statSync(absPath);
+                if (!stat.isFile())
+                    continue;
+                const existing = deps.core.getDocumentWatermark(workspaceId, relativePath);
+                updatedAt = existing?.updatedAt
+                    || (Number.isFinite(stat.mtimeMs) ? new Date(stat.mtimeMs).toISOString() : new Date().toISOString());
+            }
+            if (!Number.isFinite(Date.parse(String(updatedAt || '').trim())))
+                continue;
+            docs.push({
+                path: relativePath,
+                updatedAt: String(updatedAt || '').trim(),
+                ...getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId)
+            });
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to index sync document snapshot entry.', {
+                source: 'documents.snapshot.indexEntry',
+                path: relativePath,
+                error: String(error?.message || error || '')
+            });
+        }
+    }
+    return docs;
+}
+export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, workspaceId = 'default') {
+    if (!deps.workspaceAssetStore)
+        return [];
+    const root = path.resolve(basePath);
+    const objectStorageClient = deps.getObjectStorageClient();
+    const assets = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
+        includeDeleted: false
+    });
+    const snapshots = [];
+    for (const asset of assets) {
+        if (asset.kind !== 'image' && asset.kind !== 'file')
+            continue;
+        if (asset.storageProvider === 'external')
+            continue;
+        const storageKey = String(asset.storageKey || '').trim();
+        if (!storageKey)
+            continue;
+        if (!deps.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)) {
+                    deps.recordSyncDiagnostic(workspaceId, 'push', 'Asset registered in DB but file missing from disk — skipped from sync payload.', {
+                        source: 'assets.snapshot.missingFile',
+                        assetId: asset.assetId,
+                        path: storageKey
+                    });
+                    continue;
+                }
+                buffer = fs.readFileSync(absolutePath);
+            }
+            if (!buffer) {
+                deps.recordSyncDiagnostic(workspaceId, 'push', 'Asset registered in DB but content could not be read — skipped from sync payload.', {
+                    source: 'assets.snapshot.emptyBuffer',
+                    assetId: asset.assetId,
+                    path: storageKey,
+                    storageProvider: asset.storageProvider
+                });
+                continue;
+            }
+            const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, 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) {
+            deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to read binary asset snapshot entry.', {
+                source: 'assets.snapshot.readEntry',
+                path: storageKey,
+                error: String(error?.message || error || '')
+            });
+        }
+    }
+    return snapshots;
+}
+export async function listWorkspaceSyncBinaryAssetIndex(deps, workspaceId = 'default') {
+    if (!deps.workspaceAssetStore)
+        return [];
+    const assets = deps.workspaceAssetStore.listAllByWorkspace(workspaceId, {
+        includeDeleted: false
+    });
+    return assets
+        .filter((asset) => asset.kind === 'image' || asset.kind === 'file')
+        .filter((asset) => asset.storageProvider !== 'external')
+        .filter((asset) => {
+        const storageKey = String(asset.storageKey || '').trim();
+        return Boolean(storageKey && deps.normalizeTaskDataRelativePath(storageKey));
+    })
+        .map((asset) => {
+        const storageKey = String(asset.storageKey || '').trim();
+        const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+        const assetKind = asset.kind === 'image' ? 'image' : 'file';
+        return {
+            path: storageKey,
+            updatedAt: effectiveUpdatedAt,
+            assetId: asset.assetId,
+            kind: assetKind,
+            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')
+        };
+    })
+        .filter((entry) => Number.isFinite(Date.parse(entry.updatedAt)) && entry.path.length > 0);
+}
+export async function loadWorkspaceSyncDocumentPayload(deps, basePath, workspaceId, relativePath) {
+    const normalizedPath = deps.normalizeWorkspaceSyncDocumentPath(relativePath);
+    if (!normalizedPath)
+        return null;
+    const root = path.resolve(basePath);
+    const absolutePath = path.resolve(path.join(root, normalizedPath));
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`))
+        return null;
+    let content = '';
+    let stat = null;
+    try {
+        if (!fs.existsSync(absolutePath))
+            return null;
+        stat = fs.statSync(absolutePath);
+        if (!stat.isFile())
+            return null;
+        content = fs.readFileSync(absolutePath, 'utf8');
+    }
+    catch (error) {
+        deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to load targeted sync document payload.', {
+            source: 'documents.snapshot.loadPayload',
+            path: normalizedPath,
+            error: String(error?.message || error || '')
+        });
+        return null;
+    }
+    const workspaceCache = deps.workspaceDocumentSnapshotCache.get(workspaceId)
+        ?? (() => {
+            const next = new Map();
+            deps.workspaceDocumentSnapshotCache.set(workspaceId, next);
+            return next;
+        })();
+    const cached = workspaceCache.get(normalizedPath);
+    const canonicalAsset = deps.workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId);
+    let updatedAt = '';
+    if (canonicalAsset?.kind === 'document') {
+        updatedAt = resolveCanonicalAssetSyncLinkState(deps, canonicalAsset, workspaceId).effectiveUpdatedAt;
+    }
+    else {
+        const contentHash = createHash('sha256').update(content).digest('hex');
+        const existing = deps.core.getDocumentWatermark(workspaceId, normalizedPath);
+        if (existing && existing.contentHash === contentHash) {
+            updatedAt = existing.updatedAt;
+        }
+        else {
+            updatedAt = stat && Number.isFinite(stat.mtimeMs)
+                ? new Date(stat.mtimeMs).toISOString()
+                : new Date().toISOString();
+            try {
+                deps.core.upsertDocumentWatermark(workspaceId, normalizedPath, contentHash, updatedAt);
+            }
+            catch (error) {
+                deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to persist document watermark during targeted payload load.', {
+                    source: 'documents.snapshot.loadPayload.upsertWatermark',
+                    path: normalizedPath,
+                    error: String(error?.message || error || '')
+                });
+            }
+        }
+    }
+    if (cached
+        && stat
+        && cached.size === Buffer.byteLength(content, 'utf8')
+        && (canonicalAsset
+            ? cached.updatedAt === updatedAt
+            : cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs)) {
+        return {
+            path: normalizedPath,
+            updatedAt: cached.updatedAt,
+            content: cached.content,
+            ...getCanonicalSyncDocumentMetadata(deps, normalizedPath, workspaceId)
+        };
+    }
+    workspaceCache.set(normalizedPath, {
+        path: normalizedPath,
+        mtimeMs: stat?.mtimeMs ?? 0,
+        ctimeMs: stat?.ctimeMs ?? 0,
+        size: Buffer.byteLength(content, 'utf8'),
+        updatedAt,
+        content
+    });
+    return {
+        path: normalizedPath,
+        updatedAt,
+        content,
+        ...getCanonicalSyncDocumentMetadata(deps, normalizedPath, workspaceId)
+    };
+}
+export async function loadWorkspaceSyncBinaryAssetPayload(deps, basePath, workspaceId, assetPath) {
+    const normalizedPath = deps.normalizeTaskDataRelativePath(assetPath);
+    if (!normalizedPath)
+        return null;
+    if (!deps.workspaceAssetStore)
+        return null;
+    const asset = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+    if (!asset || (asset.kind !== 'image' && asset.kind !== 'file') || asset.storageProvider === 'external') {
+        return null;
+    }
+    const objectStorageClient = deps.getObjectStorageClient();
+    let buffer = null;
+    try {
+        if (asset.storageProvider === 'r2' && objectStorageClient) {
+            const object = await objectStorageClient.getObject(normalizedPath);
+            buffer = object?.body || null;
+        }
+        else {
+            const root = path.resolve(basePath);
+            const absolutePath = path.resolve(root, normalizedPath);
+            if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`))
+                return null;
+            if (!fs.existsSync(absolutePath))
+                return null;
+            buffer = fs.readFileSync(absolutePath);
+        }
+    }
+    catch (error) {
+        deps.recordSyncDiagnostic(workspaceId, 'pull', 'Failed to load targeted binary asset payload.', {
+            source: 'assets.snapshot.loadPayload',
+            path: normalizedPath,
+            assetId: asset.assetId,
+            error: String(error?.message || error || '')
+        });
+        return null;
+    }
+    if (!buffer)
+        return null;
+    const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId);
+    return {
+        path: normalizedPath,
+        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(normalizedPath),
+        linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment')
+    };
+}
+export function listWorkspaceSyncBinaryAssetDeletesSnapshot(deps, workspaceId = 'default') {
+    if (!deps.workspaceAssetStore)
+        return [];
+    const entries = deps.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 = deps.normalizeTaskDataRelativePath(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));
+}
+export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceId = 'default', options) {
+    const normalizedPath = deps.normalizeWorkspaceSyncDocumentPath(doc.path);
+    if (!normalizedPath)
+        return;
+    const root = path.resolve(basePath);
+    const targetPath = path.resolve(root, normalizedPath);
+    if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+        return;
+    const objectStorageClient = deps.getObjectStorageClient();
+    const content = String(doc.content || '');
+    if (objectStorageClient) {
+        try {
+            await objectStorageClient.putObject(normalizedPath, Buffer.from(content, 'utf8'), 'text/markdown');
+        }
+        catch (error) {
+            deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to write document to object storage.', {
+                source: 'documents.write.putObject',
+                path: normalizedPath,
+                error: String(error?.message || error || '')
+            });
+            return;
+        }
+    }
+    else {
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.writeFileSync(targetPath, content, 'utf8');
+    }
+    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);
+    }
+    try {
+        const contentHash = createHash('sha256').update(content).digest('hex');
+        deps.core.upsertDocumentWatermark(workspaceId, normalizedPath, contentHash, updatedAt || new Date().toISOString());
+        if (deps.workspaceAssetStore) {
+            const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+            const effectiveUpdatedAt = updatedAt || new Date().toISOString();
+            const incomingReferenceNumber = Number.isFinite(Number(doc.referenceNumber))
+                ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
+                : null;
+            const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true
+                || Boolean(existing?.referenceNumber && incomingReferenceNumber && existing.referenceNumber !== incomingReferenceNumber);
+            const originalFilename = String(doc.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'document.md').trim() || 'document.md';
+            const asset = deps.workspaceAssetStore.upsertAsset({
+                assetId: String(doc.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
+                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: incomingReferenceNumber ?? 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
+            });
+            const taskId = String(doc.taskId || '').trim();
+            reconcileWorkspaceSyncLinks(deps, {
+                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) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist document watermark after write.', {
+            source: 'documents.write.upsertWatermark',
+            path: normalizedPath,
+            error: String(error?.message || error || '')
+        });
+    }
+    deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+}
+export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, workspaceId = 'default', options) {
+    const normalizedPath = deps.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 = deps.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) {
+            deps.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 (!deps.workspaceAssetStore)
+        return;
+    try {
+        const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+        const effectiveUpdatedAt = updatedAt || new Date().toISOString();
+        const incomingReferenceNumber = Number.isFinite(Number(asset.referenceNumber))
+            ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
+            : null;
+        const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true
+            || Boolean(existing?.referenceNumber && incomingReferenceNumber && existing.referenceNumber !== incomingReferenceNumber);
+        const assetRecord = deps.workspaceAssetStore.upsertAsset({
+            assetId: String(asset.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
+            workspaceId,
+            kind: asset.kind === 'image' ? 'image' : 'file',
+            logicalName: typeof asset.logicalName === 'string' && asset.logicalName.trim().length > 0
+                ? asset.logicalName.trim()
+                : existing?.logicalName || null,
+            originalFilename: String(asset.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'asset').trim() || 'asset',
+            mimeType: String(asset.mimeType || existing?.mimeType || 'application/octet-stream').trim() || 'application/octet-stream',
+            storageProvider: objectStorageClient ? 'r2' : 'local',
+            storageKey: normalizedPath,
+            contentSha256: createHash('sha256').update(buffer).digest('hex'),
+            sizeBytes: buffer.length,
+            documentId: null,
+            referenceNumber: incomingReferenceNumber ?? 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
+        });
+        const taskId = String(asset.taskId || '').trim();
+        reconcileWorkspaceSyncLinks(deps, {
+            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) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist binary asset metadata after write.', {
+            source: 'assets.write.upsertAsset',
+            path: normalizedPath,
+            assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
+            kind: asset.kind,
+            error: String(error?.message || error || '')
+        });
+    }
+}
+export function deleteWorkspaceSyncBinaryAsset(deps, basePath, assetPath, workspaceId = 'default') {
+    const normalizedPath = deps.normalizeTaskDataRelativePath(assetPath);
+    if (!normalizedPath)
+        return;
+    const root = path.resolve(basePath);
+    const targetPath = path.resolve(root, normalizedPath);
+    const objectStorageClient = deps.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) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete workspace sync binary asset.', {
+            source: 'assets.delete.file',
+            path: normalizedPath,
+            error: String(error?.message || error || '')
+        });
+    }
+    if (deps.workspaceAssetStore) {
+        const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+        if (existing) {
+            const deletedAt = new Date().toISOString();
+            deps.workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
+            if (existing.kind === 'image') {
+                deps.core.deleteAnnotatedAttachmentSessionsForImage({
+                    workspaceId,
+                    imageAssetId: existing.assetId,
+                    deletedAt,
+                });
+            }
+            const links = deps.workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
+            for (const link of links) {
+                deps.workspaceAssetStore.deleteLink({
+                    workspaceId,
+                    assetId: existing.assetId,
+                    taskId: link.taskId,
+                    role: link.role
+                });
+            }
+        }
+    }
+}
+export function deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId = 'default') {
+    const normalizedPath = deps.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 = deps.getObjectStorageClient();
+    try {
+        if (objectStorageClient) {
+            void objectStorageClient.deleteObject(normalizedPath);
+        }
+        else if (fs.existsSync(targetPath)) {
+            fs.unlinkSync(targetPath);
+        }
+    }
+    catch (error) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete workspace sync document.', {
+            source: 'documents.delete.file',
+            path: normalizedPath,
+            error: String(error?.message || error || '')
+        });
+    }
+    try {
+        deps.core.deleteDocumentWatermark(workspaceId, normalizedPath);
+        if (deps.workspaceAssetStore) {
+            const existing = deps.workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+            if (existing) {
+                const deletedAt = new Date().toISOString();
+                deps.workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
+                if (existing.kind === 'image') {
+                    deps.core.deleteAnnotatedAttachmentSessionsForImage({
+                        workspaceId,
+                        imageAssetId: existing.assetId,
+                        deletedAt,
+                    });
+                }
+                const links = deps.workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
+                for (const link of links) {
+                    deps.workspaceAssetStore.deleteLink({
+                        workspaceId,
+                        assetId: existing.assetId,
+                        taskId: link.taskId,
+                        role: link.role
+                    });
+                }
+            }
+        }
+    }
+    catch (error) {
+        deps.recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document watermark.', {
+            source: 'documents.delete.watermark',
+            path: normalizedPath,
+            error: String(error?.message || error || '')
+        });
+    }
+    deps.workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+}
+export function createContentSyncState(deps) {
+    return {
+        resolveCanonicalAssetSyncLinkState: (asset, workspaceId) => resolveCanonicalAssetSyncLinkState(deps, asset, workspaceId),
+        getCanonicalSyncDocumentMetadata: (relativePath, workspaceId) => getCanonicalSyncDocumentMetadata(deps, relativePath, workspaceId),
+        hasDocumentSyncMetadataDrift: (workspaceId, doc, options) => hasDocumentSyncMetadataDrift(deps, workspaceId, doc, options),
+        hasBinaryAssetSyncMetadataDrift: (workspaceId, asset, options) => hasBinaryAssetSyncMetadataDrift(deps, workspaceId, asset, options),
+        reconcileWorkspaceSyncLinks: (input) => reconcileWorkspaceSyncLinks(deps, input),
+        listWorkspaceSyncDocumentDeletesSnapshot: (workspaceId = 'default') => listWorkspaceSyncDocumentDeletesSnapshot(deps, workspaceId),
+        listWorkspaceSyncDocumentIndex: (basePath, workspaceId = 'default') => listWorkspaceSyncDocumentIndex(deps, basePath, workspaceId),
+        listWorkspaceSyncDocumentsSnapshot: (basePath, workspaceId = 'default') => listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspaceId),
+        loadWorkspaceSyncDocumentPayload: (basePath, workspaceId, relativePath) => loadWorkspaceSyncDocumentPayload(deps, basePath, workspaceId, relativePath),
+        listWorkspaceSyncBinaryAssetIndex: (workspaceId = 'default') => listWorkspaceSyncBinaryAssetIndex(deps, workspaceId),
+        listWorkspaceSyncBinaryAssetsSnapshot: (basePath, workspaceId = 'default') => listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, workspaceId),
+        loadWorkspaceSyncBinaryAssetPayload: (basePath, workspaceId, assetPath) => loadWorkspaceSyncBinaryAssetPayload(deps, basePath, workspaceId, assetPath),
+        listWorkspaceSyncBinaryAssetDeletesSnapshot: (workspaceId = 'default') => listWorkspaceSyncBinaryAssetDeletesSnapshot(deps, workspaceId),
+        writeWorkspaceSyncDocument: (basePath, doc, workspaceId = 'default', options) => writeWorkspaceSyncDocument(deps, basePath, doc, workspaceId, options),
+        writeWorkspaceSyncBinaryAsset: (basePath, asset, workspaceId = 'default', options) => writeWorkspaceSyncBinaryAsset(deps, basePath, asset, workspaceId, options),
+        deleteWorkspaceSyncBinaryAsset: (basePath, assetPath, workspaceId = 'default') => deleteWorkspaceSyncBinaryAsset(deps, basePath, assetPath, workspaceId),
+        deleteWorkspaceSyncDocument: (basePath, docPath, workspaceId = 'default') => deleteWorkspaceSyncDocument(deps, basePath, docPath, workspaceId),
+    };
+}