@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/engine/workspaceSyncEngineBrowserGatewayRemoteServices.d.ts

@@ -0,0 +1,28 @@
+import type { LocalSyncCoordinatorBrowserClient } from '../coordinator/localSyncCoordinatorBrowserClient.js';
+import type { WorkspaceSyncEngineRemoteServices } from './workspaceSyncEngineRemoteServices.js';
+type BrowserGatewayClient = Pick<LocalSyncCoordinatorBrowserClient, 'issuePermit' | 'executeGateway' | 'readPermit' | 'releasePermit' | 'abandonPermit'>;
+export interface BrowserGatewayWorkspaceSyncEngineRemoteServicesOptions {
+    workspaceId: string;
+    coordinatorGeneration: number;
+    serverInstanceId: string;
+    client: BrowserGatewayClient;
+    /**
+     * Revalidates the immutable browser-owner selection before every new
+     * remote operation. Permit cleanup remains available after revocation so
+     * already-issued work can still settle safely.
+     */
+    isExecutionAuthorized?: () => boolean;
+    now: () => Date;
+    permitDeadlineMs?: number;
+    createPermitId?: () => string;
+}
+/**
+ * Browser-owned cloud transport for the browser-neutral sync engine.
+ *
+ * When the browser-authority gate selects this adapter, every cloud request
+ * receives a fresh coordinator permit. Accepted non-applying work is released
+ * before returning; accepted applying work remains bound to an opaque receipt
+ * until its exact local apply boundary commits.
+ */
+export declare function createBrowserGatewayWorkspaceSyncEngineRemoteServices(options: BrowserGatewayWorkspaceSyncEngineRemoteServicesOptions): WorkspaceSyncEngineRemoteServices;
+export {};

package/dist/sync/engine/workspaceSyncEngineBrowserGatewayRemoteServices.js

