@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/server/routes/syncCoordinatorLocalRoutes.js

@@ -0,0 +1,867 @@
+import { parseWorkspaceSyncEngineV2PushBoundary, } from '../../sync/engine/workspaceSyncEnginePushCompletion.js';
+import { parseJsonBody } from './primitives.js';
+const BASE_PATH = '/api/taskforce/sync/v3/local/coordinator';
+const OPERATION_CLASSES = new Set([
+    'handshake',
+    'bootstrap',
+    'push',
+    'pull',
+    'repair',
+    'v3-dispatch',
+    'local-apply',
+]);
+const BROWSER_COMMAND_TYPES = new Set([
+    'EnableSync',
+    'DisableSync',
+    'Sync',
+    'Retry',
+    'Repair',
+]);
+const BROWSER_WAKE_SOURCES = new Set(['realtime', 'connectivity']);
+const MAX_WAKE_EVENT_IDS = 512;
+const COMMAND_WAKE_COALESCE_MS = 10;
+function writeJson(res, statusCode, body) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(body));
+}
+function errorCode(error) {
+    return String(error?.code || 'SYNC_COORDINATOR_REQUEST_FAILED');
+}
+function errorStatus(error) {
+    const explicitStatus = Number(error?.statusCode);
+    if (Number.isInteger(explicitStatus) && explicitStatus >= 400 && explicitStatus <= 599) {
+        return explicitStatus;
+    }
+    const code = errorCode(error);
+    if (code.includes('AUTH_REQUIRED') || code.includes('AUTH_INVALID'))
+        return 401;
+    if (code.includes('PRINCIPAL_CONFLICT'))
+        return 403;
+    if (code.includes('NOT_FOUND'))
+        return 404;
+    if (code.includes('UNAVAILABLE') || code.includes('REQUEST_FAILED'))
+        return 503;
+    return 409;
+}
+function publicErrorMessage(code) {
+    if (code.includes('AUTH_REQUIRED'))
+        return 'An authenticated Taskforce session is required.';
+    if (code.includes('AUTH_INVALID'))
+        return 'The Taskforce session is invalid.';
+    if (code.includes('ACCESS_BOOTSTRAP')) {
+        return 'Verified cloud workspace access could not be initialized locally.';
+    }
+    if (code.includes('PRINCIPAL_CONFLICT'))
+        return 'A different browser principal owns this sync capability.';
+    if (code.includes('STALE_GENERATION'))
+        return 'The local sync coordinator generation is stale.';
+    if (code.includes('INACTIVE_WORKSPACE'))
+        return 'The workspace is not active in the local sync coordinator.';
+    if (code.includes('NOT_FOUND'))
+        return 'The requested coordinator record was not found.';
+    if (code.includes('RESPONSE_TOO_LARGE'))
+        return 'The cloud sync response exceeded its allowed size.';
+    if (code.includes('OPERATION_INVALID'))
+        return 'The requested sync operation is invalid.';
+    if (code.includes('PERMIT'))
+        return 'The sync execution permit could not complete this action.';
+    if (code.includes('UNAVAILABLE'))
+        return 'The local sync coordinator is unavailable.';
+    if (code.includes('SERVER_OWNERSHIP_DISABLED')) {
+        return 'Server-owned local synchronization is not enabled.';
+    }
+    return 'The local sync coordinator request failed.';
+}
+function writeError(res, error) {
+    const code = errorCode(error);
+    writeJson(res, errorStatus(error), {
+        success: false,
+        error: publicErrorMessage(code),
+        code,
+    });
+}
+function readUrl(req) {
+    return new URL(req.url || BASE_PATH, 'http://localhost');
+}
+function boundedGeneration(raw) {
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 0 ? value : -1;
+}
+function boundedIdentifier(raw, field, maxLength = 256) {
+    const value = String(raw || '').trim();
+    if (!value || value.length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
+        const error = new Error(`The ${field} is invalid.`);
+        error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+        throw error;
+    }
+    return value;
+}
+function boundedWakeEventIds(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || raw.length > MAX_WAKE_EVENT_IDS) {
+        const error = new Error('The realtime event IDs are invalid.');
+        error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+        throw error;
+    }
+    return Array.from(new Set(raw.map((value) => boundedIdentifier(value, 'realtime event ID', 512))));
+}
+function boundedSha256(raw, field) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(value)) {
+        const error = new Error(`The ${field} is invalid.`);
+        error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+        throw error;
+    }
+    return value;
+}
+function assertAuthoritativeState(state, workspaceId, expectedGeneration) {
+    if (state.coordinatorGeneration !== expectedGeneration) {
+        const error = new Error(`Coordinator generation ${expectedGeneration} is stale; current generation is ${state.coordinatorGeneration}.`);
+        error.code = 'SYNC_COORDINATOR_STALE_GENERATION';
+        throw error;
+    }
+    if (!workspaceId || state.activeWorkspaceId !== workspaceId) {
+        const error = new Error(`Workspace ${workspaceId || '(missing)'} is not the active local sync workspace.`);
+        error.code = 'SYNC_COORDINATOR_INACTIVE_WORKSPACE';
+        throw error;
+    }
+}
+export function registerLocalSyncCoordinatorRoutes(input) {
+    const services = input.services;
+    if (!services)
+        return;
+    const recoverExpiredPermits = (workspaceId) => services.permitStore.recoverExpiredPermits({
+        currentServerInstanceId: services.host.serverInstanceId,
+        workspaceId,
+        excludePermitIds: services.transportGateway.inFlightPermitIds,
+    });
+    const authorizeAttachedBrowser = (req, workspaceId, coordinatorGeneration) => {
+        if (services.credentialBroker.readSnapshot().status !== 'ready')
+            return;
+        services.credentialBroker.authorizeCookieHeader({
+            cookieHeader: req.headers.cookie,
+            workspaceId,
+            coordinatorGeneration,
+        });
+    };
+    const requireAttachedBrowser = (req, workspaceId, coordinatorGeneration) => {
+        services.credentialBroker.authorizeCookieHeader({
+            cookieHeader: req.headers.cookie,
+            workspaceId,
+            coordinatorGeneration,
+        });
+    };
+    const resumeBoundCredential = async (credential, fallbackState) => {
+        try {
+            return {
+                state: await services.onCredentialBound?.(credential) || fallbackState,
+                runtimeResumePending: false,
+                runtimeResumeErrorCode: null,
+            };
+        }
+        catch (resumeError) {
+            return {
+                state: fallbackState,
+                runtimeResumePending: true,
+                runtimeResumeErrorCode: errorCode(resumeError),
+            };
+        }
+    };
+    input.addRoute('POST', `${BASE_PATH}/attach`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = boundedIdentifier(body.workspaceId, 'workspace ID');
+            const initialState = services.host.readState();
+            if (initialState.activeWorkspaceId
+                && initialState.activeWorkspaceId !== workspaceId) {
+                const error = new Error(`Workspace ${workspaceId} is not the active local sync workspace.`);
+                error.code = 'SYNC_COORDINATOR_INACTIVE_WORKSPACE';
+                throw error;
+            }
+            let credential;
+            try {
+                credential = await services.credentialBroker.bindFromCookieHeader({
+                    cookieHeader: req.headers.cookie,
+                    workspaceId,
+                    coordinatorGeneration: initialState.coordinatorGeneration,
+                });
+            }
+            catch (error) {
+                const concurrentState = services.host.readState();
+                if (errorCode(error) !== 'SYNC_COORDINATOR_STALE_GENERATION'
+                    || concurrentState.activeWorkspaceId !== workspaceId
+                    || concurrentState.transitionState !== 'idle') {
+                    throw error;
+                }
+                const concurrentCredential = await services.credentialBroker.bindFromCookieHeader({
+                    cookieHeader: req.headers.cookie,
+                    workspaceId,
+                    coordinatorGeneration: concurrentState.coordinatorGeneration,
+                });
+                const resume = await resumeBoundCredential(concurrentCredential, concurrentState);
+                writeJson(res, 200, {
+                    success: true,
+                    credential: concurrentCredential,
+                    serverInstanceId: services.host.serverInstanceId,
+                    ...resume,
+                });
+                return;
+            }
+            if (initialState.activeWorkspaceId === workspaceId) {
+                const resume = await resumeBoundCredential(credential, initialState);
+                writeJson(res, 200, {
+                    success: true,
+                    credential,
+                    serverInstanceId: services.host.serverInstanceId,
+                    ...resume,
+                });
+                return;
+            }
+            let state;
+            try {
+                state = await services.host.switchWorkspace({
+                    expectedActiveWorkspaceId: null,
+                    targetWorkspaceId: workspaceId,
+                    expectedCoordinatorGeneration: initialState.coordinatorGeneration,
+                    requestedBy: credential.principal,
+                });
+            }
+            catch (error) {
+                const concurrentState = services.host.readState();
+                if (concurrentState.activeWorkspaceId !== workspaceId
+                    || concurrentState.transitionState !== 'idle') {
+                    if (concurrentState.activeWorkspaceId === null) {
+                        services.credentialBroker.clear('workspace-attach-failed');
+                    }
+                    throw error;
+                }
+                const concurrentCredential = await services.credentialBroker.bindFromCookieHeader({
+                    cookieHeader: req.headers.cookie,
+                    workspaceId,
+                    coordinatorGeneration: concurrentState.coordinatorGeneration,
+                });
+                const resume = await resumeBoundCredential(concurrentCredential, concurrentState);
+                writeJson(res, 200, {
+                    success: true,
+                    credential: concurrentCredential,
+                    serverInstanceId: services.host.serverInstanceId,
+                    ...resume,
+                });
+                return;
+            }
+            const advancedCredential = services.credentialBroker.advanceCoordinatorGeneration({
+                cookieHeader: req.headers.cookie,
+                workspaceId,
+                fromCoordinatorGeneration: initialState.coordinatorGeneration,
+                toCoordinatorGeneration: state.coordinatorGeneration,
+            });
+            const resume = await resumeBoundCredential(advancedCredential, state);
+            writeJson(res, 200, {
+                success: true,
+                credential: advancedCredential,
+                serverInstanceId: services.host.serverInstanceId,
+                ...resume,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/workspace-switch`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const commandId = boundedIdentifier(body.commandId, 'command ID');
+            const expectedActiveWorkspaceId = boundedIdentifier(body.expectedActiveWorkspaceId, 'expected active workspace ID');
+            const targetWorkspaceId = boundedIdentifier(body.targetWorkspaceId, 'target workspace ID');
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            if (body.version !== 1 || expectedActiveWorkspaceId === targetWorkspaceId) {
+                const error = new Error('The coordinator workspace-switch command is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const existing = services.host.readCommand(commandId);
+            const existingArgs = existing?.args;
+            if (existing
+                && (existing.type !== 'SwitchWorkspace'
+                    || existing.version !== 1
+                    || existing.workspaceId !== expectedActiveWorkspaceId
+                    || existing.expectedCoordinatorGeneration !== expectedGeneration
+                    || existingArgs?.expectedActiveWorkspaceId !== expectedActiveWorkspaceId
+                    || existingArgs?.targetWorkspaceId !== targetWorkspaceId)) {
+                const error = new Error('The coordinator command identity conflicts with an existing command.');
+                error.code = 'SYNC_COORDINATOR_COMMAND_CONFLICT';
+                throw error;
+            }
+            if (existing?.status === 'succeeded') {
+                const state = services.host.readState();
+                if (state.activeWorkspaceId !== targetWorkspaceId
+                    || state.transitionState !== 'idle') {
+                    const error = new Error('The recorded workspace-switch result no longer matches the active workspace.');
+                    error.code = 'SYNC_COORDINATOR_STALE_GENERATION';
+                    throw error;
+                }
+                const credential = await services.credentialBroker.bindFromCookieHeader({
+                    cookieHeader: req.headers.cookie,
+                    workspaceId: targetWorkspaceId,
+                    coordinatorGeneration: state.coordinatorGeneration,
+                });
+                const resume = await resumeBoundCredential(credential, state);
+                writeJson(res, 200, {
+                    success: true,
+                    replayed: true,
+                    credential,
+                    command: existing,
+                    serverInstanceId: services.host.serverInstanceId,
+                    ...resume,
+                });
+                return;
+            }
+            const prepared = await services.credentialBroker.prepareWorkspaceSwitch({
+                cookieHeader: req.headers.cookie,
+                expectedSourceWorkspaceId: expectedActiveWorkspaceId,
+                sourceCoordinatorGeneration: expectedGeneration,
+                targetWorkspaceId,
+                targetCoordinatorGeneration: expectedGeneration + 1,
+            });
+            const state = await services.host.switchWorkspace({
+                commandId,
+                expectedActiveWorkspaceId,
+                targetWorkspaceId,
+                expectedCoordinatorGeneration: expectedGeneration,
+                requestedBy: prepared.principal,
+                activateTargetForCommit: () => {
+                    services.credentialBroker.commitPreparedWorkspaceSwitch(prepared);
+                },
+                rollbackTarget: (coordinatorGeneration) => {
+                    services.credentialBroker.rollbackPreparedWorkspaceSwitch(prepared, coordinatorGeneration);
+                },
+            });
+            const credential = services.credentialBroker.readSnapshot();
+            const resume = await resumeBoundCredential(credential, state);
+            writeJson(res, 200, {
+                success: true,
+                replayed: false,
+                credential,
+                command: services.host.readCommand(commandId),
+                serverInstanceId: services.host.serverInstanceId,
+                ...resume,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('GET', `${BASE_PATH}/status`, async (req, res) => {
+        const url = readUrl(req);
+        const workspaceId = String(url.searchParams.get('workspaceId') || '').trim();
+        const expectedGeneration = boundedGeneration(url.searchParams.get('coordinatorGeneration'));
+        try {
+            const state = services.host.readState();
+            assertAuthoritativeState(state, workspaceId, expectedGeneration);
+            authorizeAttachedBrowser(req, workspaceId, expectedGeneration);
+            recoverExpiredPermits(workspaceId);
+            const workspace = services.readWorkspaceStatus?.(workspaceId, expectedGeneration) || null;
+            writeJson(res, 200, {
+                success: true,
+                state,
+                credential: services.credentialBroker.readSnapshot(),
+                permits: services.permitStore.summarize(workspaceId),
+                workspace,
+                serverInstanceId: services.host.serverInstanceId,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/recovery/authoritative-repair-complete`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = boundedIdentifier(body.workspaceId, 'workspace ID');
+            const coordinatorGeneration = boundedGeneration(body.coordinatorGeneration);
+            const repairId = boundedIdentifier(body.repairId, 'repair ID');
+            const stateSignatureSha256 = boundedSha256(body.stateSignatureSha256, 'state signature SHA-256');
+            const state = services.host.readState();
+            assertAuthoritativeState(state, workspaceId, coordinatorGeneration);
+            requireAttachedBrowser(req, workspaceId, coordinatorGeneration);
+            if (state.ownershipMode !== 'browser-gateway' || state.transitionState !== 'idle') {
+                const error = new Error('Authoritative browser repair completion requires an idle browser-gateway owner.');
+                error.code = 'SYNC_COORDINATOR_PERMITS_DISABLED';
+                throw error;
+            }
+            const workspace = services.readWorkspaceStatus?.(workspaceId, coordinatorGeneration);
+            if (!workspace || workspace.outbox.activeDepth !== 0 || workspace.outbox.recovery) {
+                const error = new Error('Authoritative repair completion requires a fully drained durable outbox.');
+                error.code = 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT';
+                throw error;
+            }
+            const result = services.permitStore.resolveAuthoritativeRepairRecoveryObligations({
+                workspaceId,
+                coordinatorGeneration,
+                ownerMode: 'browser-gateway',
+                repairId,
+                stateSignatureSha256,
+            });
+            writeJson(res, 200, {
+                success: true,
+                workspaceId,
+                coordinatorGeneration,
+                result,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/credential`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = String(body.workspaceId || '').trim();
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            const credential = await services.credentialBroker.bindFromCookieHeader({
+                cookieHeader: req.headers.cookie,
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+            });
+            const state = services.host.readState();
+            assertAuthoritativeState(state, workspaceId, expectedGeneration);
+            const resume = await resumeBoundCredential(credential, state);
+            writeJson(res, 200, {
+                success: true,
+                credential,
+                ...resume,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('DELETE', `${BASE_PATH}/credential`, async (req, res) => {
+        try {
+            const url = readUrl(req);
+            const workspaceId = String(url.searchParams.get('workspaceId') || '').trim();
+            const expectedGeneration = boundedGeneration(url.searchParams.get('coordinatorGeneration'));
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            const credential = services.credentialBroker.clearFromCookieHeader({
+                cookieHeader: req.headers.cookie,
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+                reason: 'logout',
+            });
+            writeJson(res, 200, {
+                success: true,
+                credential,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/permits`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 32 * 1024);
+            const workspaceId = String(body.workspaceId || '').trim();
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            const operationClass = String(body.operationClass || '');
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            authorizeAttachedBrowser(req, workspaceId, expectedGeneration);
+            services.credentialBroker.requireCapability({ workspaceId, coordinatorGeneration: expectedGeneration });
+            recoverExpiredPermits(workspaceId);
+            if (!OPERATION_CLASSES.has(operationClass)) {
+                const error = new Error('The requested sync operation class is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const permitId = body.permitId
+                ? boundedIdentifier(body.permitId, 'permit ID')
+                : undefined;
+            const suppliedDeadlineAt = String(body.deadlineAt || '').trim();
+            if (permitId && !suppliedDeadlineAt) {
+                const error = new Error('The execution permit deadline is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const deadlineAt = suppliedDeadlineAt
+                || new Date(Date.now() + 60_000).toISOString();
+            const deadlineMs = Date.parse(deadlineAt) - Date.now();
+            if (!Number.isFinite(deadlineMs) || deadlineMs < 1_000 || deadlineMs > 300_000) {
+                const error = new Error('The execution permit deadline must be between 1 and 300 seconds from now.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const permit = services.permitStore.issue({
+                permitId,
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+                serverInstanceId: services.host.serverInstanceId,
+                operationClass,
+                operationIdentity: body.operationIdentity ? String(body.operationIdentity) : null,
+                lastCommittedCursor: body.lastCommittedCursor ?? null,
+                deadlineAt,
+            });
+            writeJson(res, 201, { success: true, permit });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/commands`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 64 * 1024);
+            const workspaceId = boundedIdentifier(body.workspaceId, 'workspace ID');
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            authorizeAttachedBrowser(req, workspaceId, expectedGeneration);
+            const capability = services.credentialBroker.requireCapability({
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+            });
+            const type = String(body.type || '');
+            if (!BROWSER_COMMAND_TYPES.has(type) || body.version !== 1) {
+                const error = new Error('The coordinator command is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const accepted = services.host.acceptCommand({
+                commandId: body.commandId
+                    ? boundedIdentifier(body.commandId, 'command ID')
+                    : undefined,
+                workspaceId,
+                expectedCoordinatorGeneration: expectedGeneration,
+                type: type,
+                version: 1,
+                args: body.args ?? null,
+                requestedBy: capability.validation.principal,
+            });
+            if (services.onCommandAccepted && accepted.record.status === 'accepted') {
+                const wakeTimer = setTimeout(() => {
+                    try {
+                        services.onCommandAccepted?.(accepted.record);
+                    }
+                    catch {
+                        // Command acceptance is durable; a wake failure must not alter its HTTP result.
+                    }
+                }, COMMAND_WAKE_COALESCE_MS);
+                wakeTimer.unref?.();
+            }
+            writeJson(res, accepted.replayed ? 200 : 202, {
+                success: true,
+                replayed: accepted.replayed,
+                command: accepted.record,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/wake`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = boundedIdentifier(body.workspaceId, 'workspace ID');
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            const source = String(body.source || '');
+            const eventIds = boundedWakeEventIds(body.eventIds);
+            const state = services.host.readState();
+            assertAuthoritativeState(state, workspaceId, expectedGeneration);
+            requireAttachedBrowser(req, workspaceId, expectedGeneration);
+            services.credentialBroker.requireCapability({
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+            });
+            const authorizedState = services.host.readState();
+            assertAuthoritativeState(authorizedState, workspaceId, expectedGeneration);
+            if (authorizedState.ownershipMode !== 'server'
+                || authorizedState.transitionState !== 'idle'
+                || !BROWSER_WAKE_SOURCES.has(source)) {
+                const error = new Error('The coordinator wake hint is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const accepted = services.requestWakeHint?.({
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+                source: source,
+                eventIds,
+            }) === true;
+            if (!accepted) {
+                const error = new Error('The local sync coordinator wake surface is unavailable.');
+                error.code = 'SYNC_COORDINATOR_UNAVAILABLE';
+                throw error;
+            }
+            writeJson(res, 202, { success: true, accepted: true });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/ownership-transfer`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const commandId = boundedIdentifier(body.commandId, 'command ID');
+            const workspaceId = boundedIdentifier(body.workspaceId, 'workspace ID');
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            const targetMode = String(body.targetMode || '');
+            if (body.version !== 1
+                || expectedGeneration < 0
+                || !['server', 'browser-gateway'].includes(targetMode)) {
+                const error = new Error('The ownership-transfer command is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            // A completed transfer necessarily advances the coordinator
+            // generation. Look up its durable identity before applying any
+            // source-generation fence so response-loss retries remain valid.
+            const existing = services.host.readCommand(commandId);
+            const currentState = services.host.readState();
+            if (!currentState.activeWorkspaceId
+                || currentState.activeWorkspaceId !== workspaceId) {
+                const error = new Error(`Workspace ${workspaceId} is not the active local sync workspace.`);
+                error.code = 'SYNC_COORDINATOR_INACTIVE_WORKSPACE';
+                throw error;
+            }
+            authorizeAttachedBrowser(req, workspaceId, currentState.coordinatorGeneration);
+            const capability = services.credentialBroker.requireCapability({
+                workspaceId,
+                coordinatorGeneration: currentState.coordinatorGeneration,
+            });
+            if (!existing
+                && targetMode === 'server'
+                && !services.serverOwnershipTransferEnabled) {
+                const error = new Error('Server-owned local synchronization is not enabled.');
+                error.code = 'SYNC_COORDINATOR_SERVER_OWNERSHIP_DISABLED';
+                throw error;
+            }
+            const transfer = await services.host.transferOwnershipWithReplay({
+                commandId,
+                workspaceId,
+                expectedCoordinatorGeneration: expectedGeneration,
+                targetMode: targetMode,
+                requestedBy: capability.validation.principal,
+            });
+            const command = services.host.readCommand(commandId);
+            if (!command) {
+                throw new Error(`Ownership-transfer command ${commandId} is missing after completion.`);
+            }
+            writeJson(res, 200, {
+                success: true,
+                replayed: transfer.replayed,
+                command,
+                state: transfer.state,
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('GET', `${BASE_PATH}/commands/:commandId`, async (req, res, params) => {
+        try {
+            const url = readUrl(req);
+            const workspaceId = boundedIdentifier(url.searchParams.get('workspaceId'), 'workspace ID');
+            const expectedGeneration = boundedGeneration(url.searchParams.get('coordinatorGeneration'));
+            const commandId = boundedIdentifier(params?.commandId, 'command ID');
+            const rootCommandId = boundedIdentifier(url.searchParams.get('rootCommandId') || commandId, 'root command ID');
+            const command = services.host.readCommand(commandId);
+            const rootCommand = services.host.readCommand(rootCommandId);
+            const state = services.host.readState();
+            if (!command
+                || !rootCommand
+                || command.workspaceId !== workspaceId
+                || rootCommand.workspaceId !== workspaceId
+                || command.expectedCoordinatorGeneration !== expectedGeneration
+                || rootCommand.expectedCoordinatorGeneration !== expectedGeneration
+                || state.activeWorkspaceId !== workspaceId
+                || !commandIsReachableFromRoot(rootCommandId, commandId, workspaceId, expectedGeneration, services.host.readCommand.bind(services.host))) {
+                const error = new Error('Coordinator command was not found.');
+                error.code = 'SYNC_COORDINATOR_COMMAND_NOT_FOUND';
+                throw error;
+            }
+            requireAttachedBrowser(req, workspaceId, state.coordinatorGeneration);
+            const currentPrincipal = services.credentialBroker.requireCapability({
+                workspaceId,
+                coordinatorGeneration: state.coordinatorGeneration,
+            }).validation.principal;
+            if (currentPrincipal.userId !== rootCommand.requestedBy.userId
+                || currentPrincipal.tenantId !== rootCommand.requestedBy.tenantId) {
+                const error = new Error('Coordinator command was not found.');
+                error.code = 'SYNC_COORDINATOR_COMMAND_NOT_FOUND';
+                throw error;
+            }
+            writeJson(res, 200, { success: true, command });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('GET', `${BASE_PATH}/permits/:permitId`, async (req, res, params) => {
+        try {
+            const permit = services.permitStore.read(String(params?.permitId || ''));
+            if (!permit) {
+                const error = new Error('Execution permit was not found.');
+                error.code = 'SYNC_COORDINATOR_PERMIT_NOT_FOUND';
+                throw error;
+            }
+            const url = readUrl(req);
+            const workspaceId = String(url.searchParams.get('workspaceId') || '').trim();
+            const expectedGeneration = boundedGeneration(url.searchParams.get('coordinatorGeneration'));
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            authorizeAttachedBrowser(req, workspaceId, expectedGeneration);
+            if (permit.workspaceId !== workspaceId
+                || permit.coordinatorGeneration !== expectedGeneration) {
+                const error = new Error('Execution permit does not belong to this coordinator scope.');
+                error.code = 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT';
+                throw error;
+            }
+            writeJson(res, 200, { success: true, permit });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/gateway`, async (req, res) => {
+        try {
+            const body = await parseJsonBody(req, 64 * 1024 * 1024);
+            const workspaceId = String(body.workspaceId || '').trim();
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            const operation = body.operation;
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            authorizeAttachedBrowser(req, workspaceId, expectedGeneration);
+            if (!operation || typeof operation !== 'object' || operation.workspaceId !== workspaceId) {
+                const error = new Error('The fixed sync gateway operation is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const result = await services.transportGateway.execute({
+                permitId: String(body.permitId || ''),
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+                serverInstanceId: services.host.serverInstanceId,
+                operationIdentity: body.operationIdentity ? String(body.operationIdentity) : null,
+                operation,
+            });
+            res.writeHead(result.status, {
+                ...result.headers,
+                'Cache-Control': 'no-store',
+            });
+            res.end(result.body);
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/permits/:permitId/release`, async (req, res, params) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = String(body.workspaceId || '').trim();
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            requireAttachedBrowser(req, workspaceId, expectedGeneration);
+            const permitId = String(params?.permitId || '');
+            const currentPermit = services.permitStore.read(permitId);
+            const permit = currentPermit?.operationClass === 'push'
+                ? services.permitStore.completeAcceptedPushWithoutEcho({
+                    permitIds: [permitId],
+                    workspaceId,
+                    coordinatorGeneration: expectedGeneration,
+                    ownerMode: 'browser-gateway',
+                    serverInstanceId: services.host.serverInstanceId,
+                    pushBoundary: parseWorkspaceSyncEngineV2PushBoundary(body.pushBoundary),
+                })
+                : services.permitStore.release({
+                    permitId,
+                    workspaceId,
+                    coordinatorGeneration: expectedGeneration,
+                    serverInstanceId: services.host.serverInstanceId,
+                });
+            writeJson(res, 200, { success: true, permit });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('POST', `${BASE_PATH}/permits/:permitId/abandon`, async (req, res, params) => {
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = String(body.workspaceId || '').trim();
+            const expectedGeneration = boundedGeneration(body.coordinatorGeneration);
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            requireAttachedBrowser(req, workspaceId, expectedGeneration);
+            const permitId = String(params?.permitId || '');
+            const requestedErrorCode = String(body.errorCode || '').trim();
+            const errorCode = /^[A-Z][A-Z0-9_]{0,127}$/.test(requestedErrorCode)
+                ? requestedErrorCode
+                : 'SYNC_COORDINATOR_BROWSER_ABANDONED';
+            const permit = services.permitStore.abandonPermit({
+                permitId,
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+                serverInstanceId: services.host.serverInstanceId,
+                errorCode,
+            });
+            writeJson(res, 200, { success: true, permit });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    input.addRoute('GET', `${BASE_PATH}/events`, async (req, res) => {
+        const url = readUrl(req);
+        const workspaceId = String(url.searchParams.get('workspaceId') || '').trim();
+        const expectedGeneration = boundedGeneration(url.searchParams.get('coordinatorGeneration'));
+        try {
+            assertAuthoritativeState(services.host.readState(), workspaceId, expectedGeneration);
+            authorizeAttachedBrowser(req, workspaceId, expectedGeneration);
+            const rawLimit = Number(url.searchParams.get('limit') || 50);
+            if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > 100) {
+                const error = new Error('The event limit is invalid.');
+                error.code = 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID';
+                throw error;
+            }
+            const limit = rawLimit;
+            writeJson(res, 200, {
+                success: true,
+                workspaceId,
+                coordinatorGeneration: expectedGeneration,
+                events: input.core.listSyncEvents(workspaceId, limit).map((event) => ({
+                    eventType: event.eventType,
+                    status: event.status,
+                    statusCode: event.statusCode,
+                    changeCount: event.changeCount,
+                    requestMs: event.requestMs,
+                    timestamp: event.occurredAt,
+                    hasError: Boolean(event.errorMessage),
+                })),
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+}
+function commandIsReachableFromRoot(rootCommandId, targetCommandId, workspaceId, coordinatorGeneration, readCommand) {
+    let commandId = rootCommandId;
+    const visited = new Set();
+    for (let hop = 0; hop < 8; hop += 1) {
+        if (commandId === targetCommandId)
+            return true;
+        if (visited.has(commandId))
+            return false;
+        visited.add(commandId);
+        const command = readCommand(commandId);
+        if (!command
+            || command.workspaceId !== workspaceId
+            || command.expectedCoordinatorGeneration !== coordinatorGeneration
+            || command.status !== 'superseded')
+            return false;
+        const result = command.result;
+        if (!result || typeof result !== 'object')
+            return false;
+        const candidate = result;
+        const next = candidate.leaderCommandId || candidate.supersedingCommandId;
+        if (typeof next !== 'string' || !next.trim())
+            return false;
+        commandId = next.trim();
+    }
+    return false;
+}