@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/server/routes/sync.js

@@ -3,17 +3,18 @@ import { parseJsonBody } from './primitives.js';
 import { normalizeTaskDataRelativePath, ObjectStorageClient } from '../../storage/objectStorageClient.js';
 import { WorkspaceAssetStore, } from '../../storage/workspaceAssetStore.js';
 import { resolveSessionCookieAttributesForRequest } from '../auth.js';
-import { decryptDocument, ENCRYPTION_PREFIX } from '../../sync/encryptionService.js';
-import { isAiProfileSurfaceType } from '../../shared/aiProfileSurfaceType.js';
-import { serializeTaskForSync, } from '../../sync/taskSyncPayload.js';
+import { isAiProfileSurfaceType, parseAiProfileSurfaceType } from '../../shared/aiProfileSurfaceType.js';
+import { isAiProfileSeatScope } from '../../shared/aiProfileSeatScope.js';
 import { serializeBinaryAssetSyncPayload, serializeDocumentSyncPayload, } from '../../sync/contentSyncPayload.js';
 import { createContentSyncState } from '../../sync/contentSyncState.js';
 import { normalizeAiProfileSyncPayload, normalizeAnnotatedAttachmentSessionSyncPayload, normalizeDocumentReviewCommentSyncPayload, normalizeDocumentReviewSessionSyncPayload, } from '../../sync/collaborationSyncPayload.js';
 import { createCollaborationSyncState } from '../../sync/collaborationSyncState.js';
-import { buildWorkspacePullFeed } from '../../sync/workspacePullFeed.js';
 import { normalizeInitiativeSyncPayload, normalizeTaxonomySyncPayload, normalizeWorkstreamSyncPayload, } from '../../sync/planningSyncPayload.js';
 import { applyAiProfileAndMemberSyncChanges, applyCollaborationSyncChanges, applyContentSyncChanges, applyPlanningSyncChanges, applyPreparedTaskSyncSnapshot, applyTaskActivitySyncChanges, applyTaskSyncDeletes, classifyWorkspaceSyncChanges, prepareTaskSyncSnapshotApply, } from '../../sync/syncApplyHandlers.js';