@@ -0,0 +1,543 @@
+import { workspaceSyncGatewayOperationClassFor, workspaceSyncGatewayTimeoutMs, } from '../coordinator/workspaceSyncTransportGateway.js';
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
+import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR, resolveWorkspaceSyncV3CombinedCoverageForExclusions, } from '../v3/workspaceSyncV3CombinedWireContract.js';
+import { WORKSPACE_SYNC_ENGINE_TRANSFER_COMPLETION_VERSION, } from './workspaceSyncEngineTransferCompletion.js';
+import { parseWorkspaceSyncEngineAppliedTaskUpserts, parseWorkspaceSyncEngineV2PushBoundary, workspaceSyncEngineExpectedTaskEchoIds, } from './workspaceSyncEnginePushCompletion.js';
+const PERMIT_DEADLINE_SLACK_MS = 5_000;
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isValidV2PullPage(value, workspaceId) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.success !== true
+        || value.workspaceId !== workspaceId
+        || !Array.isArray(value.changes)
+        || typeof value.hasMore !== 'boolean'
+        || !Object.hasOwn(value, 'nextCursor')
+        || !(value.nextCursor === null || typeof value.nextCursor === 'string')) {
+        return false;
+    }
+    if (value.workspaceMembers !== undefined
+        && !Array.isArray(value.workspaceMembers)) {
+        return false;
+    }
+    if (value.excludedProjections !== undefined
+        && (!Array.isArray(value.excludedProjections)
+            || value.excludedProjections.some((entry) => typeof entry !== 'string'))) {
+        return false;
+    }
+    return value.diagnostics === undefined || isPlainObject(value.diagnostics);
+}
+function v2Boundary(cursor) {
+    return { cursor: cursor ?? null };
+}
+function v3Boundary(input) {
+    return {
+        version: 1,
+        projection: input.projection,
+        cursor: input.cursor ?? null,
+        ...(input.coverage ? { coverage: { ...input.coverage } } : {}),
+    };
+}
+async function decodeGatewayResponse(response, nowMs) {
+    const rawText = await response.text();
+    let data = {};
+    let validJsonObject = false;
+    if (rawText) {
+        try {
+            data = JSON.parse(rawText);
+            validJsonObject = Boolean(data
+                && typeof data === 'object'
+                && !Array.isArray(data));
+        }
+        catch {
+            data = {
+                error: rawText.slice(0, 400),
+            };
+        }
+    }
+    const retryAfterRaw = response.headers.get('retry-after');
+    let retryAfterMs;
+    if (retryAfterRaw) {
+        const seconds = Number.parseInt(retryAfterRaw, 10);
+        if (Number.isFinite(seconds) && seconds > 0) {
+            retryAfterMs = seconds * 1_000;
+        }
+        else {
+            const retryAt = Date.parse(retryAfterRaw);
+            const delta = retryAt - nowMs;
+            if (Number.isFinite(retryAt) && delta > 0)
+                retryAfterMs = delta;
+        }
+    }
+    return {
+        result: {
+            ok: response.status >= 200 && response.status < 300,
+            status: response.status,
+            data,
+            ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+        },
+        validJsonObject,
+    };
+}
+/**
+ * Browser-owned cloud transport for the browser-neutral sync engine.
+ *
+ * When the browser-authority gate selects this adapter, every cloud request
+ * receives a fresh coordinator permit. Accepted non-applying work is released
+ * before returning; accepted applying work remains bound to an opaque receipt
+ * until its exact local apply boundary commits.
+ */
+export function createBrowserGatewayWorkspaceSyncEngineRemoteServices(options) {
+    const now = options.now;
+    const createPermitId = options.createPermitId || (() => crypto.randomUUID());
+    const receiptMetadata = new WeakMap();
+    const assertWorkspace = (workspaceId) => {
+        if (workspaceId !== options.workspaceId) {
+            throw new TypeError('The browser-gateway sync operation workspace does not match its coordinator.');
+        }
+    };
+    const abandon = async (permitId, errorCode = 'SYNC_COORDINATOR_BROWSER_ABANDONED', expected) => {
+        const result = await options.client.abandonPermit({
+            permitId,
+            workspaceId: options.workspaceId,
+            coordinatorGeneration: options.coordinatorGeneration,
+            errorCode,
+        });
+        const permit = result?.permit;
+        if (!permit
+            || permit.permitId !== permitId
+            || permit.workspaceId !== options.workspaceId
+            || permit.coordinatorGeneration !== options.coordinatorGeneration
+            || permit.serverInstanceId !== options.serverInstanceId
+            || permit.ownerMode !== 'browser-gateway'
+            || (expected
+                && (permit.operationClass !== expected.operationClass
+                    || permit.operationIdentity !== expected.operationIdentity))
+            || ![
+                'released',
+                'abandoned-clean',
+                'abandoned-reconcile-required',
+            ].includes(permit.state)
+            || (expected?.acceptedReceipt === true
+                && (permit.upstreamDisposition !== 'accepted'
+                    || ![
+                        'released',
+                        'abandoned-reconcile-required',
+                    ].includes(permit.state)))) {
+            throw new Error('The browser-gateway execution permit was not abandoned safely.');
+        }
+        return permit;
+    };
+    const abandonKnownPermitAndRethrow = async (permitId, error, expected) => {
+        try {
+            await abandon(permitId, undefined, expected);
+        }
+        catch {
+            // Preserve the triggering failure. A failed abandon remains
+            // recoverable through permit expiry and coordinator reconciliation.
+        }
+        throw error;
+    };
+    const execute = async (input) => {
+        if (options.isExecutionAuthorized?.() === false) {
+            throw new Error('The browser-gateway sync authority selection was revoked.');
+        }
+        assertWorkspace(input.operation.workspaceId);
+        const issuedAt = now();
+        const permitDeadlineMs = Math.max(1, Math.floor(options.permitDeadlineMs
+            ?? (workspaceSyncGatewayTimeoutMs(input.operation)
+                + PERMIT_DEADLINE_SLACK_MS)));
+        const operationClass = workspaceSyncGatewayOperationClassFor(input.operation);
+        const settlementIdentity = {
+            operationClass,
+            operationIdentity: input.operationIdentity || null,
+        };
+        const permitId = createPermitId();
+        let issued;
+        try {
+            issued = await options.client.issuePermit({
+                permitId,
+                workspaceId: options.workspaceId,
+                coordinatorGeneration: options.coordinatorGeneration,
+                operationClass,
+                operationIdentity: input.operationIdentity || null,
+                lastCommittedCursor: input.previousBoundary,
+                deadlineAt: new Date(issuedAt.getTime() + permitDeadlineMs).toISOString(),
+            });
+        }
+        catch (error) {
+            return abandonKnownPermitAndRethrow(permitId, error, settlementIdentity);
+        }
+        const issuedPermit = issued?.permit;
+        if (!issuedPermit
+            || issuedPermit.permitId !== permitId
+            || issuedPermit.workspaceId !== options.workspaceId
+            || issuedPermit.coordinatorGeneration !== options.coordinatorGeneration
+            || issuedPermit.serverInstanceId !== options.serverInstanceId
+            || issuedPermit.ownerMode !== 'browser-gateway'
+            || issuedPermit.operationClass !== operationClass
+            || issuedPermit.operationIdentity !== settlementIdentity.operationIdentity
+            || issuedPermit.state !== 'issued-idle') {
+            return abandonKnownPermitAndRethrow(permitId, new Error('The browser-gateway execution permit is invalid.'), settlementIdentity);
+        }
+        let response;
+        try {
+            response = await options.client.executeGateway({
+                permitId: issuedPermit.permitId,
+                workspaceId: options.workspaceId,
+                coordinatorGeneration: options.coordinatorGeneration,
+                operationIdentity: input.operationIdentity || null,
+                operation: input.operation,
+            });
+        }
+        catch (error) {
+            return abandonKnownPermitAndRethrow(permitId, error, settlementIdentity);
+        }
+        let decoded;
+        try {
+            decoded = await decodeGatewayResponse(response, issuedAt.getTime());
+        }
+        catch (error) {
+            return abandonKnownPermitAndRethrow(permitId, error, settlementIdentity);
+        }
+        const result = decoded.result;
+        let completed;
+        try {
+            completed = await options.client.readPermit({
+                permitId,
+                workspaceId: options.workspaceId,
+                coordinatorGeneration: options.coordinatorGeneration,
+            });
+        }
+        catch (error) {
+            return abandonKnownPermitAndRethrow(permitId, error, settlementIdentity);
+        }
+        const completedPermit = completed?.permit;
+        if (!completedPermit
+            || completedPermit.permitId !== permitId
+            || completedPermit.workspaceId !== options.workspaceId
+            || completedPermit.coordinatorGeneration !== options.coordinatorGeneration
+            || completedPermit.serverInstanceId !== options.serverInstanceId
+            || completedPermit.ownerMode !== 'browser-gateway'
+            || completedPermit.operationClass !== operationClass
+            || completedPermit.operationIdentity !== settlementIdentity.operationIdentity
+            || completedPermit.state !== 'gateway-complete-awaiting-apply'
+            || !['accepted', 'rejected', 'unknown'].includes(completedPermit.upstreamDisposition || '')) {
+            return abandonKnownPermitAndRethrow(permitId, new Error('The browser-gateway did not settle its execution permit.'), settlementIdentity);
+        }
+        if (completedPermit.upstreamDisposition === 'accepted'
+            && ((input.requireAcceptedJsonObject && !decoded.validJsonObject)
+                || (input.validateAcceptedData
+                    && !input.validateAcceptedData(result.data)))) {
+            return abandonKnownPermitAndRethrow(permitId, new Error('The accepted browser-gateway sync response is invalid.'), settlementIdentity);
+        }
+        if (!input.applying) {
+            if (completedPermit.upstreamDisposition === 'accepted') {
+                let released;
+                try {
+                    released = await options.client.releasePermit({
+                        permitId,
+                        workspaceId: options.workspaceId,
+                        coordinatorGeneration: options.coordinatorGeneration,
+                    });
+                }
+                catch (error) {
+                    return abandonKnownPermitAndRethrow(permitId, error, settlementIdentity);
+                }
+                const releasedPermit = released?.permit;
+                if (!releasedPermit
+                    || releasedPermit.permitId !== permitId
+                    || releasedPermit.workspaceId !== options.workspaceId
+                    || releasedPermit.coordinatorGeneration
+                        !== options.coordinatorGeneration
+                    || releasedPermit.serverInstanceId !== options.serverInstanceId
+                    || releasedPermit.ownerMode !== 'browser-gateway'
+                    || releasedPermit.operationClass !== operationClass
+                    || releasedPermit.operationIdentity
+                        !== settlementIdentity.operationIdentity
+                    || releasedPermit.state !== 'released') {
+                    return abandonKnownPermitAndRethrow(permitId, new Error('The browser-gateway execution permit was not released.'), settlementIdentity);
+                }
+            }
+            else {
+                await abandon(permitId, undefined, settlementIdentity);
+            }
+            return result;
+        }
+        if (completedPermit.upstreamDisposition !== 'accepted') {
+            await abandon(permitId, undefined, settlementIdentity);
+            return result;
+        }
+        if (!input.previousBoundary) {
+            return abandonKnownPermitAndRethrow(permitId, new Error('A browser-gateway applying request did not declare its prior boundary.'), settlementIdentity);
+        }
+        const token = Object.freeze({});
+        receiptMetadata.set(token, {
+            permitId,
+            workspaceId: options.workspaceId,
+            previousBoundary: input.previousBoundary,
+            operationClass,
+            operationIdentity: settlementIdentity.operationIdentity,
+        });
+        return {
+            ...result,
+            transferReceipt: { token },
+        };
+    };
+    const readReceipts = (workspaceId, receipts, expectedBoundary) => {
+        assertWorkspace(workspaceId);
+        if (!Array.isArray(receipts) || receipts.length === 0) {
+            throw new TypeError('A browser-gateway apply completion group requires transfer receipts.');
+        }
+        const metadata = receipts.map((receipt) => {
+            if (!receipt || typeof receipt !== 'object') {
+                throw new TypeError('The browser-gateway transfer receipt is invalid.');
+            }
+            const token = receipt.token;
+            if (!token || typeof token !== 'object') {
+                throw new TypeError('The browser-gateway transfer receipt token is invalid.');
+            }
+            const resolved = receiptMetadata.get(token);
+            if (!resolved || resolved.workspaceId !== workspaceId) {
+                throw new TypeError('The browser-gateway transfer receipt does not belong to this adapter.');
+            }
+            if (expectedBoundary
+                && canonicalWorkspaceSyncJson(resolved.previousBoundary)
+                    !== canonicalWorkspaceSyncJson(expectedBoundary)) {
+                throw new TypeError('The browser-gateway transfer receipt starts at a different boundary.');
+            }
+            return resolved;
+        });
+        if (new Set(metadata.map((entry) => entry.permitId)).size !== metadata.length) {
+            throw new TypeError('The browser-gateway apply completion group contains duplicate receipts.');
+        }
+        return metadata;
+    };
+    const completionGroup = (workspaceId, receipts, previousBoundary, expectedBoundary) => {
+        const metadata = readReceipts(workspaceId, receipts, previousBoundary);
+        return {
+            version: WORKSPACE_SYNC_ENGINE_TRANSFER_COMPLETION_VERSION,
+            workspaceId,
+            coordinatorGeneration: options.coordinatorGeneration,
+            ownerMode: 'browser-gateway',
+            serverInstanceId: options.serverInstanceId,
+            permitIds: metadata.map((entry) => entry.permitId),
+            previousBoundary,
+            expectedBoundary,
+        };
+    };
+    return {
+        handshakeWorkspace: (workspaceId) => execute({
+            operation: { type: 'handshake', workspaceId },
+            applying: false,
+        }),
+        provisionWorkspace: (input) => execute({
+            operation: { type: 'provision', ...input },
+            applying: false,
+        }),
+        pushWorkspaceChanges: (input) => {
+            const { ownership } = input;
+            const pushBoundary = parseWorkspaceSyncEngineV2PushBoundary(input.pushBoundary);
+            const expectedTaskEchoIds = workspaceSyncEngineExpectedTaskEchoIds(input.changes);
+            return execute({
+                operation: {
+                    type: 'push',
+                    workspaceId: input.workspaceId,
+                    idempotencyKey: input.idempotencyKey,
+                    changes: input.changes,
+                    ...(input.repairMode === true ? { repairMode: true } : {}),
+                    ...(ownership.activeV3TaskMetadataIds.length > 0
+                        ? { activeV3TaskMetadataIds: ownership.activeV3TaskMetadataIds }
+                        : {}),
+                    ...(ownership.activeV3TaskLifecycleIds.length > 0
+                        ? { activeV3TaskLifecycleIds: ownership.activeV3TaskLifecycleIds }
+                        : {}),
+                    ...(ownership.activeV3TaskReopenAssigneeIds.length > 0
+                        ? { activeV3TaskReopenAssigneeIds: ownership.activeV3TaskReopenAssigneeIds }
+                        : {}),
+                    ...(ownership.activeV3InitiativeIds.length > 0
+                        ? { activeV3InitiativeIds: ownership.activeV3InitiativeIds }
+                        : {}),
+                    ...(ownership.initiativeProjectionOwner === 'v3'
+                        ? { v3InitiativeProjectionOwned: true }
+                        : {}),
+                    ...(ownership.combinedCoverage
+                        ? {
+                            combinedCoverage: ownership.combinedCoverage,
+                            excludedProjections: ownership.combinedExcludedProjections || [],
+                        }
+                        : {}),
+                },
+                operationIdentity: input.idempotencyKey,
+                previousBoundary: pushBoundary,
+                applying: true,
+                requireAcceptedJsonObject: true,
+                validateAcceptedData: (value) => {
+                    try {
+                        parseWorkspaceSyncEngineAppliedTaskUpserts(value, expectedTaskEchoIds);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+            });
+        },
+        pullWorkspaceChanges: (input) => {
+            const coverage = input.excludedProjections?.length
+                ? resolveWorkspaceSyncV3CombinedCoverageForExclusions(input.excludedProjections)
+                : null;
+            return execute({
+                operation: {
+                    type: 'pull',
+                    ...input,
+                    ...(coverage ? { coverage } : {}),
+                    excludedProjections: input.excludedProjections
+                        ? [...input.excludedProjections]
+                        : undefined,
+                },
+                previousBoundary: v2Boundary(input.cursor),
+                applying: true,
+                requireAcceptedJsonObject: true,
+                validateAcceptedData: (value) => isValidV2PullPage(value, input.workspaceId),
+            });
+        },
+        pullWorkspaceContent: (input) => {
+            const { previousCursor, ...request } = input;
+            return execute({
+                operation: { type: 'content-pull', ...request },
+                previousBoundary: v2Boundary(previousCursor),
+                applying: true,
+            });
+        },
+        pullInitiativeFeed: (input) => execute({
+            operation: {
+                type: 'v3-feed',
+                ...input,
+                limit: input.limit || 100,
+            },
+            previousBoundary: v3Boundary({
+                projection: 'initiative',
+                cursor: input.repairCursor || input.cursor,
+            }),
+            applying: true,
+        }),
+        pullInitiativeRepair: (input) => execute({
+            operation: {
+                type: 'initiative-repair',
+                ...input,
+                limit: input.limit || 100,
+            },
+            previousBoundary: v3Boundary({
+                projection: 'initiative',
+                cursor: input.cursor,
+            }),
+            applying: true,
+        }),
+        pullCombinedFeed: (input) => execute({
+            operation: {
+                type: 'v3-feed',
+                ...input,
+                limit: input.limit || 100,
+            },
+            previousBoundary: v3Boundary({
+                projection: 'combined',
+                cursor: input.repairCursor || input.cursor,
+                coverage: input.coverage || WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR,
+            }),
+            applying: true,
+        }),
+        pullCombinedRepair: (input) => execute({
+            operation: {
+                type: 'combined-repair',
+                ...input,
+                limit: input.limit || 100,
+                coverage: input.coverage || WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR,
+            },
+            previousBoundary: v3Boundary({
+                projection: 'combined',
+                cursor: input.cursor,
+                coverage: input.coverage || WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR,
+            }),
+            applying: true,
+        }),
+        pullTaskCommentAudit: (input) => execute({
+            operation: {
+                type: 'task-comment-audit',
+                ...input,
+                limit: input.limit || 50,
+            },
+            previousBoundary: v3Boundary({
+                projection: 'task-comment-audit',
+                cursor: input.cursor,
+            }),
+            applying: true,
+        }),
+        abandonTransferReceipts: async ({ workspaceId, receipts, errorCode }) => {
+            const metadata = readReceipts(workspaceId, receipts);
+            await Promise.all(metadata.map((receipt) => (abandon(receipt.permitId, errorCode, {
+                operationClass: receipt.operationClass,
+                operationIdentity: receipt.operationIdentity,
+                acceptedReceipt: true,
+            }))));
+        },
+        acknowledgeNonApplyingTransferReceipts: async ({ workspaceId, receipts }) => {
+            const metadata = readReceipts(workspaceId, receipts);
+            await Promise.all(metadata.map(async (receipt) => {
+                const released = await options.client.releasePermit({
+                    permitId: receipt.permitId,
+                    workspaceId,
+                    coordinatorGeneration: options.coordinatorGeneration,
+                    ...(receipt.operationClass === 'push'
+                        ? {
+                            pushBoundary: parseWorkspaceSyncEngineV2PushBoundary(receipt.previousBoundary),
+                        }
+                        : {}),
+                });
+                if (!released?.permit
+                    || released.permit.state !== 'released'
+                    || released.permit.permitId !== receipt.permitId
+                    || released.permit.workspaceId !== workspaceId
+                    || released.permit.coordinatorGeneration
+                        !== options.coordinatorGeneration
+                    || released.permit.serverInstanceId !== options.serverInstanceId
+                    || released.permit.ownerMode !== 'browser-gateway'
+                    || released.permit.operationClass !== receipt.operationClass) {
+                    throw new Error('The browser-gateway non-applying transfer receipt was not released.');
+                }
+            }));
+        },
+        buildV2ApplyCompletionGroup: ({ workspaceId, previousCursor, nextCursor, receipts, }) => completionGroup(workspaceId, receipts, v2Boundary(previousCursor), v2Boundary(nextCursor)),
+        buildV2PushApplyCompletionGroup: ({ workspaceId, pushBoundary, receipts, }) => completionGroup(workspaceId, receipts, parseWorkspaceSyncEngineV2PushBoundary(pushBoundary), parseWorkspaceSyncEngineV2PushBoundary(pushBoundary)),
+        buildV3ApplyCompletionGroup: ({ workspaceId, apply, receipts }) => {
+            const metadata = readReceipts(workspaceId, receipts);
+            const previousBoundary = metadata[0].previousBoundary;
+            if (!('projection' in previousBoundary)
+                || previousBoundary.projection !== apply.projection
+                || metadata.some((entry) => (canonicalWorkspaceSyncJson(entry.previousBoundary)
+                    !== canonicalWorkspaceSyncJson(previousBoundary)))) {
+                throw new TypeError('The v3 transfer receipts do not match the applied projection.');
+            }
+            const acceptedRepairTransition = apply.kind === 'repair'
+                && apply.previousCursor === null
+                && metadata.every((entry) => entry.operationClass === 'pull');
+            if (previousBoundary.cursor !== apply.previousCursor
+                && !acceptedRepairTransition) {
+                throw new TypeError('The v3 apply does not start at the receipt boundary.');
+            }
+            const expectedOperationClass = apply.kind === 'delta' || apply.kind === 'audit'
+                ? 'pull'
+                : 'repair';
+            if (!acceptedRepairTransition
+                && metadata.some((entry) => entry.operationClass !== expectedOperationClass)) {
+                throw new TypeError('The v3 transfer receipt operation does not match the apply.');
+            }
+            return completionGroup(workspaceId, receipts, previousBoundary, {
+                ...previousBoundary,
+                cursor: apply.nextCursor,
+            });
+        },
+    };
+}

package/dist/sync/engine/workspaceSyncEngineContracts.d.ts

@@ -0,0 +1,78 @@
+import type { WorkspaceSyncChange } from '../workspaceSyncModel.js';
+import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
+export interface WorkspaceSyncEngineClock {
+    now(): Date;
+}
+export interface WorkspaceSyncEngineCancellation {
+    readonly aborted: boolean;
+    throwIfAborted(): void;
+}
+export interface WorkspaceSyncEngineScheduler {
+    schedule(delayMs: number, callback: () => void): {
+        cancel(): void;
+    };
+}
+export interface WorkspaceSyncEngineConnectivity {
+    isOnline(): boolean;
+}
+export interface WorkspaceSyncEngineTransport {
+    handshake(workspaceId: string, cancellation: WorkspaceSyncEngineCancellation): Promise<unknown>;
+    pull(input: {
+        workspaceId: string;
+        cursor: string | null;
+        repairMode: boolean;
+        cancellation: WorkspaceSyncEngineCancellation;
+    }): Promise<unknown>;
+    push(input: {
+        workspaceId: string;
+        operationIdentity: string;
+        changes: WorkspaceSyncChange[];
+        repairMode: boolean;
+        cancellation: WorkspaceSyncEngineCancellation;
+    }): Promise<unknown>;
+}
+export interface WorkspaceSyncEngineLocalApply {
+    apply(input: {
+        workspaceId: string;
+        previousCursor: string | null;
+        changes: WorkspaceSyncChange[];
+        nextCursor: string | null;
+        cancellation: WorkspaceSyncEngineCancellation;
+    }): Promise<{
+        localDataVersion: number;
+        appliedChanges: number;
+    }>;
+}
+export interface WorkspaceSyncEngineDurability {
+    readPhase(workspaceId: string): Promise<WorkspaceSyncPhase>;
+    readCommittedCursor(workspaceId: string): Promise<string | null>;
+    countPendingOperations(workspaceId: string): Promise<number>;
+}
+export interface WorkspaceSyncEngineEventSink {
+    record(event: {
+        workspaceId: string;
+        operation: 'handshake' | 'pull' | 'push' | 'repair' | 'apply';
+        status: 'started' | 'succeeded' | 'failed';
+        code?: string | null;
+        changeCount?: number;
+        durationMs?: number;
+    }): void;
+}
+export interface WorkspaceSyncEngineStatusSink {
+    publish(snapshot: {
+        workspaceId: string;
+        phase: WorkspaceSyncPhase;
+        busy: boolean;
+        issueCode: string | null;
+    }): void;
+}
+export interface WorkspaceSyncEnginePorts {
+    clock: WorkspaceSyncEngineClock;
+    scheduler: WorkspaceSyncEngineScheduler;
+    connectivity: WorkspaceSyncEngineConnectivity;
+    transport: WorkspaceSyncEngineTransport;
+    localApply: WorkspaceSyncEngineLocalApply;
+    durability: WorkspaceSyncEngineDurability;
+    events: WorkspaceSyncEngineEventSink;
+    status: WorkspaceSyncEngineStatusSink;
+}

package/dist/sync/engine/workspaceSyncEngineContracts.js

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