@taskforcehq/taskforce 0.3.302 → 0.3.303

package/dist/sync/contentSyncState.d.ts

@@ -21,6 +21,8 @@ interface ContentSyncStateDeps {
     recordSyncDiagnostic: RecordSyncDiagnostic;
     workspaceDocumentSnapshotCache: Map<string, Map<string, CachedWorkspaceSyncDocument>>;
 }
+export type DocumentSyncIndexEntry = Omit<DocumentSyncPayload, 'content'>;
+export type BinaryAssetSyncIndexEntry = Omit<BinaryAssetSyncPayload, 'contentBase64'>;
 export declare function resolveCanonicalAssetSyncLinkState(deps: ContentSyncStateDeps, asset: WorkspaceAssetEntry, workspaceId: string): {
     primaryLink: WorkspaceAssetLinkEntry | null;
     effectiveUpdatedAt: string;
@@ -42,7 +44,11 @@ export declare function reconcileWorkspaceSyncLinks(deps: ContentSyncStateDeps,
 }): void;
 export declare function listWorkspaceSyncDocumentDeletesSnapshot(deps: ContentSyncStateDeps, workspaceId?: string): DocumentDeleteSyncPayload[];
 export declare function listWorkspaceSyncDocumentsSnapshot(deps: ContentSyncStateDeps, basePath: string, workspaceId?: string): Promise<DocumentSyncPayload[]>;
+export declare function listWorkspaceSyncDocumentIndex(deps: ContentSyncStateDeps, basePath: string, workspaceId?: string): Promise<DocumentSyncIndexEntry[]>;
 export declare function listWorkspaceSyncBinaryAssetsSnapshot(deps: ContentSyncStateDeps, basePath: string, workspaceId?: string): Promise<BinaryAssetSyncPayload[]>;