-import { applyWorkspaceRepair } from '../../sync/workspaceRepair.js';
+import { registerWorkspaceSyncAuxRoutes } from './syncAuxRoutes.js';
+import { registerWorkspacePullApplySyncRoutes } from './syncPullApplyRoutes.js';
+import { registerWorkspacePushSyncRoutes } from './syncPushRoutes.js';
+import { registerWorkspaceSnapshotSyncRoutes } from './syncSnapshotRoutes.js';
 function decodeWorkspaceSyncCursor(raw) {
     const value = String(raw || '').trim();
     if (!value)
@@ -51,6 +52,8 @@ function normalizeIncomingAiProfileSurfaceType(value, context) {
     const normalized = String(value || '').trim();
     if (!normalized)
         return null;
+    if (normalized === 'other')
+        return parseAiProfileSurfaceType(normalized);
     if (!isAiProfileSurfaceType(normalized)) {
         throw createSyncRouteError(`Invalid ai profile surfaceType "${normalized}"`, {
             ...context,
@@ -59,16 +62,36 @@ function normalizeIncomingAiProfileSurfaceType(value, context) {
     }
     return normalized;
 }
+function normalizeIncomingAiProfileSeatScope(value, context) {
+    if (value === undefined || value === null)
+        return null;
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        return null;
+    if (!isAiProfileSeatScope(normalized)) {
+        throw createSyncRouteError(`Invalid ai profile seatScope "${normalized}"`, {
+            ...context,
+            seatScope: normalized
+        }, { code: 'AI_PROFILE_SEAT_SCOPE_INVALID', statusCode: 400 });
+    }
+    return normalized;
+}
 function normalizeTaskEventSyncPayload(raw, workspaceId, sourceWatermark) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
     const source = raw;
     const id = String(source.id || '').trim();
+    const entityType = source.entityType === 'initiative' || source.entityType === 'workstream'
+        ? source.entityType
+        : source.entity_type === 'initiative' || source.entity_type === 'workstream'
+            ? source.entity_type
+            : 'task';
     const taskId = String(source.taskId || source.task_id || '').trim();
+    const entityId = String(source.entityId || source.entity_id || taskId).trim();
     const action = String(source.action || '').trim();
     const actor = String(source.actor || 'system').trim() || 'system';
     const createdAt = String(source.createdAt || source.created_at || sourceWatermark || '').trim();
-    if (!id || !taskId || !action || !Number.isFinite(Date.parse(createdAt)))
+    if (!id || !entityId || !action || !Number.isFinite(Date.parse(createdAt)))
         return null;
     const actorType = source.actorType === 'ai' || source.actorType === 'human' || source.actorType === 'system'
         ? source.actorType
@@ -84,8 +107,10 @@ function normalizeTaskEventSyncPayload(raw, workspaceId, sourceWatermark) {
         : {};
     return {
         id,
-        taskId,
         workspaceId,
+        entityType,
+        entityId,
+        taskId: entityType === 'task' ? (taskId || entityId) : undefined,
         action,
         actor,
         actorType,
@@ -155,7 +180,7 @@ export function registerSyncRoutes(deps) {
     const assertSyncedAiProfilesPersisted = (workspaceId, incomingAiProfiles) => {
         if (incomingAiProfiles.size === 0)
             return;
-        const persistedIds = new Set(core.listAiProfiles(workspaceId)
+        const persistedIds = new Set(core.listAiProfiles(workspaceId, { includeArchived: true })
             .map((profile) => String(profile.id || '').trim())
             .filter(Boolean));
         for (const profile of incomingAiProfiles.values()) {
@@ -240,6 +265,7 @@ export function registerSyncRoutes(deps) {
                 normalizeWorkspaceSyncDocumentPath,
                 normalizeTaskAssetPath: (rawPath) => normalizeTaskDataRelativePath(String(rawPath || '').trim()),
                 normalizeIncomingAiProfileSurfaceType,
+                normalizeIncomingAiProfileSeatScope,
                 normalizeTaskEventSyncPayload,
                 recordSyncDiagnostic,
             });
@@ -624,7 +650,7 @@ export function registerSyncRoutes(deps) {
                     workstream
                 })),
                 ...incomingAiProfiles
-                    .map((profile) => normalizeAiProfileSyncPayload(profile, cloudWorkspaceId, normalizeIncomingAiProfileSurfaceType, 'push.aiProfileUpsert'))
+                    .map((profile) => normalizeAiProfileSyncPayload(profile, cloudWorkspaceId, normalizeIncomingAiProfileSurfaceType, normalizeIncomingAiProfileSeatScope, 'push.aiProfileUpsert'))
                     .filter((profile) => Boolean(profile && profile.id.length > 0))
                     .map((profile) => ({
                     op: 'ai-profile-upsert',
@@ -722,607 +748,47 @@ export function registerSyncRoutes(deps) {
             }));
         }
     });
-    // GET /api/taskforce/sync/workspace/documents - Snapshot markdown documents only.
-    // Binary image/file assets travel through the sibling /assets snapshot and asset-* sync ops.
-    addRoute('GET', '/api/taskforce/sync/workspace/documents', async (req, res) => {
-        const authConfig = context.authConfig;
-        if (authConfig?.runtimeMode === 'cloud') {
-            const access = resolveRequestAccess(req, authConfig);
-            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-                res.writeHead(401, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-                return;
-            }
-        }
-        const workspaceId = requestWorkspaceId(req) || 'default';
-        const basePath = core.getPaths().basePath;
-        const documents = await contentSyncState.listWorkspaceSyncDocumentsSnapshot(basePath, workspaceId);
-        const fingerprint = JSON.stringify(documents.map((doc) => [
-            doc.path,
-            doc.updatedAt,
-            doc.content.length,
-            doc.assetId || '',
-            doc.documentId || '',
-            String(doc.version ?? ''),
-            doc.taskId || '',
-            doc.linkRole || ''
-        ].join(':')));
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            success: true,
-            documents,
-            fingerprint
-        }));
-    });
-    // GET /api/taskforce/sync/workspace/ai-profiles - Snapshot workspace AI profiles for local->cloud sync.
-    addRoute('GET', '/api/taskforce/sync/workspace/ai-profiles', async (req, res) => {
-        const authConfig = context.authConfig;
-        if (authConfig?.runtimeMode === 'cloud') {
-            const access = resolveRequestAccess(req, authConfig);
-            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-                res.writeHead(401, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-                return;
-            }
-        }
-        const workspaceId = requestWorkspaceId(req) || 'default';
-        const aiProfiles = core.listAiProfiles(workspaceId);
-        const fingerprint = JSON.stringify(aiProfiles.map((profile) => [
-            profile.id,
-            profile.updatedAt,
-            profile.name,
-            profile.username,
-            profile.profileToken,
-            profile.surfaceType ?? ''
-        ].join(':')));
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            success: true,
-            aiProfiles,
-            fingerprint
-        }));
-    });
-    // GET /api/taskforce/sync/workspace/document-reviews - Snapshot document review sessions for local->cloud sync.
-    addRoute('GET', '/api/taskforce/sync/workspace/document-reviews', async (req, res) => {
-        const authConfig = context.authConfig;
-        if (authConfig?.runtimeMode === 'cloud') {
-            const access = resolveRequestAccess(req, authConfig);
-            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-                res.writeHead(401, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-                return;
-            }
-        }
-        const workspaceId = requestWorkspaceId(req) || 'default';
-        const sessions = collaborationSyncState.listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId);
-        const comments = collaborationSyncState.listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId);
-        const fingerprint = JSON.stringify([
-            ...sessions.map((session) => [
-                'session',
-                session.id,
-                session.updatedAt,
-                session.status,
-                session.comments.length
-            ].join(':')),
-            ...comments.map((comment) => [
-                'comment',
-                comment.id,
-                comment.sessionId,
-                comment.updatedAt,
-                comment.deletedAt || ''
-            ].join(':'))
-        ]);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            success: true,
-            sessions,
-            comments,
-            fingerprint
-        }));
-    });
-    // GET /api/taskforce/sync/workspace/annotated-attachments - Snapshot Image Notes sessions for local->cloud sync.
-    addRoute('GET', '/api/taskforce/sync/workspace/annotated-attachments', async (req, res) => {
-        const authConfig = context.authConfig;
-        if (authConfig?.runtimeMode === 'cloud') {
-            const access = resolveRequestAccess(req, authConfig);
-            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-                res.writeHead(401, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-                return;
-            }
-        }
-        const workspaceId = requestWorkspaceId(req) || 'default';
-        const sessions = collaborationSyncState.listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId);
-        const fingerprint = JSON.stringify(sessions.map((session) => [
-            session.id,
-            session.updatedAt,
-            session.taskId,
-            session.baseImageAssetId,
-            session.annotations.length,
-            session.deletedAt || ''
-        ].join(':')));
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            success: true,
-            sessions,
-            fingerprint
-        }));
-    });
-    // GET /api/taskforce/sync/workspace/assets - Snapshot non-markdown local assets.
-    // Markdown remains on the /documents snapshot so document encryption/version semantics stay isolated.
-    addRoute('GET', '/api/taskforce/sync/workspace/assets', async (req, res) => {
-        const authConfig = context.authConfig;
-        if (authConfig?.runtimeMode === 'cloud') {
-            const access = resolveRequestAccess(req, authConfig);
-            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-                res.writeHead(401, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-                return;
-            }
-        }
-        const workspaceId = requestWorkspaceId(req) || 'default';
-        const basePath = core.getPaths().basePath;
-        const assets = await contentSyncState.listWorkspaceSyncBinaryAssetsSnapshot(basePath, workspaceId);
-        const fingerprint = JSON.stringify(assets.map((asset) => [
-            asset.path,
-            asset.updatedAt,
-            asset.contentBase64.length,
-            asset.assetId || '',
-            asset.kind,
-            asset.mimeType,
-            asset.taskId || '',
-            asset.originalFilename || '',
-            asset.linkRole || ''
-        ].join(':')));
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            success: true,
-            assets,
-            fingerprint
-        }));
-    });
-    // GET /api/taskforce/sync/workspace/pull - Incremental workspace task deltas with cursor paging
-    addRoute('GET', '/api/taskforce/sync/workspace/pull', async (req, res) => {
-        const authConfig = context.authConfig;
-        if (!authConfig || !authConfig.enabled) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
-            return;
-        }
-        const access = resolveRequestAccess(req, authConfig);
-        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-            auditAuthAction(req, 'sync-workspace-pull-unauthorized', {});
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-            return;
-        }
-        const url = new URL(req.url || '/api/taskforce/sync/workspace/pull', 'http://localhost');
-        const requestedWorkspaceId = String(url.searchParams.get('workspaceId') || '').trim();
-        if (!requestedWorkspaceId) {
-            auditAuthAction(req, 'sync-workspace-pull-missing-workspace', { code: 'WORKSPACE_ID_REQUIRED' });
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: 'workspaceId is required.',
-                code: 'WORKSPACE_ID_REQUIRED',
-                workspaceId: null
-            }));
-            return;
-        }
-        const allowed = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === requestedWorkspaceId);
-        if (!allowed) {
-            auditAuthAction(req, 'sync-workspace-pull-forbidden', {
-                requestedWorkspaceId
-            });
-            res.writeHead(403, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: 'You do not have access to this workspace.',
-                code: 'WORKSPACE_ACCESS_DENIED',
-                workspaceId: requestedWorkspaceId
-            }));
-            return;
-        }
-        const targetWorkspaceId = requestedWorkspaceId;
-        const cursor = decodeWorkspaceSyncCursor(url.searchParams.get('cursor'));
-        const requestedLimit = Number.parseInt(String(url.searchParams.get('limit') || ''), 10);
-        const pageSize = Number.isFinite(requestedLimit) && requestedLimit > 0
-            ? Math.max(1, Math.min(500, Math.floor(requestedLimit)))
-            : 200;
-        const { workspaceMembers, changes, nextCursor, hasMore, diagnostics } = await buildWorkspacePullFeed({
-            core,
-            workspaceId: targetWorkspaceId,
-            cursor,
-            pageSize,
-            encodeWorkspaceSyncCursor,
-            contentSyncState,
-            collaborationSyncState,
-        });
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            success: true,
-            workspaceId: targetWorkspaceId,
-            workspaceMembers,
-            changes,
-            nextCursor,
-            hasMore,
-            diagnostics
-        }));
-        auditAuthAction(req, 'sync-workspace-pull-success', {
-            workspaceId: targetWorkspaceId,
-            returnedChanges: changes.length,
-            hasMore,
-            diagnostics
-        });
-    });
-    // POST /api/taskforce/sync/workspace/apply-local - Apply pulled cloud deltas into local workspace store
-    addRoute('POST', '/api/taskforce/sync/workspace/apply-local', async (req, res) => {
-        const startedAtMs = Date.now();
-        const authConfig = context.authConfig;
-        if (authConfig?.runtimeMode === 'cloud') {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Local apply endpoint is only available in local runtime.' }));
-            return;
-        }
-        const body = await parseJsonBody(req, 50 * 1024 * 1024);
-        const bodyWorkspaceId = String(body?.workspaceId || '').trim();
-        const headerWorkspaceId = String(Array.isArray(req.headers['x-taskforce-workspace-id'])
-            ? req.headers['x-taskforce-workspace-id'][0]
-            : req.headers['x-taskforce-workspace-id'] || '').trim();
-        let workspaceId = bodyWorkspaceId || headerWorkspaceId || requestWorkspaceId(req);
-        if (authConfig?.enabled) {
-            const access = resolveRequestAccess(req, authConfig);
-            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-                auditAuthAction(req, 'sync-workspace-apply-unauthorized', {});
-                res.writeHead(401, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-                return;
-            }
-            if (workspaceId && workspaceId !== 'default' && workspaceId !== 'null') {
-                const allowed = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === workspaceId);
-                if (!allowed) {
-                    auditAuthAction(req, 'sync-workspace-apply-forbidden', {
-                        requestedWorkspaceId: workspaceId
-                    });
-                    res.writeHead(403, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: false,
-                        error: 'You do not have access to this workspace.',
-                        code: 'WORKSPACE_ACCESS_DENIED',
-                        workspaceId
-                    }));
-                    return;
-                }
-            }
-            else {
-                const accessWorkspaceId = String(access.workspaceId || '').trim();
-                if (accessWorkspaceId && accessWorkspaceId !== 'default') {
-                    workspaceId = accessWorkspaceId;
-                }
-            }
-        }
-        if (!workspaceId || workspaceId === 'default' || workspaceId === 'null') {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: 'Workspace ID required.',
-                code: 'WORKSPACE_ID_REQUIRED'
-            }));
-            return;
-        }
-        const incomingChanges = Array.isArray(body?.changes) ? body.changes : [];
-        const workspaceMembers = Array.isArray(body?.workspaceMembers)
-            ? body.workspaceMembers
-                .map((entry) => normalizeWorkspaceMemberSyncSnapshot(workspaceId, entry && typeof entry === 'object' ? entry : null))
-                .filter((entry) => Boolean(entry))
-            : undefined;
-        const allowReferenceNumberReassignment = body?.repair === true;
-        try {
-            const { result, emittedEventIds } = await dispatchWorkspaceSyncChanges(workspaceId, incomingChanges, {
-                allowReferenceNumberReassignment,
-                ...(Array.isArray(workspaceMembers) ? { workspaceMembers } : {})
-            });
-            const durationMs = Date.now() - startedAtMs;
-            core.recordSyncEvent(workspaceId, {
-                eventType: 'apply',
-                status: 'success',
-                changeCount: incomingChanges.length,
-                requestMs: durationMs
-            });
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: true,
-                workspaceId,
-                result,
-                emittedEventIds,
-                durationMs
-            }));
-        }
-        catch (error) {
-            const statusCode = resolveErrorStatusCode(error, 400);
-            const durationMs = Date.now() - startedAtMs;
-            core.recordSyncEvent(workspaceId, {
-                eventType: 'apply',
-                status: 'error',
-                statusCode,
-                errorMessage: String(error?.message || 'Failed to apply local workspace deltas'),
-                changeCount: incomingChanges.length,
-                requestMs: durationMs
-            });
-            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: String(error?.message || 'Failed to apply local workspace deltas'),
-                code: error?.code,
-                details: error?.details || undefined,
-                durationMs
-            }));
-        }
-    });
-    // POST /api/taskforce/sync/workspace/push - Incremental workspace deltas from local to cloud
-    addRoute('POST', '/api/taskforce/sync/workspace/push', async (req, res) => {
-        const startedAtMs = Date.now();
-        const authConfig = context.authConfig;
-        if (!authConfig || !authConfig.enabled) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
-            return;
-        }
-        const access = resolveRequestAccess(req, authConfig);
-        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
-            auditAuthAction(req, 'sync-workspace-push-unauthorized', {});
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-            return;
-        }
-        const body = await parseJsonBody(req, 50 * 1024 * 1024);
-        const requestedWorkspaceId = String(body?.workspaceId || '').trim();
-        if (!requestedWorkspaceId) {
-            auditAuthAction(req, 'sync-workspace-push-missing-workspace', { code: 'WORKSPACE_ID_REQUIRED' });
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: 'workspaceId is required.',
-                code: 'WORKSPACE_ID_REQUIRED',
-                workspaceId: null,
-                durationMs: Date.now() - startedAtMs
-            }));
-            return;
-        }
-        const allowed = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === requestedWorkspaceId);
-        if (!allowed) {
-            auditAuthAction(req, 'sync-workspace-push-forbidden', {
-                requestedWorkspaceId
-            });
-            res.writeHead(403, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: 'You do not have access to this workspace.',
-                code: 'WORKSPACE_ACCESS_DENIED',
-                workspaceId: requestedWorkspaceId
-            }));
-            return;
-        }
-        const targetWorkspaceId = requestedWorkspaceId;
-        const idempotencyKey = String(body?.idempotencyKey || '').trim();
-        if (idempotencyKey) {
-            const replay = readPushIdempotency(targetWorkspaceId, idempotencyKey);
-            if (replay) {
-                auditAuthAction(req, 'sync-workspace-push-idempotent-replay', {
-                    workspaceId: targetWorkspaceId,
-                    idempotencyKey
-                });
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(replay);
-                return;
-            }
-        }
-        let incomingChanges = Array.isArray(body?.changes) ? body.changes : [];
-        const incomingTaskUpsertIds = incomingChanges
-            .filter((change) => change?.op === 'upsert')
-            .map((change) => String(change.task?.id || '').trim())
-            .filter((taskId) => taskId.length > 0);
-        const allowReferenceNumberReassignment = body?.repair === true;
-        // Decrypt asset and document content if TASKFORCE_SYNC_KEY is configured on this server.
-        // The local runtime encrypts content before pushing; the cloud must decrypt before writing to storage.
-        if (typeof process !== 'undefined' && process.env?.TASKFORCE_SYNC_KEY) {
-            const syncKey = process.env.TASKFORCE_SYNC_KEY;
-            const decryptedChanges = [];
-            for (const change of incomingChanges) {
-                if (change.op === 'asset-upsert' && typeof change.contentBase64 === 'string' && change.contentBase64.startsWith(ENCRYPTION_PREFIX)) {
-                    try {
-                        decryptedChanges.push({ ...change, contentBase64: await decryptDocument(change.contentBase64, syncKey) });
-                    }
-                    catch {
-                        decryptedChanges.push(change);
-                    }
-                }
-                else if (change.op === 'document-upsert' && typeof change.content === 'string' && change.content.startsWith(ENCRYPTION_PREFIX)) {
-                    try {
-                        decryptedChanges.push({ ...change, content: await decryptDocument(change.content, syncKey) });
-                    }
-                    catch {
-                        decryptedChanges.push(change);
-                    }
-                }
-                else {
-                    decryptedChanges.push(change);
-                }
-            }
-            incomingChanges = decryptedChanges;
-        }
-        const receivedAtBaseMs = Date.now();
-        incomingChanges = incomingChanges.map((change, index) => {
-            if (change.op !== 'upsert')
-                return change;
-            const task = change.task;
-            const rawReferenceNumber = task.referenceNumber;
-            const incomingReferenceNumber = rawReferenceNumber === undefined || rawReferenceNumber === null
-                ? null
-                : (Number.isFinite(Number(rawReferenceNumber))
-                    ? Math.max(1, Math.floor(Number(rawReferenceNumber)))
-                    : null);
-            if (incomingReferenceNumber)
-                return change;
-            return {
-                ...change,
-                task: {
-                    ...task,
-                    updatedAt: new Date(receivedAtBaseMs + index).toISOString()
-                }
-            };
-        });
-        try {
-            const { result, deleteCount, emittedEventIds } = await dispatchWorkspaceSyncChanges(targetWorkspaceId, incomingChanges, {
-                allowReferenceNumberReassignment
-            });
-            const appliedTaskUpserts = incomingTaskUpsertIds
-                .map((taskId) => core.getTask(taskId, targetWorkspaceId))
-                .filter((task) => Boolean(task))
-                .map((task) => ({
-                archived: Boolean(task.isArchived),
-                task: serializeTaskForSync(task)
-            }));
-            const durationMs = Date.now() - startedAtMs;
-            const payload = JSON.stringify({
-                success: true,
-                workspaceId: targetWorkspaceId,
-                idempotencyKey: idempotencyKey || null,
-                emittedEventIds,
-                appliedTaskUpserts,
-                result,
-                durationMs
-            });
-            if (idempotencyKey) {
-                writePushIdempotency(targetWorkspaceId, idempotencyKey, payload);
-            }
-            core.recordSyncEvent(targetWorkspaceId, {
-                eventType: 'push',
-                status: 'success',
-                changeCount: incomingChanges.length,
-                requestMs: durationMs
-            });
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(payload);
-            auditAuthAction(req, 'sync-workspace-push-success', {
-                workspaceId: targetWorkspaceId,
-                idempotencyKey: idempotencyKey || null,
-                changeCount: incomingChanges.length,
-                deleteCount: deleteCount,
-                durationMs
-            });
-        }
-        catch (error) {
-            const statusCode = resolveErrorStatusCode(error, 400);
-            const durationMs = Date.now() - startedAtMs;
-            core.recordSyncEvent(targetWorkspaceId, {
-                eventType: 'push',
-                status: 'error',
-                statusCode,
-                errorMessage: String(error?.message || 'Failed to apply workspace deltas'),
-                changeCount: incomingChanges.length,
-                requestMs: durationMs
-            });
-            auditAuthAction(req, 'sync-workspace-push-failed', {
-                workspaceId: targetWorkspaceId,
-                code: error?.code || null,
-                statusCode,
-                details: error?.details || null,
-                durationMs
-            });
-            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                success: false,
-                error: String(error?.message || 'Failed to apply workspace deltas'),
-                code: error?.code,
-                details: error?.details || undefined,
-                durationMs
-            }));
-        }
+    registerWorkspaceSnapshotSyncRoutes({
+        addRoute,
+        core,
+        context,
+        resolveRequestAccess,
+        requestWorkspaceId,
+        contentSyncState,
+        collaborationSyncState
     });
