@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/coordinator/workspaceSyncTransportGateway.js

@@ -0,0 +1,738 @@
+import { WORKSPACE_SYNC_V3_ORIGIN_ASSERTION_HEADER } from '../v3/workspaceSyncV3OriginAssertionHeader.js';
+import { readSetCookieHeaders, rewriteSetCookieForLocalHost, } from '../../utils/httpSetCookie.js';
+export class WorkspaceSyncTransportGatewayError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceSyncTransportGatewayError';
+    }
+}
+export class WorkspaceSyncTransportGateway {
+    options;
+    inFlight = new Map();
+    idleWaiters = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async execute(input) {
+        return this.executeForOwner('browser-gateway', input);
+    }
+    async executeServer(input) {
+        return this.executeForOwner('server', input);
+    }
+    async executeForOwner(ownerMode, input) {
+        if (input.operation.workspaceId !== input.workspaceId) {
+            throw new WorkspaceSyncTransportGatewayError('The gateway operation workspace does not match the execution permit.', 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID');
+        }
+        if (this.inFlight.has(input.permitId)) {
+            throw new WorkspaceSyncTransportGatewayError(`Execution permit ${input.permitId} already has a gateway request in flight.`, 'SYNC_COORDINATOR_GATEWAY_ALREADY_IN_FLIGHT');
+        }
+        const operationClass = workspaceSyncGatewayOperationClassFor(input.operation);
+        const permit = this.options.permitStore.read(input.permitId);
+        if (!permit
+            || permit.ownerMode !== ownerMode
+            || permit.operationClass !== operationClass) {
+            throw new WorkspaceSyncTransportGatewayError('The gateway operation does not match the execution permit owner or class.', 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID');
+        }
+        const capability = this.options.credentialBroker.requireCapability({
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+        });
+        const operation = input.operation.type === 'v3-dispatch' && this.options.decodeV3Envelope
+            ? {
+                ...input.operation,
+                envelope: decodeV3Envelope(this.options.decodeV3Envelope, input.operation.envelope),
+            }
+            : input.operation;
+        const request = buildGatewayRequest(this.options.cloudBaseUrl, operation);
+        const operationIdentity = operationIdentityFor(operation, capability.validation.principal.tenantId);
+        if (operationIdentity && input.operationIdentity !== operationIdentity) {
+            throw new WorkspaceSyncTransportGatewayError('The gateway operation identity does not match its canonical wire identity.', 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID');
+        }
+        this.options.permitStore.transition({
+            permitId: input.permitId,
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+            serverInstanceId: input.serverInstanceId,
+            expectedState: 'issued-idle',
+            nextState: 'gateway-in-flight',
+            operationIdentity: input.operationIdentity || null,
+        });
+        const controller = new AbortController();
+        this.inFlight.set(input.permitId, controller);
+        const timeoutMs = Math.max(1, Math.min(workspaceSyncGatewayTimeoutMs(input.operation), Date.parse(permit.deadlineAt) - Date.now(), 2_147_483_647));
+        let rejectDeadline = null;
+        const deadline = new Promise((_resolve, reject) => {
+            rejectDeadline = reject;
+        });
+        const deadlineTimer = setTimeout(() => {
+            controller.abort();
+            rejectDeadline?.(new WorkspaceSyncTransportGatewayError('The sync gateway request exceeded its execution deadline.', 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED'));
+        }, timeoutMs);
+        deadlineTimer.unref?.();
+        const headers = new Headers(request.headers);
+        headers.set('Cookie', capability.cookieHeader);
+        if (operation.type === 'v3-dispatch') {
+            const assertion = this.options.createV3OriginAssertion?.(operation.envelope, this.options.now?.() || new Date());
+            if (assertion)
+                headers.set(WORKSPACE_SYNC_V3_ORIGIN_ASSERTION_HEADER, assertion);
+        }
+        if (this.options.cloudflareAccess?.clientId && this.options.cloudflareAccess.clientSecret) {
+            headers.set('CF-Access-Client-Id', this.options.cloudflareAccess.clientId);
+            headers.set('CF-Access-Client-Secret', this.options.cloudflareAccess.clientSecret);
+        }
+        let disposition = 'unknown';
+        let gatewayFinished = false;
+        try {
+            const requestResult = (async () => {
+                const response = await (this.options.fetchImpl || fetch)(request.url, {
+                    method: request.method,
+                    headers,
+                    body: request.body,
+                    redirect: 'manual',
+                    signal: controller.signal,
+                });
+                const body = await readBoundedBody(response, Math.min(this.options.maxResponseBytes ?? 50 * 1024 * 1024, operation.type === 'v3-dispatch' ? 1024 * 1024 : Number.MAX_SAFE_INTEGER));
+                return { response, body };
+            })();
+            const { response, body } = await Promise.race([requestResult, deadline]);
+            this.options.credentialBroker.handleUpstreamStatus(response.status);
+            disposition = upstreamDispositionFor(response, operation);
+            let rotatedSetCookie = null;
+            if (operation.type === 'provision' && response.ok) {
+                const rotation = await this.options.credentialBroker.rotateFromSetCookieHeaders({
+                    setCookieHeaders: readSetCookieHeaders(response.headers),
+                    workspaceId: input.workspaceId,
+                    coordinatorGeneration: input.coordinatorGeneration,
+                });
+                rotatedSetCookie = rewriteSetCookieForLocalHost(rotation.setCookieHeader);
+            }
+            this.finishGateway(input, disposition);
+            gatewayFinished = true;
+            const responseHeaders = {};
+            for (const name of ['content-type', 'etag', 'retry-after', 'x-request-id']) {
+                const value = response.headers.get(name);
+                if (value)
+                    responseHeaders[name] = value;
+            }
+            if (rotatedSetCookie)
+                responseHeaders['set-cookie'] = rotatedSetCookie;
+            return { status: response.status, headers: responseHeaders, body };
+        }
+        catch (error) {
+            if (!gatewayFinished) {
+                this.finishGateway(input, disposition);
+            }
+            if (error instanceof WorkspaceSyncTransportGatewayError)
+                throw error;
+            throw new WorkspaceSyncTransportGatewayError(String(error?.message || 'The sync gateway request failed.'), 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED');
+        }
+        finally {
+            clearTimeout(deadlineTimer);
+            this.inFlight.delete(input.permitId);
+            if (this.inFlight.size === 0) {
+                for (const resolve of this.idleWaiters)
+                    resolve();
+                this.idleWaiters.clear();
+            }
+        }
+    }
+    abort(permitId) {
+        const controller = this.inFlight.get(permitId);
+        if (!controller)
+            return false;
+        controller.abort();
+        return true;
+    }
+    get inFlightCount() {
+        return this.inFlight.size;
+    }
+    get inFlightPermitIds() {
+        return new Set(this.inFlight.keys());
+    }
+    async drain(graceMs) {
+        if (this.inFlight.size === 0)
+            return;
+        const drained = await this.waitForIdle(graceMs);
+        if (drained)
+            return;
+        for (const controller of this.inFlight.values())
+            controller.abort();
+        const aborted = await this.waitForIdle(Math.min(1_000, Math.max(1, graceMs)));
+        if (!aborted) {
+            throw new WorkspaceSyncTransportGatewayError('The sync gateway could not drain every active request.', 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED');
+        }
+    }
+    finishGateway(input, disposition) {
+        this.options.permitStore.transition({
+            permitId: input.permitId,
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+            serverInstanceId: input.serverInstanceId,
+            expectedState: 'gateway-in-flight',
+            nextState: 'gateway-complete-awaiting-apply',
+            upstreamDisposition: disposition,
+        });
+    }
+    waitForIdle(timeoutMs) {
+        if (this.inFlight.size === 0)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            let settled = false;
+            const onIdle = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.idleWaiters.delete(onIdle);
+                resolve(true);
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.idleWaiters.delete(onIdle);
+                resolve(false);
+            }, Math.max(1, timeoutMs));
+            timer.unref?.();
+            this.idleWaiters.add(onIdle);
+        });
+    }
+}
+function upstreamDispositionFor(response, operation) {
+    if (response.ok)
+        return 'accepted';
+    if (response.status >= 500)
+        return 'unknown';
+    if (response.status === 409 && isApplyingV3Operation(operation))
+        return 'accepted';
+    return 'rejected';
+}
+function isApplyingV3Operation(operation) {
+    return operation.type === 'v3-feed'
+        || operation.type === 'v3-feed-repair';
+}
+function decodeV3Envelope(decoder, envelope) {
+    try {
+        return decoder(envelope);
+    }
+    catch {
+        throw invalidOperation('The v3 operation envelope failed its canonical codec.');
+    }
+}
+export function workspaceSyncGatewayOperationClassFor(operation) {
+    if (operation.type === 'handshake')
+        return 'handshake';
+    if (operation.type === 'provision' || operation.type === 'bootstrap-push')
+        return 'bootstrap';
+    if (operation.type === 'push')
+        return 'push';
+    if (operation.type === 'v3-dispatch')
+        return 'v3-dispatch';
+    if (operation.type === 'initiative-repair'
+        || operation.type === 'combined-repair'
+        || operation.type === 'v3-feed-repair'
+        || (operation.type === 'pull' && operation.repairMode === true)
+        || (operation.type === 'v3-feed'
+            && (operation.forceRepair === true || Boolean(operation.repairCursor)))) {
+        return 'repair';
+    }
+    if (operation.type === 'pull'
+        || operation.type === 'v3-feed'
+        || operation.type === 'task-comment-audit'
+        || operation.type === 'content-pull') {
+        return 'pull';
+    }
+    throw invalidOperation('The requested sync gateway operation is not supported.');
+}
+function buildGatewayRequest(cloudBaseUrl, operation) {
+    const baseUrl = String(cloudBaseUrl || '').trim().replace(/\/+$/, '');
+    if (!/^https?:\/\//i.test(baseUrl)) {
+        throw new WorkspaceSyncTransportGatewayError('The sync gateway cloud base URL is invalid.', 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID');
+    }
+    assertOperationKeys(operation);
+    assertWorkspaceId(operation.workspaceId);
+    if (operation.type === 'handshake') {
+        return jsonPost(baseUrl, '/api/taskforce/sync/workspace/handshake', {
+            workspaceId: operation.workspaceId,
+        });
+    }
+    if (operation.type === 'provision') {
+        const name = boundedString(operation.name, 'workspace name', 200);
+        return jsonPost(baseUrl, '/api/taskforce/sync/workspace/provision', {
+            workspaceId: operation.workspaceId,
+            name,
+        });
+    }
+    if (operation.type === 'push') {
+        const idempotencyKey = boundedString(operation.idempotencyKey, 'idempotency key', 256);
+        if (!Array.isArray(operation.changes)) {
+            throw invalidOperation('Workspace push changes must be an array.');
+        }
+        validateWorkspaceSyncChanges(operation.changes);
+        return jsonPost(baseUrl, '/api/taskforce/sync/workspace/push', {
+            workspaceId: operation.workspaceId,
+            idempotencyKey,
+            changes: operation.changes,
+            ...(operation.repairMode === true ? { repair: true } : {}),
+            ...optionalStringArrayFields(operation, [
+                'activeV3TaskMetadataIds',
+                'activeV3TaskLifecycleIds',
+                'activeV3TaskReopenAssigneeIds',
+                'activeV3InitiativeIds',
+                'excludedProjections',
+            ]),
+            ...(operation.v3InitiativeProjectionOwned === true
+                ? { v3InitiativeProjectionOwned: true }
+                : {}),
+            ...(operation.combinedCoverage
+                ? { combinedCoverage: validateCoverage(operation.combinedCoverage) }
+                : {}),
+        });
+    }
+    if (operation.type === 'bootstrap-push') {
+        validateBootstrapSnapshot(operation.snapshot);
+        if ('workspaceId' in operation.snapshot
+            && operation.snapshot.workspaceId !== operation.workspaceId) {
+            throw invalidOperation('The bootstrap snapshot workspace does not match the operation.');
+        }
+        return jsonPost(baseUrl, '/api/taskforce/sync/workspace/bootstrap-push', {
+            ...operation.snapshot,
+            workspaceId: operation.workspaceId,
+        });
+    }
+    if (operation.type === 'v3-dispatch') {
+        validateV3Envelope(operation.envelope, operation.workspaceId);
+        return jsonPost(baseUrl, '/api/taskforce/sync/v3/workspace/operations', operation.envelope, { Accept: 'application/json' });
+    }
+    if (operation.type === 'content-pull') {
+        if (!Array.isArray(operation.requests)
+            || operation.requests.length < 1
+            || operation.requests.length > 100) {
+            throw invalidOperation('Content pull requests must contain between 1 and 100 entries.');
+        }
+        return jsonPost(baseUrl, '/api/taskforce/sync/workspace/content', {
+            workspaceId: operation.workspaceId,
+            requests: operation.requests.map((request) => {
+                if (request
+                    && request.kind === 'asset'
+                    && 'assetId' in request
+                    && !('path' in request)) {
+                    if (operation.requests.length !== 1) {
+                        throw invalidOperation('An asset ID content request must be the only request.');
+                    }
+                    return {
+                        kind: 'asset',
+                        assetId: boundedString(request.assetId, 'asset ID', 256),
+                    };
+                }
+                if (!request
+                    || (request.kind !== 'document' && request.kind !== 'asset')
+                    || !('path' in request)) {
+                    throw invalidOperation('Content pull entries require a supported kind and path.');
+                }
+                return {
+                    kind: request.kind,
+                    path: boundedString(request.path, 'content path', 2_048),
+                };
+            }),
+        });
+    }
+    const params = new URLSearchParams({ workspaceId: operation.workspaceId });
+    if (operation.type === 'pull') {
+        assertLimit(operation.limit, 1_000);
+        params.set('limit', String(operation.limit));
+        if (operation.cursor)
+            params.set('cursor', operation.cursor);
+        if (operation.repairMode)
+            params.set('repair', '1');
+        if (operation.contentMode === 'manifest')
+            params.set('content', 'manifest');
+        if (operation.excludeInitiatives)
+            params.set('excludeInitiatives', '1');
+        if (operation.excludedProjections?.length) {
+            params.set('excludeProjections', operation.excludedProjections.join(','));
+        }
+        appendCoverage(params, operation.coverage);
+        return get(baseUrl, '/api/taskforce/sync/workspace/pull', params);
+    }
+    if (operation.type === 'v3-feed' || operation.type === 'v3-feed-repair') {
+        assertLimit(operation.limit, 500);
+        params.set('limit', String(operation.limit));
+        if (operation.cursor)
+            params.set('cursor', operation.cursor);
+        if (operation.repairCursor)
+            params.set('repairCursor', operation.repairCursor);
+        if (operation.forceRepair)
+            params.set('forceRepair', '1');
+        appendCoverage(params, operation.coverage);
+        return get(baseUrl, '/api/taskforce/sync/v3/workspace/feed', params);
+    }
+    assertLimit(operation.limit, 500);
+    params.set('limit', String(operation.limit));
+    if (operation.cursor)
+        params.set('cursor', operation.cursor);
+    if (operation.type === 'initiative-repair') {
+        return get(baseUrl, '/api/taskforce/sync/workspace/initiative-repair', params);
+    }
+    if (operation.type === 'combined-repair') {
+        appendCoverage(params, operation.coverage);
+        return get(baseUrl, '/api/taskforce/sync/workspace/combined-repair', params);
+    }
+    if (operation.type === 'task-comment-audit') {
+        return get(baseUrl, '/api/taskforce/sync/v3/workspace/task-comment-audit', params);
+    }
+    throw invalidOperation('The requested sync gateway operation is not supported.');
+}
+function appendCoverage(params, coverage) {
+    if (!coverage)
+        return;
+    const valid = validateCoverage(coverage);
+    params.set('coverageProfileId', valid.coverageProfileId);
+    params.set('coverageVersion', String(valid.coverageVersion));
+    params.set('coverageDigest', valid.coverageDigest);
+}
+function jsonPost(baseUrl, path, body, extraHeaders) {
+    return {
+        url: `${baseUrl}${path}`,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...extraHeaders },
+        body: JSON.stringify(body),
+    };
+}
+function get(baseUrl, path, params) {
+    return { url: `${baseUrl}${path}?${params.toString()}`, method: 'GET' };
+}
+function assertWorkspaceId(workspaceId) {
+    if (!workspaceId || workspaceId.length > 200 || /\s/.test(workspaceId)) {
+        throw invalidOperation('The sync gateway workspace ID is invalid.');
+    }
+}
+function assertLimit(limit, max) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > max) {
+        throw invalidOperation(`The sync gateway limit must be between 1 and ${max}.`);
+    }
+}
+function invalidOperation(message) {
+    return new WorkspaceSyncTransportGatewayError(message, 'SYNC_COORDINATOR_GATEWAY_OPERATION_INVALID');
+}
+function operationIdentityFor(operation, tenantId) {
+    if (operation.type === 'push')
+        return operation.idempotencyKey;
+    if (operation.type !== 'v3-dispatch')
+        return null;
+    const envelope = operation.envelope;
+    return [
+        tenantId,
+        envelope.workspaceId,
+        envelope.clientId,
+        envelope.operationId,
+    ].join('/');
+}
+const OPERATION_KEYS = {
+    handshake: new Set(['type', 'workspaceId']),
+    provision: new Set(['type', 'workspaceId', 'name']),
+    push: new Set([
+        'type',
+        'workspaceId',
+        'idempotencyKey',
+        'changes',
+        'repairMode',
+        'activeV3TaskMetadataIds',
+        'activeV3TaskLifecycleIds',
+        'activeV3TaskReopenAssigneeIds',
+        'activeV3InitiativeIds',
+        'v3InitiativeProjectionOwned',
+        'combinedCoverage',
+        'excludedProjections',
+    ]),
+    'bootstrap-push': new Set(['type', 'workspaceId', 'snapshot']),
+    'v3-dispatch': new Set(['type', 'workspaceId', 'envelope']),
+    pull: new Set([
+        'type',
+        'workspaceId',
+        'cursor',
+        'limit',
+        'repairMode',
+        'contentMode',
+        'excludeInitiatives',
+        'excludedProjections',
+        'coverage',
+    ]),
+    'v3-feed': new Set([
+        'type',
+        'workspaceId',
+        'cursor',
+        'repairCursor',
+        'limit',
+        'forceRepair',
+        'coverage',
+    ]),
+    'v3-feed-repair': new Set([
+        'type',
+        'workspaceId',
+        'cursor',
+        'repairCursor',
+        'limit',
+        'forceRepair',
+        'coverage',
+    ]),
+    'initiative-repair': new Set(['type', 'workspaceId', 'cursor', 'limit']),
+    'combined-repair': new Set(['type', 'workspaceId', 'cursor', 'limit', 'coverage']),
+    'task-comment-audit': new Set(['type', 'workspaceId', 'cursor', 'limit']),
+    'content-pull': new Set(['type', 'workspaceId', 'requests']),
+};
+function assertOperationKeys(operation) {
+    if (!isPlainObject(operation) || !Object.hasOwn(OPERATION_KEYS, operation.type)) {
+        throw invalidOperation('The requested sync gateway operation is not supported.');
+    }
+    const allowed = OPERATION_KEYS[operation.type];
+    for (const key of Object.keys(operation)) {
+        if (!allowed.has(key)) {
+            throw invalidOperation(`The sync gateway operation field ${key} is not supported.`);
+        }
+    }
+}
+export function workspaceSyncGatewayTimeoutMs(operation) {
+    if (operation.type === 'v3-dispatch')
+        return 90_000;
+    if (operation.type === 'initiative-repair'
+        || operation.type === 'combined-repair'
+        || operation.type === 'v3-feed-repair'
+        || (operation.type === 'push' && operation.repairMode === true)
+        || (operation.type === 'pull' && operation.repairMode === true)
+        || (operation.type === 'v3-feed'
+            && (operation.forceRepair === true || Boolean(operation.repairCursor))))
+        return 180_000;
+    if (operation.type === 'push'
+        || operation.type === 'bootstrap-push')
+        return 90_000;
+    if (operation.type === 'pull'
+        || operation.type === 'v3-feed'
+        || operation.type === 'content-pull')
+        return 90_000;
+    if (operation.type === 'task-comment-audit')
+        return 45_000;
+    return 20_000;
+}
+async function readBoundedBody(response, maxBytes) {
+    const declaredLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        throw responseTooLarge(maxBytes);
+    }
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel();
+                throw responseTooLarge(maxBytes);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+function responseTooLarge(maxBytes) {
+    return new WorkspaceSyncTransportGatewayError(`The sync gateway response exceeded ${maxBytes} bytes.`, 'SYNC_COORDINATOR_GATEWAY_RESPONSE_TOO_LARGE');
+}
+function boundedString(value, label, maxLength) {
+    const normalized = String(value || '').trim();
+    if (!normalized || normalized.length > maxLength || /[\u0000-\u001f\u007f]/.test(normalized)) {
+        throw invalidOperation(`The ${label} is invalid.`);
+    }
+    return normalized;
+}
+function isPlainObject(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function validateCoverage(coverage) {
+    if (!coverage
+        || !Number.isInteger(coverage.coverageVersion)
+        || coverage.coverageVersion < 1
+        || !/^[a-f0-9]{64}$/.test(String(coverage.coverageDigest || ''))) {
+        throw invalidOperation('The sync gateway coverage selector is invalid.');
+    }
+    return {
+        coverageProfileId: boundedString(coverage.coverageProfileId, 'coverage profile ID', 200),
+        coverageVersion: coverage.coverageVersion,
+        coverageDigest: coverage.coverageDigest,
+    };
+}
+function optionalStringArrayFields(operation, fields) {
+    const result = {};
+    for (const field of fields) {
+        const raw = operation[field];
+        if (raw === undefined)
+            continue;
+        if (!Array.isArray(raw) || raw.length > 10_000) {
+            throw invalidOperation(`The ${field} list is invalid.`);
+        }
+        result[field] = raw.map((value) => boundedString(value, field, 256));
+    }
+    return result;
+}
+function validateV3Envelope(envelope, workspaceId) {
+    if (!isPlainObject(envelope)
+        || envelope.contractVersion !== 3
+        || envelope.workspaceId !== workspaceId
+        || !isPlainObject(envelope.operation)) {
+        throw invalidOperation('The v3 operation envelope is invalid.');
+    }
+    assertExactKeys(envelope, ['contractVersion', 'workspaceId', 'clientId', 'operationId', 'operation'], 'v3 operation envelope');
+    boundedString(envelope.clientId, 'v3 client ID', 256);
+    boundedString(envelope.operationId, 'v3 operation ID', 256);
+    const nested = envelope.operation;
+    assertExactKeys(nested, ['domain', 'entityId', 'mutationKind', 'baseEntityRevision', 'baseLifecycleRevision', 'payload'], 'v3 operation');
+    boundedString(nested.entityId, 'v3 entity ID', 256);
+    for (const key of ['baseEntityRevision', 'baseLifecycleRevision']) {
+        if (typeof nested[key] !== 'string' || !/^(0|[1-9]\d*)$/.test(nested[key])) {
+            throw invalidOperation(`The v3 ${key} is invalid.`);
+        }
+    }
+    if (!isPlainObject(nested.payload)) {
+        throw invalidOperation('The v3 operation payload must be an object.');
+    }
+    const domain = String(nested.domain || '');
+    const mutationKind = String(nested.mutationKind || '');
+    if (!V3_DOMAIN_MUTATIONS[domain]?.has(mutationKind)) {
+        throw invalidOperation('The v3 operation domain or mutation kind is unsupported.');
+    }
+}
+const V3_DOMAIN_MUTATIONS = {
+    task: new Set([
+        'metadata-update', 'create', 'delete', 'restore', 'archive', 'unarchive',
+        'complete', 'reopen', 'set-status',
+    ]),
+    'workflow-execution': new Set(['transition', 'complete-step']),
+    'task-comments': new Set(['append', 'reconcile']),
+    'task-checklist': new Set(['replace']),
+    'task-attachment-links': new Set(['replace']),
+    'task-relationship': new Set(['link', 'unlink']),
+    'entity-event': new Set(['adopt-legacy-batch']),
+    taxonomy: new Set(['replace-state', 'replace-state-with-task-remaps']),
+    initiative: new Set(['create', 'metadata-update', 'append-comment', 'archive', 'unarchive']),
+    workstream: new Set(['create', 'metadata-update', 'append-comment', 'archive', 'unarchive']),
+};
+const CHANGE_FIELDS = {
+    upsert: { allowed: ['op', 'archived', 'task', 'durableRevision'], required: ['archived', 'task'], objectField: 'task' },
+    delete: { allowed: ['op', 'taskId', 'deletedAt', 'watermark', 'actor', 'actorType', 'source', 'details'], required: ['taskId'] },
+    'task-relationship-upsert': { allowed: ['op', 'relationship'], required: ['relationship'], objectField: 'relationship' },
+    'task-relationship-delete': { allowed: ['op', 'relationship'], required: ['relationship'], objectField: 'relationship' },
+    'initiative-upsert': { allowed: ['op', 'initiative'], required: ['initiative'], objectField: 'initiative' },
+    'workstream-upsert': { allowed: ['op', 'workstream'], required: ['workstream'], objectField: 'workstream' },
+    'taxonomy-upsert': { allowed: ['op', 'taxonomies', 'taxonomyState', 'updatedAt', 'durableRevision'], required: ['updatedAt'] },
+    'ai-profile-upsert': { allowed: ['op', 'profile'], required: ['profile'], objectField: 'profile' },
+    'document-upsert': { allowed: [
+            'op', 'path', 'updatedAt', 'content', 'assetId', 'documentId', 'referenceNumber',
+            'version', 'taskId', 'linkTargetType', 'linkTargetId', 'logicalName', 'caption',
+            'originalFilename', 'linkRole', 'links',
+        ], required: ['path', 'updatedAt', 'content'] },
+    'document-delete': { allowed: ['op', 'path', 'assetId', 'deletedAt'], required: ['path'] },
+    'document-manifest': { allowed: ['op', 'manifest', 'metadata'], required: ['manifest', 'metadata'], objectField: 'manifest' },
+    'asset-upsert': { allowed: [
+            'op', 'path', 'updatedAt', 'contentBase64', 'assetId', 'kind', 'mimeType',
+            'referenceNumber', 'taskId', 'linkTargetType', 'linkTargetId', 'logicalName',
+            'caption', 'originalFilename', 'linkRole', 'links',
+        ], required: ['path', 'updatedAt', 'contentBase64', 'kind', 'mimeType'] },
+    'asset-delete': { allowed: ['op', 'path', 'assetId', 'deletedAt'], required: ['path'] },
+    'asset-manifest': { allowed: ['op', 'manifest', 'metadata'], required: ['manifest', 'metadata'], objectField: 'manifest' },
+    'document-review-session-upsert': { allowed: ['op', 'session'], required: ['session'], objectField: 'session' },
+    'document-review-session-delete': { allowed: ['op', 'sessionId', 'deletedAt'], required: ['sessionId'] },
+    'document-review-comment-upsert': { allowed: ['op', 'comment'], required: ['comment'], objectField: 'comment' },
+    'document-review-comment-delete': { allowed: ['op', 'commentId', 'deletedAt', 'deletedByActorId'], required: ['commentId'] },
+    'annotated-attachment-session-upsert': { allowed: ['op', 'session'], required: ['session'], objectField: 'session' },
+    'annotated-attachment-session-delete': { allowed: ['op', 'sessionId', 'deletedAt'], required: ['sessionId'] },
+    'taskforce-agent-upsert': { allowed: ['op', 'agent'], required: ['agent'], objectField: 'agent' },
+    'agent-role-upsert': { allowed: ['op', 'role'], required: ['role'], objectField: 'role' },
+    'taskforce-agent-skill-upsert': { allowed: ['op', 'skill'], required: ['skill'], objectField: 'skill' },
+    'agent-conversation-upsert': { allowed: ['op', 'conversation'], required: ['conversation'], objectField: 'conversation' },
+    'entity-event-upsert': { allowed: ['op', 'event'], required: ['event'], objectField: 'event' },
+    'task-event-upsert': { allowed: ['op', 'event'], required: ['event'], objectField: 'event' },
+};
+function validateWorkspaceSyncChanges(changes) {
+    if (changes.length > 10_000) {
+        throw invalidOperation('Workspace push changes exceed the fixed gateway limit.');
+    }
+    for (const change of changes) {
+        if (!isPlainObject(change)) {
+            throw invalidOperation('Every workspace push change must be an object.');
+        }
+        const op = String(change.op || '');
+        const codec = CHANGE_FIELDS[op];
+        if (!codec)
+            throw invalidOperation(`Workspace push change ${op || '(missing)'} is unsupported.`);
+        assertAllowedKeys(change, codec.allowed, `workspace push change ${op}`);
+        for (const field of codec.required || []) {
+            if (!Object.hasOwn(change, field) || change[field] === undefined || change[field] === null) {
+                throw invalidOperation(`Workspace push change ${op} requires ${field}.`);
+            }
+        }
+        if (codec.objectField && !isPlainObject(change[codec.objectField])) {
+            throw invalidOperation(`Workspace push change ${op} requires ${codec.objectField}.`);
+        }
+        if (op === 'upsert' && typeof change.archived !== 'boolean') {
+            throw invalidOperation('Workspace task upsert requires an archived boolean.');
+        }
+        if (op === 'delete')
+            boundedString(change.taskId, 'deleted task ID', 256);
+    }
+}
+const BOOTSTRAP_FIELDS = new Set([
+    'workspaceId', 'tasks', 'archived', 'taxonomies', 'initiatives', 'workstreams',
+    'documents', 'assets', 'taskforceAgents', 'agentRoles', 'taskforceAgentSkills',
+    'agentConversations', 'activeV3TaskMetadataIds', 'activeV3TaskLifecycleIds',
+    'activeV3TaskReopenAssigneeIds', 'activeV3InitiativeIds',
+    'v3InitiativeProjectionOwned', 'combinedCoverage', 'excludedProjections',
+]);
+function validateBootstrapSnapshot(snapshot) {
+    if (!isPlainObject(snapshot)) {
+        throw invalidOperation('The bootstrap snapshot must be an object.');
+    }
+    assertAllowedKeys(snapshot, BOOTSTRAP_FIELDS, 'bootstrap snapshot');
+    if (!Array.isArray(snapshot.tasks) || !Array.isArray(snapshot.archived)) {
+        throw invalidOperation('The bootstrap snapshot requires task and archived arrays.');
+    }
+    for (const [key, value] of Object.entries(snapshot)) {
+        if (key !== 'workspaceId'
+            && key !== 'v3InitiativeProjectionOwned'
+            && key !== 'combinedCoverage'
+            && value !== undefined
+            && !Array.isArray(value)) {
+            throw invalidOperation(`The bootstrap snapshot field ${key} must be an array.`);
+        }
+    }
+}
+function assertExactKeys(value, expected, label) {
+    const actual = Object.keys(value).sort();
+    const sortedExpected = [...expected].sort();
+    if (actual.length !== sortedExpected.length
+        || actual.some((key, index) => key !== sortedExpected[index])) {
+        throw invalidOperation(`The ${label} contains missing or unknown fields.`);
+    }
+}
+function assertAllowedKeys(value, allowed, label) {
+    const allowedSet = allowed instanceof Set ? allowed : new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedSet.has(key)) {
+            throw invalidOperation(`The ${label} field ${key} is unsupported.`);
+        }
+    }
+}