+export declare function listWorkspaceSyncBinaryAssetIndex(deps: ContentSyncStateDeps, workspaceId?: string): Promise<BinaryAssetSyncIndexEntry[]>;
+export declare function loadWorkspaceSyncDocumentPayload(deps: ContentSyncStateDeps, basePath: string, workspaceId: string, relativePath: string): Promise<DocumentSyncPayload | null>;
+export declare function loadWorkspaceSyncBinaryAssetPayload(deps: ContentSyncStateDeps, basePath: string, workspaceId: string, assetPath: string): Promise<BinaryAssetSyncPayload | null>;
 export declare function listWorkspaceSyncBinaryAssetDeletesSnapshot(deps: ContentSyncStateDeps, workspaceId?: string): BinaryAssetDeleteSyncPayload[];
 export declare function writeWorkspaceSyncDocument(deps: ContentSyncStateDeps, basePath: string, doc: DocumentSyncPayload, workspaceId?: string, options?: {
     allowReferenceNumberReassignment?: boolean;
@@ -73,8 +79,12 @@ export declare function createContentSyncState(deps: ContentSyncStateDeps): {
         updatedAt?: string | null;
     }) => void;
     listWorkspaceSyncDocumentDeletesSnapshot: (workspaceId?: string) => DocumentDeleteSyncPayload[];
+    listWorkspaceSyncDocumentIndex: (basePath: string, workspaceId?: string) => Promise<DocumentSyncIndexEntry[]>;
     listWorkspaceSyncDocumentsSnapshot: (basePath: string, workspaceId?: string) => Promise<DocumentSyncPayload[]>;
+    loadWorkspaceSyncDocumentPayload: (basePath: string, workspaceId: string, relativePath: string) => Promise<DocumentSyncPayload | null>;
+    listWorkspaceSyncBinaryAssetIndex: (workspaceId?: string) => Promise<BinaryAssetSyncIndexEntry[]>;
     listWorkspaceSyncBinaryAssetsSnapshot: (basePath: string, workspaceId?: string) => Promise<BinaryAssetSyncPayload[]>;
+    loadWorkspaceSyncBinaryAssetPayload: (basePath: string, workspaceId: string, assetPath: string) => Promise<BinaryAssetSyncPayload | null>;
     listWorkspaceSyncBinaryAssetDeletesSnapshot: (workspaceId?: string) => BinaryAssetDeleteSyncPayload[];
     writeWorkspaceSyncDocument: (basePath: string, doc: DocumentSyncPayload, workspaceId?: string, options?: {
         allowReferenceNumberReassignment?: boolean;

package/dist/sync/contentSyncState.js

@@ -68,10 +68,10 @@ export function hasDocumentSyncMetadataDrift(deps, workspaceId, doc, options) {
         : null;
     const normalizedIncomingLinkRole = doc.linkRole === 'reference' ? 'reference' : 'attachment';
     const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
-    if (!allowReferenceNumberReassignment
-        && existingAsset.referenceNumber
+    const referenceNumberMismatch = Boolean(existingAsset.referenceNumber
         && normalizedIncomingReference
-        && 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,
@@ -80,7 +80,8 @@ export function hasDocumentSyncMetadataDrift(deps, workspaceId, doc, options) {
             incomingReferenceNumber: normalizedIncomingReference
         });
     }
-    return (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
+    return referenceNumberMismatch
+        || (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
         || existingAsset.version !== normalizedIncomingVersion
         || (existingAsset.documentId || null) !== normalizedIncomingDocumentId
         || (existingAsset.logicalName || null) !== normalizedIncomingLogicalName
@@ -117,10 +118,10 @@ export function hasBinaryAssetSyncMetadataDrift(deps, workspaceId, asset, option
             ? 'image'
             : 'attachment';
     const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
-    if (!allowReferenceNumberReassignment
-        && existingAsset.referenceNumber
+    const referenceNumberMismatch = Boolean(existingAsset.referenceNumber
         && normalizedIncomingReference
-        && 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,
@@ -129,7 +130,8 @@ export function hasBinaryAssetSyncMetadataDrift(deps, workspaceId, asset, option
             incomingReferenceNumber: normalizedIncomingReference
         });
     }
-    return (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
+    return referenceNumberMismatch
+        || (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
         || (existingAsset.logicalName || null) !== normalizedIncomingLogicalName
         || (existingAsset.originalFilename || null) !== normalizedIncomingFilename
         || (primaryLink?.taskId || null) !== normalizedIncomingTaskId
@@ -344,6 +346,80 @@ export async function listWorkspaceSyncDocumentsSnapshot(deps, basePath, workspa
     }
     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 [];
@@ -418,6 +494,181 @@ export async function listWorkspaceSyncBinaryAssetsSnapshot(deps, basePath, work
     }
     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 [];
@@ -479,6 +730,11 @@ export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceI
         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, '')}`),
@@ -494,9 +750,7 @@ export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceI
                 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,
+                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),
@@ -509,7 +763,7 @@ export async function writeWorkspaceSyncDocument(deps, basePath, doc, workspaceI
                 updatedAt: effectiveUpdatedAt,
                 deletedAt: null,
                 purgeAfter: null,
-                allowReferenceNumberReassignment: options?.allowReferenceNumberReassignment === true
+                allowReferenceNumberReassignment
             });
             const taskId = String(doc.taskId || '').trim();
             reconcileWorkspaceSyncLinks(deps, {
@@ -569,6 +823,11 @@ export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, works
     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,
@@ -583,9 +842,7 @@ export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, works
             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,
+            referenceNumber: incomingReferenceNumber ?? existing?.referenceNumber ?? null,
             version: null,
             isLatest: true,
             scanStatus: existing?.scanStatus || 'clean',
@@ -596,7 +853,7 @@ export async function writeWorkspaceSyncBinaryAsset(deps, basePath, asset, works
             updatedAt: effectiveUpdatedAt,
             deletedAt: null,
             purgeAfter: null,
-            allowReferenceNumberReassignment: options?.allowReferenceNumberReassignment === true
+            allowReferenceNumberReassignment
         });
         const taskId = String(asset.taskId || '').trim();
         reconcileWorkspaceSyncLinks(deps, {
@@ -732,8 +989,12 @@ export function createContentSyncState(deps) {
         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),

package/dist/sync/syncService.d.ts

@@ -115,6 +115,7 @@ export interface WorkspacePullSyncResult {
     pulledArchivedUpserts: boolean;
     documentDecryptFailures?: string[];
     emittedEventIds?: string[];
+    serverDiagnostics?: Record<string, unknown> | null;
 }
 export declare function runWorkspacePullSyncService(input: WorkspacePullSyncInput): Promise<WorkspacePullSyncResult>;
 export declare function syncUserGlobalSettingsService(input: UserSettingsSyncInput): Promise<UserSettingsSyncResult>;

package/dist/sync/syncService.js

@@ -243,6 +243,7 @@ export async function runWorkspacePullSyncService(input) {
     const documentDecryptFailures = new Set();
     const emittedEventIds = new Set();
     const pulledAnnotatedAttachmentSessionIds = new Set();
+    let lastServerDiagnostics = null;
     const maxPages = Number.isFinite(Number(input.maxPages)) ? Math.max(1, Math.floor(Number(input.maxPages))) : 20;
     try {
         while (hasMore && pages < maxPages) {
@@ -279,11 +280,16 @@ export async function runWorkspacePullSyncService(input) {
                     pulledDeleteTaskIds,
                     pulledActiveUpserts,
                     pulledArchivedUpserts,
-                    documentDecryptFailures: Array.from(documentDecryptFailures)
+                    documentDecryptFailures: Array.from(documentDecryptFailures),
+                    serverDiagnostics: null
                 };
             }
             const pullData = pullRes.data || {};
             const changes = Array.isArray(pullData?.changes) ? pullData.changes : [];
+            const serverDiagnostics = pullData?.diagnostics && typeof pullData.diagnostics === 'object'
+                ? pullData.diagnostics
+                : null;
+            lastServerDiagnostics = serverDiagnostics;
             const hasWorkspaceMembersSnapshot = Array.isArray(pullData?.workspaceMembers);
             const workspaceMembers = hasWorkspaceMembersSnapshot
                 ? pullData.workspaceMembers
@@ -365,7 +371,8 @@ export async function runWorkspacePullSyncService(input) {
                             pulledDeleteTaskIds,
                             pulledActiveUpserts,
                             pulledArchivedUpserts,
-                            documentDecryptFailures: Array.from(documentDecryptFailures)
+                            documentDecryptFailures: Array.from(documentDecryptFailures),
+                            serverDiagnostics
                         };
                     }
                     const hasTransientApplyFailure = applyFailures.some((entry) => {
@@ -392,7 +399,8 @@ export async function runWorkspacePullSyncService(input) {
                         pulledActiveUpserts,
                         pulledArchivedUpserts,
                         documentDecryptFailures: Array.from(documentDecryptFailures),
-                        emittedEventIds: Array.from(emittedEventIds)
+                        emittedEventIds: Array.from(emittedEventIds),
+                        serverDiagnostics: lastServerDiagnostics
                     };
                 }
                 const applyPayloadData = asObjectRecord(applyResult.data);
@@ -412,7 +420,8 @@ export async function runWorkspacePullSyncService(input) {
                         pulledActiveUpserts,
                         pulledArchivedUpserts,
                         documentDecryptFailures: Array.from(documentDecryptFailures),
-                        emittedEventIds: Array.from(emittedEventIds)
+                        emittedEventIds: Array.from(emittedEventIds),
+                        serverDiagnostics: lastServerDiagnostics
                     };
                 }
                 applyMs += (Date.now() - applyStartedAtMs);
@@ -461,7 +470,8 @@ export async function runWorkspacePullSyncService(input) {
                         pulledActiveUpserts,
                         pulledArchivedUpserts,
                         documentDecryptFailures: Array.from(documentDecryptFailures),
-                        emittedEventIds: Array.from(emittedEventIds)
+                        emittedEventIds: Array.from(emittedEventIds),
+                        serverDiagnostics: lastServerDiagnostics
                     };
                 }
                 const hasTransientApplyFailure = bootstrapApplyFailures.some((entry) => {
@@ -488,7 +498,8 @@ export async function runWorkspacePullSyncService(input) {
                     pulledActiveUpserts,
                     pulledArchivedUpserts,
                     documentDecryptFailures: Array.from(documentDecryptFailures),
-                    emittedEventIds: Array.from(emittedEventIds)
+                    emittedEventIds: Array.from(emittedEventIds),
+                    serverDiagnostics: lastServerDiagnostics
                 };
             }
             applyMs += (Date.now() - bootstrapApplyStartedAtMs);
@@ -505,7 +516,8 @@ export async function runWorkspacePullSyncService(input) {
             pulledActiveUpserts,
             pulledArchivedUpserts,
             documentDecryptFailures: Array.from(documentDecryptFailures),
-            emittedEventIds: Array.from(emittedEventIds)
+            emittedEventIds: Array.from(emittedEventIds),
+            serverDiagnostics: lastServerDiagnostics
         };
     }
     catch (error) {
@@ -524,7 +536,8 @@ export async function runWorkspacePullSyncService(input) {
             pulledActiveUpserts,
             pulledArchivedUpserts,
             documentDecryptFailures: Array.from(documentDecryptFailures),
-            emittedEventIds: Array.from(emittedEventIds)
+            emittedEventIds: Array.from(emittedEventIds),
+            serverDiagnostics: null
         };
     }
 }

package/dist/sync/workspacePullFeed.d.ts

@@ -15,6 +15,16 @@ export interface WorkspacePullFeedResult {
     changes: EncodedWorkspaceSyncChange[];
     nextCursor: string | null;
     hasMore: boolean;
+    diagnostics: {
+        totalEntries: number;
+        pageEntries: number;
+        documentIndexCount: number;
+        assetIndexCount: number;
+        indexMs: number;
+        hydrationMs: number;
+        encodeMs: number;
+        buildMs: number;
+    };
 }
 export declare function buildWorkspacePullFeed(input: {
     core: SyncCore;