-    // GET /api/taskforce/sync/events - Query recent sync events (local runtime only)
-    addRoute('GET', '/api/taskforce/sync/events', async (req, res) => {
-        const authConfig = context.authConfig;
-        const access = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
-        if (access && (!access.authenticated || !access.userId || access.userId === 'anonymous')) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-            return;
-        }
-        const url = new URL(req.url || '/', 'http://localhost');
-        const workspaceId = String(url.searchParams.get('workspace_id') || access?.workspaceId || '').trim() || 'default';
-        const limit = Math.min(500, Math.max(1, Number(url.searchParams.get('limit') || '100')));
-        const events = core.listSyncEvents(workspaceId, limit);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, events }));
+    registerWorkspacePullApplySyncRoutes({
+        addRoute,
+        core,
+        context,
+        auditAuthAction,
+        resolveErrorStatusCode,
+        requestWorkspaceId,
+        resolveRequestAccess,
+        contentSyncState,
+        collaborationSyncState,
+        decodeWorkspaceSyncCursor,
+        encodeWorkspaceSyncCursor,
+        normalizeWorkspaceMemberSyncSnapshot,
+        dispatchWorkspaceSyncChanges
     });
-    // POST /api/taskforce/sync/events - Record a client-side sync event (pull results, handshake outcomes)
-    addRoute('POST', '/api/taskforce/sync/events', async (req, res) => {
-        const authConfig = context.authConfig;
-        const access = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
-        if (access && (!access.authenticated || !access.userId || access.userId === 'anonymous')) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-            return;
-        }
-        const body = await parseJsonBody(req);
-        const allowedEventTypes = ['pull', 'handshake', 'bootstrap', 'apply', 'push'];
-        const eventType = String(body?.eventType || '').trim().toLowerCase();
-        if (!allowedEventTypes.includes(eventType)) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Invalid eventType.' }));
-            return;
-        }
-        const workspaceId = String(body?.workspaceId || access?.workspaceId || '').trim() || 'default';
-        core.recordSyncEvent(workspaceId, {
-            eventType: eventType,
-            status: String(body?.status || '') === 'error' ? 'error' : 'success',
-            statusCode: typeof body?.statusCode === 'number' ? body.statusCode : undefined,
-            errorMessage: typeof body?.errorMessage === 'string' ? body.errorMessage.slice(0, 500) : undefined,
-            changeCount: typeof body?.changeCount === 'number' ? body.changeCount : undefined,
-            requestMs: typeof body?.requestMs === 'number' ? body.requestMs : undefined,
-            details: body?.details && typeof body.details === 'object' && !Array.isArray(body.details)
-                ? body.details
-                : undefined
-        });
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true }));
+    registerWorkspacePushSyncRoutes({
+        addRoute,
+        core,
+        context,
+        auditAuthAction,
+        resolveErrorStatusCode,
+        resolveRequestAccess,
+        readPushIdempotency,
+        writePushIdempotency,
+        dispatchWorkspaceSyncChanges
     });
