@taskforcehq/taskforce 0.3.302 → 0.3.304

package/dist/shared/taskActor.d.ts

@@ -0,0 +1,10 @@
+export interface TaskActor {
+    id: string;
+    kind: 'human' | 'ai';
+    label: string;
+    username: string;
+    icon: string;
+    color: string;
+    isNamed: boolean;
+    meta?: Record<string, unknown>;
+}

package/dist/shared/taskActor.js

@@ -0,0 +1 @@
+export {};

package/dist/sync/cloudSyncApi.d.ts

@@ -25,6 +25,7 @@ export declare function pullWorkspaceChanges(resolveCloudAuthUrl: (path: string)
     nextCursor?: string | null;
     hasMore?: boolean;
     workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+    diagnostics?: Record<string, unknown>;
 }>>;
 export declare function pushWorkspaceChanges(resolveCloudAuthUrl: (path: string) => string, input: {
     workspaceId: string;

package/dist/sync/collaborationSyncPayload.js

@@ -39,6 +39,10 @@ export function normalizeAiProfileSyncPayload(raw, workspaceId, normalizeSurface
         username: String(profile.username || '').trim(),
         icon: String(profile.icon || 'Bot').trim() || 'Bot',
         color: String(profile.color || '#8b5cf6').trim() || '#8b5cf6',
+        description: toNullableTrimmedString(profile.description),
+        role: toNullableTrimmedString(profile.role),
+        provider: toNullableTrimmedString(profile.provider),
+        model: toNullableTrimmedString(profile.model),
         surfaceType: normalizeSurfaceType(profile.surfaceType, { source, profileId, workspaceId: profileWorkspaceId }),
         providerMetadata: profile.providerMetadata && typeof profile.providerMetadata === 'object' && !Array.isArray(profile.providerMetadata)
             ? profile.providerMetadata

package/dist/sync/collaborationSyncPayload.test.js

@@ -15,6 +15,10 @@ describe('collaborationSyncPayload', () => {
             username: ' agent ',
             icon: ' Bot ',
             color: ' #111111 ',
+            description: ' Product coding agent ',
+            role: ' Implementer ',
+            provider: ' OpenAI ',
+            model: ' gpt-5.4 ',
             surfaceType: 'agent',
             providerMetadata: { foo: 'bar' },
             createdAt: '2026-04-10T10:00:00.000Z',
@@ -29,6 +33,10 @@ describe('collaborationSyncPayload', () => {
             username: 'agent',
             icon: 'Bot',
             color: '#111111',
+            description: 'Product coding agent',
+            role: 'Implementer',
+            provider: 'OpenAI',
+            model: 'gpt-5.4',
             surfaceType: 'agent',
             providerMetadata: { foo: 'bar' },
             createdAt: '2026-04-10T10:00:00.000Z',

package/dist/sync/collaborationSyncState.d.ts

@@ -1,5 +1,5 @@
 import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
-import type { WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot } from './workspaceSyncModel.js';
+import type { WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncTaskEventSnapshot } from './workspaceSyncModel.js';
 type SyncCore = TaskforceCore & TaskforceSyncCapable;
 interface CollaborationSyncStateDeps {
     core: SyncCore;
@@ -7,9 +7,11 @@ interface CollaborationSyncStateDeps {
 export declare function listWorkspaceSyncDocumentReviewSessionsSnapshot(deps: CollaborationSyncStateDeps, workspaceId?: string): WorkspaceSyncDocumentReviewSessionSnapshot[];
 export declare function listWorkspaceSyncDocumentReviewCommentsSnapshot(deps: CollaborationSyncStateDeps, workspaceId?: string): WorkspaceSyncDocumentReviewCommentSnapshot[];
 export declare function listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(deps: CollaborationSyncStateDeps, workspaceId?: string): WorkspaceSyncAnnotatedAttachmentSessionSnapshot[];
+export declare function listWorkspaceSyncTaskEventsSnapshot(deps: CollaborationSyncStateDeps, workspaceId?: string): WorkspaceSyncTaskEventSnapshot[];
 export declare function createCollaborationSyncState(deps: CollaborationSyncStateDeps): {
     listWorkspaceSyncDocumentReviewSessionsSnapshot: (workspaceId?: string) => WorkspaceSyncDocumentReviewSessionSnapshot[];
     listWorkspaceSyncDocumentReviewCommentsSnapshot: (workspaceId?: string) => WorkspaceSyncDocumentReviewCommentSnapshot[];
     listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: (workspaceId?: string) => WorkspaceSyncAnnotatedAttachmentSessionSnapshot[];
+    listWorkspaceSyncTaskEventsSnapshot: (workspaceId?: string) => WorkspaceSyncTaskEventSnapshot[];
 };
 export {};

package/dist/sync/collaborationSyncState.js

@@ -51,10 +51,29 @@ export function listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(deps, works
         && session.workspaceId.length > 0
         && session.baseImageAssetId.length > 0));
 }
+export function listWorkspaceSyncTaskEventsSnapshot(deps, workspaceId = 'default') {
+    return deps.core.listTaskEventsForSync({ workspaceId })
+        .map((event) => ({
+        id: event.id,
+        taskId: event.taskId,
+        workspaceId: event.workspaceId,
+        action: event.action,
+        actor: event.actor,
+        actorType: event.actorType,
+        details: event.details,
+        createdAt: event.createdAt,
+    }))
+        .filter((event) => (event.id.length > 0
+        && event.taskId.length > 0
+        && event.workspaceId.length > 0
+        && event.action.length > 0
+        && event.createdAt.length > 0));
+}
 export function createCollaborationSyncState(deps) {
     return {
         listWorkspaceSyncDocumentReviewSessionsSnapshot: (workspaceId = 'default') => listWorkspaceSyncDocumentReviewSessionsSnapshot(deps, workspaceId),
         listWorkspaceSyncDocumentReviewCommentsSnapshot: (workspaceId = 'default') => listWorkspaceSyncDocumentReviewCommentsSnapshot(deps, workspaceId),
         listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: (workspaceId = 'default') => listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(deps, workspaceId),
+        listWorkspaceSyncTaskEventsSnapshot: (workspaceId = 'default') => listWorkspaceSyncTaskEventsSnapshot(deps, workspaceId),
     };
 }

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,
@@ -117,10 +117,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,
@@ -344,6 +344,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 +492,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 +728,13 @@ 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;
+            const nextReferenceNumber = allowReferenceNumberReassignment
+                ? (incomingReferenceNumber ?? existing?.referenceNumber ?? null)
+                : (existing?.referenceNumber ?? incomingReferenceNumber ?? null);
             const originalFilename = String(doc.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'document.md').trim() || 'document.md';
             const asset = deps.workspaceAssetStore.upsertAsset({
                 assetId: String(doc.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
@@ -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: nextReferenceNumber,
                 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,13 @@ 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;
+        const nextReferenceNumber = allowReferenceNumberReassignment
+            ? (incomingReferenceNumber ?? existing?.referenceNumber ?? null)
+            : (existing?.referenceNumber ?? incomingReferenceNumber ?? null);
         const assetRecord = deps.workspaceAssetStore.upsertAsset({
             assetId: String(asset.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
             workspaceId,
@@ -583,9 +844,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: nextReferenceNumber,
             version: null,
             isLatest: true,
             scanStatus: existing?.scanStatus || 'clean',
@@ -596,7 +855,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 +991,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/syncApplyHandlers.d.ts

@@ -1,6 +1,7 @@
 import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
-import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncInitiativeSnapshot, WorkspaceSyncWorkspaceMemberSnapshot, WorkspaceSyncWorkstreamSnapshot } from './workspaceSyncModel.js';
+import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncChange, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncInitiativeSnapshot, WorkspaceSyncTaskEventSnapshot, WorkspaceSyncTaskSnapshot, WorkspaceSyncWorkspaceMemberSnapshot, WorkspaceSyncWorkstreamSnapshot } from './workspaceSyncModel.js';
 import type { BinaryAssetSyncPayload, DocumentSyncPayload } from './contentSyncPayload.js';
+import type { AiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 type SyncCore = TaskforceCore & TaskforceSyncCapable;
 type SyncRouteError = Error & {
     code?: string;
@@ -12,7 +13,81 @@ type CreateSyncRouteError = (message: string, details: Record<string, unknown>,
     code?: string;
     statusCode?: number;
 }) => SyncRouteError;
+type NormalizeIncomingAiProfileSurfaceType = (value: unknown, context: {
+    source: string;
+    profileId?: string;
+    workspaceId?: string;
+}) => AiProfileSurfaceType | null;
+type NormalizeTaskEventSyncPayload = (raw: unknown, workspaceId: string, sourceWatermark?: string) => WorkspaceSyncTaskEventSnapshot | null;
+export interface WorkspaceSyncIncomingTaskMutation {
+    archived: boolean;
+    task: WorkspaceSyncTaskSnapshot;
+}
+export interface WorkspaceSyncIncomingTaskApplyModel {
+    upserts: WorkspaceSyncIncomingTaskMutation[];
+    deletes: Map<string, string>;
+}
+export interface WorkspaceSyncIncomingApplyModel {
+    taskMutations: WorkspaceSyncIncomingTaskApplyModel;
+    planning: {
+        incomingTaxonomies: unknown[] | null;
+        incomingTaxonomyState: Record<string, unknown> | null;
+        incomingTaxonomiesUpdatedAt: string;
+        incomingInitiatives: Map<string, WorkspaceSyncInitiativeSnapshot>;
+        incomingWorkstreams: Map<string, WorkspaceSyncWorkstreamSnapshot>;
+    };
+    profiles: {
+        incomingAiProfiles: Map<string, WorkspaceSyncAiProfileSnapshot>;
+    };
+    content: {
+        incomingDocuments: DocumentSyncPayload[];
+        incomingDocumentDeletes: Map<string, string>;
+        incomingAssets: BinaryAssetSyncPayload[];
+        incomingAssetDeletes: Map<string, string>;
+    };
+    collaboration: {
+        incomingDocumentReviewSessions: Map<string, WorkspaceSyncDocumentReviewSessionSnapshot>;
+        incomingDocumentReviewSessionDeletes: Map<string, string>;
+        incomingDocumentReviewComments: Map<string, WorkspaceSyncDocumentReviewCommentSnapshot>;
+        incomingDocumentReviewCommentDeletes: Map<string, string>;
+        incomingAnnotatedAttachmentSessions: Map<string, WorkspaceSyncAnnotatedAttachmentSessionSnapshot>;
+        incomingAnnotatedAttachmentSessionDeletes: Map<string, string>;
+    };
+    taskActivity: {
+        incomingTaskEvents: Map<string, WorkspaceSyncTaskEventSnapshot>;
+    };
+}
+export interface PreparedWorkspaceTaskSyncSnapshot {
+    tasks: WorkspaceSyncTaskSnapshot[];
+    archived: WorkspaceSyncTaskSnapshot[];
+}
 export declare function resolveSyncConflictOrdering(incomingWatermark: string, existingWatermark: string, incomingTieBreak: string, existingTieBreak: string): number;
+export declare function classifyWorkspaceSyncChanges(input: {
+    workspaceId: string;
+    incomingChanges: WorkspaceSyncChange[];
+    normalizeWorkspaceSyncDocumentPath: (rawPath: unknown) => string | null;
+    normalizeTaskAssetPath: (rawPath: unknown) => string | null;
+    normalizeIncomingAiProfileSurfaceType: NormalizeIncomingAiProfileSurfaceType;
+    normalizeTaskEventSyncPayload: NormalizeTaskEventSyncPayload;
+    recordSyncDiagnostic: RecordSyncDiagnostic;
+}): WorkspaceSyncIncomingApplyModel;
+export declare function prepareTaskSyncSnapshotApply(input: {
+    core: SyncCore;
+    workspaceId: string;
+    taskMutations: WorkspaceSyncIncomingTaskApplyModel;
+    recordSyncDiagnostic: RecordSyncDiagnostic;
+}): PreparedWorkspaceTaskSyncSnapshot;
+export declare function applyTaskSyncDeletes(input: {
+    core: SyncCore;
+    workspaceId: string;
+    taskMutations: WorkspaceSyncIncomingTaskApplyModel;
+    recordSyncDiagnostic: RecordSyncDiagnostic;
+}): number;
+export declare function applyPreparedTaskSyncSnapshot(input: {
+    core: SyncCore;
+    workspaceId: string;
+    prepared: PreparedWorkspaceTaskSyncSnapshot;
+}): ReturnType<SyncCore['applyWorkspaceSyncSnapshot']>;
 export declare function applyPlanningSyncChanges(input: {
     core: SyncCore;
     workspaceId: string;
@@ -51,6 +126,10 @@ export declare function applyContentSyncChanges(input: {
     hasBinaryAssetSyncMetadataDrift: (workspaceId: string, asset: BinaryAssetSyncPayload, options?: {
         allowReferenceNumberReassignment?: boolean;
     }) => boolean;
+    getExistingDocument?: (docPath: string, workspaceId: string) => {
+        updatedAt?: string | null;
+        contentHash?: string | null;
+    } | null;
     writeWorkspaceSyncDocument: (basePath: string, doc: DocumentSyncPayload, workspaceId?: string, options?: {
         allowReferenceNumberReassignment?: boolean;
     }) => Promise<void>;
@@ -80,4 +159,11 @@ export declare function applyCollaborationSyncChanges(input: {
     recordSyncDiagnostic: RecordSyncDiagnostic;
     createSyncRouteError: CreateSyncRouteError;
 }): void;
+export declare function applyTaskActivitySyncChanges(input: {
+    core: SyncCore;
+    workspaceId: string;
+    incomingTaskEvents: Map<string, WorkspaceSyncTaskEventSnapshot>;
+    recordSyncDiagnostic: RecordSyncDiagnostic;
+    createSyncRouteError: CreateSyncRouteError;
+}): void;
 export {};