@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/server/routes/syncPullApplyRoutes.d.ts

@@ -1,12 +1,17 @@
 import type { IncomingMessage } from 'http';
 import { buildWorkspacePullFeed } from '../../sync/workspacePullFeed.js';
 import type { WorkspaceSyncChange, WorkspaceSyncWorkspaceMemberSnapshot } from '../../sync/workspaceSyncModel.js';
+import { type WorkspaceSyncV2ProjectionExclusion } from '../../sync/v3/workspaceSyncV2ProjectionExclusions.js';
 import type { SyncAddRoute, SyncResolveRequestAccess, SyncRouteAuthConfig, SyncRouteCore } from './syncRouteTypes.js';
+import type { LocalSyncCoordinatorRouteServices } from '../../sync/coordinator/localSyncCoordinatorRouteServices.js';
+import type { WorkspaceSyncEngineLocalApplyResult } from '../../sync/engine/workspaceSyncEngineLocalApply.js';
+import type { WorkspaceSyncV2PreparedContentPlan } from '../../sync/engine/workspaceSyncV2PreparedContent.js';
 interface RegisterWorkspacePullApplySyncRoutesArgs {
     addRoute: SyncAddRoute;
     core: SyncRouteCore;
     context: {
         authConfig?: SyncRouteAuthConfig | null;
+        localSyncCoordinator?: LocalSyncCoordinatorRouteServices | null;
     };
     auditAuthAction: (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
     resolveErrorStatusCode: (error: unknown, fallback?: number) => number;
@@ -26,11 +31,34 @@ interface RegisterWorkspacePullApplySyncRoutesArgs {
     dispatchWorkspaceSyncChanges: (workspaceId: string, incomingChanges: WorkspaceSyncChange[], options?: {
         allowReferenceNumberReassignment?: boolean;
         workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+        coexistenceDirection?: 'local-pull';
+        v2ExcludedProjections?: readonly WorkspaceSyncV2ProjectionExclusion[];
+        transactionHooks?: {
+            beforeApply?: () => unknown;
+            beforeCommit?: (result: WorkspaceSyncEngineLocalApplyResult) => unknown;
+        };
     }) => Promise<{
         result: any;
         deleteCount: number;
         emittedEventIds: string[];
     }>;
+    dispatchWorkspaceSyncMetadataAtomically: (workspaceId: string, incomingChanges: WorkspaceSyncChange[], options: {
+        allowReferenceNumberReassignment?: boolean;
+        workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+        coexistenceDirection: 'local-pull';
+        v2ExcludedProjections: readonly WorkspaceSyncV2ProjectionExclusion[];
+    }) => WorkspaceSyncEngineLocalApplyResult;
+    prepareWorkspaceSyncV2Content: (workspaceId: string, changes: readonly WorkspaceSyncChange[]) => Promise<WorkspaceSyncV2PreparedContentPlan>;
+    dispatchWorkspaceSyncPreparedContentAtomically: (workspaceId: string, plan: WorkspaceSyncV2PreparedContentPlan, options: {
+        allowReferenceNumberReassignment?: boolean;
+        workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+        coexistenceDirection: 'local-pull';
+        v2ExcludedProjections: readonly WorkspaceSyncV2ProjectionExclusion[];
+        transactionHooks?: {
+            beforeApply?: () => unknown;
+            beforeCommit?: (result: WorkspaceSyncEngineLocalApplyResult) => unknown;
+        };
+    }) => WorkspaceSyncEngineLocalApplyResult;
 }
-export declare function registerWorkspacePullApplySyncRoutes({ addRoute, core, context, auditAuthAction, resolveErrorStatusCode, requestWorkspaceId, resolveRequestAccess, contentSyncState, collaborationSyncState, decodeWorkspaceSyncCursor, encodeWorkspaceSyncCursor, normalizeWorkspaceMemberSyncSnapshot, dispatchWorkspaceSyncChanges }: RegisterWorkspacePullApplySyncRoutesArgs): void;
+export declare function registerWorkspacePullApplySyncRoutes({ addRoute, core, context, auditAuthAction, resolveErrorStatusCode, requestWorkspaceId, resolveRequestAccess, contentSyncState, collaborationSyncState, decodeWorkspaceSyncCursor, encodeWorkspaceSyncCursor, normalizeWorkspaceMemberSyncSnapshot, dispatchWorkspaceSyncChanges, dispatchWorkspaceSyncMetadataAtomically, prepareWorkspaceSyncV2Content, dispatchWorkspaceSyncPreparedContentAtomically, }: RegisterWorkspacePullApplySyncRoutesArgs): void;
 export {};

package/dist/server/routes/syncPullApplyRoutes.js

@@ -1,7 +1,13 @@
-import { buildWorkspacePullFeed } from '../../sync/workspacePullFeed.js';
+import { DEFAULT_WORKSPACE_PULL_PAGE_MAX_BYTES, buildWorkspacePullFeed, WorkspacePullEntryTooLargeError, } from '../../sync/workspacePullFeed.js';
+import { applyWorkspaceSyncLocalBatch } from '../../sync/engine/workspaceSyncEngineLocalApply.js';
 import { parseJsonBody } from './primitives.js';
+import { normalizeWorkspaceSyncV2ProjectionExclusions, parseWorkspaceSyncV2ProjectionExclusions, WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS, } from '../../sync/v3/workspaceSyncV2ProjectionExclusions.js';
+import { resolveWorkspaceSyncV3AttestedV2Exclusions } from '../../sync/v3/workspaceSyncV3LegacyBoundaryAttestation.js';
 import { requireAuthenticatedSyncRequest, requireEnabledSyncAuth, resolveAuthorizedSyncWorkspace, } from './syncRouteGuards.js';
-export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context, auditAuthAction, resolveErrorStatusCode, requestWorkspaceId, resolveRequestAccess, contentSyncState, collaborationSyncState, decodeWorkspaceSyncCursor, encodeWorkspaceSyncCursor, normalizeWorkspaceMemberSyncSnapshot, dispatchWorkspaceSyncChanges }) {
+import { completeLocalSyncBrowserPushEchoPermitGroup, createLocalSyncBrowserV2ApplyTransactionHooks, parseLocalSyncBrowserApplyPermitContext, resolveLocalSyncBrowserApplyPermitOperationClass, } from '../../sync/coordinator/localSyncBrowserApplyPermitContext.js';
+import { WorkspaceSyncContentPullObligationStore, } from '../../sync/engine/workspaceSyncContentPullObligationStore.js';
+import { fingerprintWorkspaceContentBody } from '../../sync/workspaceContentManifest.js';
+export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context, auditAuthAction, resolveErrorStatusCode, requestWorkspaceId, resolveRequestAccess, contentSyncState, collaborationSyncState, decodeWorkspaceSyncCursor, encodeWorkspaceSyncCursor, normalizeWorkspaceMemberSyncSnapshot, dispatchWorkspaceSyncChanges, dispatchWorkspaceSyncMetadataAtomically, prepareWorkspaceSyncV2Content, dispatchWorkspaceSyncPreparedContentAtomically, }) {
     // 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;
@@ -34,7 +40,50 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
             return;
         }
         const repairMode = url.searchParams.get('repair') === '1' || url.searchParams.get('repair') === 'true';