-    // POST /api/taskforce/sync/workspace/repair-startup - Auto-repair missing asset/document
-    // metadata on workspace open. Only safe fixups: re-registers DB records for files that
-    // exist on disk but have no (or a stale deleted) metadata entry. Never deletes files.
-    // Called once by the sync orchestrator when the workspace becomes active.
-    addRoute('POST', '/api/taskforce/sync/workspace/repair-startup', async (req, res) => {
-        const authConfig = context.authConfig;
-        const access = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
-        if (access && (!access.authenticated || !access.userId || access.userId === 'anonymous')) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
-            return;
-        }
-        const body = await parseJsonBody(req);
-        const workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim() || 'default';
-        if (!workspaceAssetStore) {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: true, applied: 0, skipped: 0, failed: 0, detail: 'Asset store unavailable.' }));
-            return;
-        }
-        const { basePath } = core.getPaths();
-        const result = applyWorkspaceRepair({
-            workspaceId,
-            basePath,
-            tasks: core.listTasks(workspaceId)?.tasks || [],
-            archivedTasks: core.listArchive(workspaceId)?.archived || [],
-            deletedTasks: core.listWorkspaceSyncDeletes(workspaceId) || [],
-            workspaceAssetStore,
-            upsertDocumentWatermark: (targetWorkspaceId, docPath, contentHash, updatedAt) => {
-                core.upsertDocumentWatermark(targetWorkspaceId, docPath, contentHash, updatedAt);
-            }
-        });
-        const applied = result.actionsApplied.filter((a) => a.status === 'applied').length;
-        const failed = result.actionsApplied.filter((a) => a.status === 'failed').length;
-        const skipped = result.actionsApplied.filter((a) => a.status === 'skipped').length;
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, applied, skipped, failed }));
+    registerWorkspaceSyncAuxRoutes({
+        addRoute,
+        core,
+        context,
+        resolveRequestAccess,
+        requestWorkspaceId,
+        workspaceAssetStore
     });
 }