-        const rawCursor = repairMode ? '' : String(url.searchParams.get('cursor') || '').trim();
+        const includeInitiatives = url.searchParams.get('excludeInitiatives') !== '1';
+        let excludedProjections;
+        try {
+            excludedProjections = parseWorkspaceSyncV2ProjectionExclusions(url.searchParams.get('excludeProjections'));
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, code: 'INVALID_SYNC_V2_PROJECTION_EXCLUSIONS',
+                error: 'Invalid workspace sync v2 projection exclusions.' }));
+            return;
+        }
+        const coverageKeys = ['coverageProfileId', 'coverageVersion', 'coverageDigest'];
+        const hasCoverageSelector = coverageKeys.some((key) => url.searchParams.has(key));
+        if (hasCoverageSelector) {
+            const coverage = coverageKeys.every((key) => url.searchParams.getAll(key).length === 1)
+                ? {
+                    coverageProfileId: url.searchParams.get('coverageProfileId'),
+                    coverageVersion: url.searchParams.get('coverageVersion'),
+                    coverageDigest: url.searchParams.get('coverageDigest'),
+                }
+                : null;
+            const attested = coverage && resolveWorkspaceSyncV3AttestedV2Exclusions({
+                coverage,
+                excludedProjections: String(url.searchParams.get('excludeProjections') || '')
+                    .split(',').filter(Boolean),
+            });
+            if (!attested) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, code: 'SYNC_V2_PROJECTION_BOUNDARY_MISMATCH',
+                    error: 'Workspace sync v2 projection boundary attestation is invalid.' }));
+                return;
+            }
+            excludedProjections = [...attested];
+        }
+        else if (excludedProjections.some((projection) => !WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS.includes(projection))) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, code: 'SYNC_V2_PROJECTION_BOUNDARY_MISMATCH',
+                error: 'Workspace sync v2 projection boundary attestation is required for nested exclusions.' }));
+            return;
+        }
+        const contentMode = url.searchParams.get('content') === 'manifest' ? 'manifest' : 'full';
+        // Repair starts from a null cursor at the caller, but subsequent pages must
+        // honor the returned cursor or a multi-page repair will replay page one.
+        const rawCursor = String(url.searchParams.get('cursor') || '').trim();
         const cursor = decodeWorkspaceSyncCursor(rawCursor);
         if (rawCursor && !cursor) {
             auditAuthAction(req, 'sync-workspace-pull-invalid-cursor', {
@@ -52,15 +101,38 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
         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,
-        });
+        let pullFeed;
+        try {
+            pullFeed = await buildWorkspacePullFeed({
+                core,
+                workspaceId: targetWorkspaceId,
+                cursor,
+                pageSize,
+                encodeWorkspaceSyncCursor,
+                contentSyncState,
+                collaborationSyncState,
+                contentMode,
+                includeInitiatives,
+                excludedProjections,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof WorkspacePullEntryTooLargeError))
+                throw error;
+            auditAuthAction(req, 'sync-workspace-pull-entry-too-large', {
+                workspaceId: targetWorkspaceId,
+                ...error.details,
+            });
+            res.writeHead(error.statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: error.message,
+                code: error.code,
+                details: error.details,
+            }));
+            return;
+        }
+        const { workspaceMembers, changes, nextCursor, hasMore, diagnostics } = pullFeed;
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
             success: true,
@@ -69,6 +141,7 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
             changes,
             nextCursor,
             hasMore,
+            excludedProjections,
             diagnostics
         }));
         try {
@@ -77,6 +150,9 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
                 returnedChanges: changes.length,
                 hasMore,
                 repairMode,
+                contentMode,
+                includeInitiatives,
+                excludedProjections,
                 diagnostics
             });
         }
@@ -84,6 +160,272 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
             // post-response diagnostics must never cause an unhandled rejection
         }
     });
+    // POST /api/taskforce/sync/workspace/content - Bounded body hydration for manifest reconciliation.
+    addRoute('POST', '/api/taskforce/sync/workspace/content', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!requireEnabledSyncAuth(res, authConfig))
+            return;
+        const access = requireAuthenticatedSyncRequest({
+            req,
+            res,
+            authConfig,
+            resolveRequestAccess,
+            auditAuthAction,
+            unauthorizedAuditAction: 'sync-workspace-content-unauthorized'
+        });
+        if (!access)
+            return;
+        const body = await parseJsonBody(req, 1024 * 1024);
+        const targetWorkspaceId = resolveAuthorizedSyncWorkspace({
+            req,
+            res,
+            core,
+            access,
+            requestedWorkspaceId: String(body?.workspaceId || '').trim(),
+            auditAuthAction,
+            missingWorkspaceAuditAction: 'sync-workspace-content-missing-workspace',
+            forbiddenWorkspaceAuditAction: 'sync-workspace-content-forbidden'
+        });
+        if (!targetWorkspaceId)
+            return;
+        const rawRequests = Array.isArray(body?.requests) ? body.requests : [];
+        if (rawRequests.length < 1 || rawRequests.length > 100) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Content requests must contain between 1 and 100 entries.', code: 'INVALID_CONTENT_REQUEST_COUNT' }));
+            return;
+        }
+        const assetIdRequestCount = rawRequests.filter((entry) => (Boolean(entry && typeof entry === 'object' && !Array.isArray(entry)
+            && String(entry.assetId || '').trim()))).length;
+        if (assetIdRequestCount > 0 && (assetIdRequestCount !== 1 || rawRequests.length !== 1)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'Asset identity hydration accepts exactly one asset request.',
+                code: 'INVALID_CONTENT_REQUEST_COUNT'
+            }));
+            return;
+        }
+        const requests = rawRequests.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                return [];
+            const value = entry;
+            const kind = value.kind === 'document' ? 'document' : value.kind === 'asset' ? 'asset' : null;
+            const path = String(value.path || '').trim();
+            const assetId = String(value.assetId || '').trim();
+            if (kind === 'asset' && assetId && !path)
+                return [{ kind, assetId }];
+            return kind && path ? [{ kind, path }] : [];
+        });
+        if (requests.length !== rawRequests.length) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'Every content request requires a valid kind and path, or an asset kind and assetId.',
+                code: 'INVALID_CONTENT_REQUEST'
+            }));
+            return;
+        }
+        const changes = [];
+        const missing = [];
+        const [documentIndex, assetIndex] = await Promise.all([
+            contentSyncState.listWorkspaceSyncDocumentIndex(core.getPaths().basePath, targetWorkspaceId),
+            contentSyncState.listWorkspaceSyncBinaryAssetIndex(targetWorkspaceId),
+        ]);
+        const documentIndexByPath = new Map(documentIndex.map((entry) => [entry.path, entry]));
+        const assetIndexByPath = new Map(assetIndex.map((entry) => [entry.path, entry]));
+        const contentMetadata = [];
+        let responseBytes = Buffer.byteLength(JSON.stringify({
+            success: true, changes: [], missing: [], remaining: [], contentMetadata: [],
+        }), 'utf8');
+        let consumed = 0;
+        for (const request of requests) {
+            let change = null;
+            let metadataEntry = null;
+            let requestedAsset = null;
+            if (request.kind === 'document') {
+                const payload = await contentSyncState.loadWorkspaceSyncDocumentPayload(core.getPaths().basePath, targetWorkspaceId, request.path);
+                if (payload) {
+                    change = {
+                        op: 'document-upsert',
+                        ...payload,
+                        linkRole: payload.linkRole === 'reference' ? 'reference' : 'attachment',
+                    };
+                }
+            }
+            else {
+                requestedAsset = 'assetId' in request
+                    ? core.getWorkspaceAssetStore().get(request.assetId, targetWorkspaceId)
+                    : null;
+                const assetPath = 'assetId' in request
+                    ? requestedAsset && !requestedAsset.deletedAt ? requestedAsset.storageKey : ''
+                    : request.path;
+                if (assetPath && requestedAsset?.kind === 'document') {
+                    const payload = await contentSyncState.loadWorkspaceSyncDocumentPayload(core.getPaths().basePath, targetWorkspaceId, assetPath);
+                    if (payload) {
+                        change = {
+                            op: 'document-upsert',
+                            ...payload,
+                            linkRole: payload.linkRole === 'reference' ? 'reference' : 'attachment',
+                        };
+                    }
+                }
+                else if (assetPath) {
+                    const payload = await contentSyncState.loadWorkspaceSyncBinaryAssetPayload(core.getPaths().basePath, targetWorkspaceId, assetPath);
+                    if (payload)
+                        change = { op: 'asset-upsert', ...payload };
+                }
+            }
+            if (change && (change.op === 'document-upsert' || change.op === 'asset-upsert')) {
+                const kind = change.op === 'document-upsert' ? 'document' : 'asset';
+                const indexEntry = kind === 'document'
+                    ? documentIndexByPath.get(change.path)
+                    : assetIndexByPath.get(change.path);
+                const fallbackFingerprint = indexEntry
+                    ? null
+                    : await fingerprintWorkspaceContentBody(kind, change.op === 'document-upsert' ? change.content : change.contentBase64);
+                metadataEntry = {
+                    kind,
+                    path: change.path,
+                    ...('assetId' in request && requestedAsset
+                        ? { assetId: requestedAsset.assetId }
+                        : {}),
+                    sha256: String(indexEntry?.contentSha256
+                        || requestedAsset?.contentSha256
+                        || fallbackFingerprint?.sha256
+                        || '').toLowerCase(),
+                    sizeBytes: Number(indexEntry?.sizeBytes
+                        ?? requestedAsset?.sizeBytes
+                        ?? fallbackFingerprint?.sizeBytes
+                        ?? 0),
+                    updatedAt: String(indexEntry?.updatedAt || change.updatedAt || ''),
+                };
+            }
+            if (!change) {
+                missing.push(request);
+                consumed += 1;
+                continue;
+            }
+            const changeBytes = Buffer.byteLength(JSON.stringify(change), 'utf8')
+                + (metadataEntry ? Buffer.byteLength(JSON.stringify(metadataEntry), 'utf8') + 1 : 0)
+                + (changes.length > 0 ? 1 : 0);
+            if (changes.length === 0 && responseBytes + changeBytes > DEFAULT_WORKSPACE_PULL_PAGE_MAX_BYTES) {
+                res.writeHead(413, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    success: false,
+                    error: 'Requested workspace content exceeds the maximum transfer size.',
+                    code: 'WORKSPACE_SYNC_ENTRY_TOO_LARGE',
+                    details: { kind: request.kind, path: request.path, maxPageBytes: DEFAULT_WORKSPACE_PULL_PAGE_MAX_BYTES }
+                }));
+                return;
+            }
+            if (responseBytes + changeBytes > DEFAULT_WORKSPACE_PULL_PAGE_MAX_BYTES)
+                break;
+            changes.push(change);
+            if (metadataEntry)
+                contentMetadata.push(metadataEntry);
+            responseBytes += changeBytes;
+            consumed += 1;
+        }
+        const remaining = requests.slice(consumed);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, changes, missing, remaining, contentMetadata }));
+    });
+    addRoute('GET', '/api/taskforce/sync/workspace/content-obligations', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Content obligations are local-runtime state.' }));
+            return;
+        }
+        let workspaceId = String(requestWorkspaceId(req) || '').trim();
+        if (authConfig?.enabled) {
+            const access = requireAuthenticatedSyncRequest({
+                req,
+                res,
+                authConfig,
+                resolveRequestAccess,
+                auditAuthAction,
+                unauthorizedAuditAction: 'sync-content-obligations-unauthorized',
+            });
+            if (!access)
+                return;
+            const authorizedWorkspaceId = resolveAuthorizedSyncWorkspace({
+                req,
+                res,
+                core,
+                access,
+                requestedWorkspaceId: workspaceId,
+                auditAuthAction,
+                forbiddenWorkspaceAuditAction: 'sync-content-obligations-forbidden',
+            });
+            if (!authorizedWorkspaceId)
+                return;
+            workspaceId = authorizedWorkspaceId;
+        }
+        if (!workspaceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Workspace ID required.' }));
+            return;
+        }
+        const requestUrl = new URL(req.url || '/', 'http://localhost');
+        const limit = Math.max(1, Math.min(100, Number(requestUrl.searchParams.get('limit')) || 100));
+        const obligations = new WorkspaceSyncContentPullObligationStore(core.getDatabaseAdapter())
+            .listOpen({ tenantId: core.getTenantId(), workspaceId, limit });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, obligations }));
+    });
+    addRoute('POST', '/api/taskforce/sync/workspace/content-obligations/failures', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Content obligations are local-runtime state.' }));
+            return;
+        }
+        const body = await parseJsonBody(req, 256 * 1024);
+        let workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim();
+        if (authConfig?.enabled) {
+            const access = requireAuthenticatedSyncRequest({
+                req,
+                res,
+                authConfig,
+                resolveRequestAccess,
+                auditAuthAction,
+                unauthorizedAuditAction: 'sync-content-obligation-failures-unauthorized',
+            });
+            if (!access)
+                return;
+            const authorizedWorkspaceId = resolveAuthorizedSyncWorkspace({
+                req,
+                res,
+                core,
+                access,
+                requestedWorkspaceId: workspaceId,
+                auditAuthAction,
+                forbiddenWorkspaceAuditAction: 'sync-content-obligation-failures-forbidden',
+            });
+            if (!authorizedWorkspaceId)
+                return;
+            workspaceId = authorizedWorkspaceId;
+        }
+        const obligationIds = Array.isArray(body?.obligationIds)
+            ? body.obligationIds.map((entry) => String(entry || '').trim()).filter(Boolean)
+            : [];
+        if (!workspaceId || obligationIds.length < 1 || obligationIds.length > 100) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Workspace and 1-100 obligation ids are required.' }));
+            return;
+        }
+        new WorkspaceSyncContentPullObligationStore(core.getDatabaseAdapter())
+            .recordAttemptFailure({
+            tenantId: core.getTenantId(),
+            workspaceId,
+            obligationIds,
+            error: String(body?.error || 'Content body remains unavailable.'),
+            now: new Date().toISOString(),
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
     // 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();
@@ -143,17 +485,178 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
             return;
         }
         const incomingChanges = Array.isArray(body?.changes) ? body.changes : [];
+        let permitContext;
+        try {
+            permitContext = parseLocalSyncBrowserApplyPermitContext(body);
+        }
+        catch (error) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                code: 'INVALID_LOCAL_SYNC_BROWSER_APPLY_PERMIT_CONTEXT',
+                error: String(error?.message || error),
+            }));
+            return;
+        }
+        let v2ExcludedProjections;
+        try {
+            if (body?.excludedProjections !== undefined && !Array.isArray(body.excludedProjections))
+                throw new Error();
+            v2ExcludedProjections = normalizeWorkspaceSyncV2ProjectionExclusions(body?.excludedProjections || []);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, code: 'INVALID_SYNC_V2_PROJECTION_EXCLUSIONS',
+                error: 'Invalid workspace sync v2 projection exclusions.' }));
+            return;
+        }
         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;
+        const contentPullObligations = Array.isArray(body?.contentPullObligations)
+            ? body.contentPullObligations.filter((entry) => (Boolean(entry && typeof entry === 'object' && !Array.isArray(entry))))
+            : [];
+        const contentPullResolutionClaims = Array.isArray(body?.contentPullResolutionClaims)
+            ? body.contentPullResolutionClaims.filter((entry) => {
+                if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                    return false;
+                const claim = entry;
+                if ((claim.kind !== 'document' && claim.kind !== 'asset')
+                    || !String(claim.path || '').trim()
+                    || !String(claim.sourceWatermark || '').trim()) {
+                    return false;
+                }
+                if (claim.resolution === 'at-or-before-watermark')
+                    return true;
+                return claim.resolution === 'exact-version'
+                    && Boolean(String(claim.metadataFingerprint || '').trim());
+            })
+            : [];
         try {
-            const { result, emittedEventIds } = await dispatchWorkspaceSyncChanges(workspaceId, incomingChanges, {
-                allowReferenceNumberReassignment,
-                ...(Array.isArray(workspaceMembers) ? { workspaceMembers } : {})
-            });
+            const coordinatorServices = permitContext
+                ? (() => {
+                    if (!context.localSyncCoordinator) {
+                        throw new Error('Local sync coordinator services are required for browser apply.');
+                    }
+                    return context.localSyncCoordinator;
+                })()
+                : null;
+            const permitOperationClass = permitContext && coordinatorServices
+                ? resolveLocalSyncBrowserApplyPermitOperationClass({
+                    services: coordinatorServices,
+                    cookieHeader: req.headers.cookie,
+                    workspaceId,
+                    context: permitContext,
+                })
+                : null;
+            let applyResult;
+            if (permitContext && coordinatorServices && permitOperationClass === 'push') {
+                applyResult = completeLocalSyncBrowserPushEchoPermitGroup({
+                    services: coordinatorServices,
+                    cookieHeader: req.headers.cookie,
+                    workspaceId,
+                    context: permitContext,
+                    applyAuthoritativeEchoes: () => {
+                        if (incomingChanges.length === 0
+                            || incomingChanges.some((change) => (change.op !== 'upsert'
+                                || !change.task
+                                || !String(change.task.id || '').trim()))
+                            || workspaceMembers !== undefined
+                            || body?.bootstrapSnapshot !== undefined
+                            || allowReferenceNumberReassignment
+                            || v2ExcludedProjections.length > 0) {
+                            throw new Error('Browser push echo apply accepts only authoritative task upserts.');
+                        }
+                        return dispatchWorkspaceSyncMetadataAtomically(workspaceId, incomingChanges, {
+                            allowReferenceNumberReassignment: false,
+                            coexistenceDirection: 'local-pull',
+                            v2ExcludedProjections: [],
+                        });
+                    },
+                });
+            }
+            else {
+                const permitTransactionHooks = permitContext
+                    && coordinatorServices
+                    && (permitOperationClass === 'pull' || permitOperationClass === 'repair')
+                    ? createLocalSyncBrowserV2ApplyTransactionHooks({
+                        services: coordinatorServices,
+                        cookieHeader: req.headers.cookie,
+                        workspaceId,
+                        context: permitContext,
+                        operationClass: permitOperationClass,
+                    })
+                    : undefined;
+                const obligationStore = (contentPullObligations.length > 0
+                    || contentPullResolutionClaims.length > 0)
+                    ? new WorkspaceSyncContentPullObligationStore(core.getDatabaseAdapter())
+                    : null;
+                const transactionHooks = (permitTransactionHooks
+                    || contentPullObligations.length > 0
+                    || contentPullResolutionClaims.length > 0)
+                    ? {
+                        beforeApply: () => {
+                            permitTransactionHooks?.beforeApply?.();
+                            if (contentPullObligations.length > 0) {
+                                obligationStore.upsertMany({
+                                    tenantId: core.getTenantId(),
+                                    workspaceId,
+                                    obligations: contentPullObligations,
+                                    now: new Date().toISOString(),
+                                });
+                            }
+                        },
+                        beforeCommit: (result) => {
+                            if (contentPullResolutionClaims.length > 0) {
+                                obligationStore.resolveMany({
+                                    tenantId: core.getTenantId(),
+                                    workspaceId,
+                                    claims: contentPullResolutionClaims,
+                                    now: new Date().toISOString(),
+                                });
+                            }
+                            return permitTransactionHooks?.beforeCommit?.(result);
+                        },
+                    }
+                    : undefined;
+                if (transactionHooks
+                    && ((permitOperationClass === 'repair') !== allowReferenceNumberReassignment)) {
+                    throw new Error('Browser V2 apply repair mode does not match its execution permits.');
+                }
+                applyResult = await applyWorkspaceSyncLocalBatch({
+                    workspaceId,
+                    changes: incomingChanges,
+                    allowReferenceNumberReassignment,
+                    v2ExcludedProjections,
+                    ...(Array.isArray(workspaceMembers) ? { workspaceMembers } : {}),
+                }, {
+                    content: {
+                        loadDocument: (targetWorkspaceId, contentPath) => contentSyncState.loadWorkspaceSyncDocumentPayload(core.getPaths().basePath, targetWorkspaceId, contentPath),
+                        loadAsset: (targetWorkspaceId, contentPath) => contentSyncState.loadWorkspaceSyncBinaryAssetPayload(core.getPaths().basePath, targetWorkspaceId, contentPath),
+                    },
+                    dispatcher: {
+                        dispatch: (targetWorkspaceId, changes, options) => (dispatchWorkspaceSyncChanges(targetWorkspaceId, changes, {
+                            ...options,
+                            ...(transactionHooks ? { transactionHooks } : {}),
+                        })),
+                    },
+                    ...(transactionHooks
+                        ? {
+                            preparedContent: {
+                                prepare: prepareWorkspaceSyncV2Content,
+                                dispatcher: {
+                                    dispatchPreparedContentAtomically: dispatchWorkspaceSyncPreparedContentAtomically,
+                                },
+                                transactionHooks,
+                            },
+                        }
+                        : {}),
+                });
+            }
+            const { result, emittedEventIds } = applyResult;
             const durationMs = Date.now() - startedAtMs;
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
@@ -176,7 +679,7 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
             }
         }
         catch (error) {
-            const statusCode = resolveErrorStatusCode(error, 400);
+            const statusCode = resolveErrorStatusCode(error, permitContext ? 409 : 400);
             const durationMs = Date.now() - startedAtMs;
             res.writeHead(statusCode, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({