@taskforcehq/taskforce 0.3.326 → 0.3.328

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

@@ -0,0 +1,63 @@
+import type { TaskforceCore, TaskforceSyncCapable } from '../../core/Taskforce.js';
+import type { WorkspaceSyncAgentConversationSnapshot, WorkspaceSyncAgentRoleSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncAssetSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncDocumentSnapshot, WorkspaceSyncEntityEventSnapshot, WorkspaceSyncTaskforceAgentSkillSnapshot, WorkspaceSyncTaskforceAgentSnapshot, WorkspaceSyncPayload } from '../workspaceSyncModel.js';
+import { type WorkspaceSyncV2FrozenSnapshot, type WorkspaceSyncV2PushBaseline } from '../workspaceSyncV2SnapshotBuilder.js';
+import type { WorkspacePushSyncResult } from '../syncService.js';
+import type { WorkspaceSyncPushBaselineSnapshot } from '../workspaceSyncState.js';
+export type WorkspaceSyncEngineServerSnapshotCore = Pick<TaskforceCore & TaskforceSyncCapable, 'getPaths' | 'listTasks' | 'listArchive' | 'listDeletedTasks' | 'listTaskRelationshipsForSync' | 'listInitiatives' | 'listWorkstreams' | 'getTaxonomiesSyncSnapshot' | 'listAiProfiles'>;
+export interface WorkspaceSyncEngineServerContentSnapshotReader {
+    listWorkspaceSyncDocumentIndex(basePath: string, workspaceId: string): Promise<readonly {
+        path: string;
+    }[]>;
+    listWorkspaceSyncDocumentsSnapshot(basePath: string, workspaceId: string): Promise<readonly WorkspaceSyncDocumentSnapshot[]>;
+    listWorkspaceSyncBinaryAssetIndex(workspaceId: string): Promise<readonly {
+        path: string;
+    }[]>;
+    listWorkspaceSyncBinaryAssetsSnapshot(basePath: string, workspaceId: string): Promise<readonly WorkspaceSyncAssetSnapshot[]>;
+}
+export interface WorkspaceSyncEngineServerCollaborationSnapshotReader {
+    listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId: string): readonly WorkspaceSyncDocumentReviewSessionSnapshot[];
+    listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId: string): readonly WorkspaceSyncDocumentReviewCommentSnapshot[];
+    listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId: string): readonly WorkspaceSyncAnnotatedAttachmentSessionSnapshot[];
+    listWorkspaceSyncTaskforceAgentsSnapshot(workspaceId: string): readonly WorkspaceSyncTaskforceAgentSnapshot[];
+    listWorkspaceSyncAgentRolesSnapshot(workspaceId: string): readonly WorkspaceSyncAgentRoleSnapshot[];
+    listWorkspaceSyncTaskforceAgentSkillsSnapshot(workspaceId: string): readonly WorkspaceSyncTaskforceAgentSkillSnapshot[];
+    listWorkspaceSyncAgentConversationsSnapshot(workspaceId: string): readonly WorkspaceSyncAgentConversationSnapshot[];
+    listWorkspaceSyncTaskEventsSnapshot(workspaceId: string, options: {
+        cursor: {
+            watermark: string;
+            id: string;
+        } | null;
+        limit: number;
+    }): readonly WorkspaceSyncEntityEventSnapshot[];
+}
+export interface WorkspaceSyncEngineServerSnapshotReaderOptions {
+    core: WorkspaceSyncEngineServerSnapshotCore;
+    contentSyncState: WorkspaceSyncEngineServerContentSnapshotReader;
+    collaborationSyncState: WorkspaceSyncEngineServerCollaborationSnapshotReader;
+}
+export interface WorkspaceSyncEngineServerSnapshotReader {
+    read(workspaceId: string): Promise<WorkspaceSyncV2FrozenSnapshot>;
+}
+export interface WorkspaceSyncEngineServerPushCandidate {
+    signature: string;
+    payload: WorkspaceSyncPayload;
+}
+export interface WorkspaceSyncEngineServerPushCandidateProvider {
+    buildPushCandidate(input: {
+        workspaceId: string;
+        pushBaseline: WorkspaceSyncPushBaselineSnapshot | null;
+        forceAllAiProfiles: boolean;
+        repairMode: boolean;
+        forceDocumentPaths?: ReadonlySet<string>;
+        forceAssetPaths?: ReadonlySet<string>;
+    }): Promise<WorkspaceSyncEngineServerPushCandidate>;
+    buildPushBaseline(input: {
+        workspaceId: string;
+        previousBaseline: WorkspaceSyncPushBaselineSnapshot | null;
+        payload: WorkspaceSyncPayload;
+        result: WorkspacePushSyncResult;
+    }): WorkspaceSyncPushBaselineSnapshot;
+}
+export declare function toWorkspaceSyncV2PushBaseline(snapshot: WorkspaceSyncPushBaselineSnapshot | null, currentTaxonomyStateFingerprint?: string): WorkspaceSyncV2PushBaseline;
+export declare function createWorkspaceSyncEngineServerPushCandidateProvider(snapshotReader: WorkspaceSyncEngineServerSnapshotReader): WorkspaceSyncEngineServerPushCandidateProvider;
+export declare function createWorkspaceSyncEngineServerSnapshotReader(options: WorkspaceSyncEngineServerSnapshotReaderOptions): WorkspaceSyncEngineServerSnapshotReader;

package/dist/sync/engine/workspaceSyncEngineServerSnapshotReader.js

@@ -0,0 +1,276 @@
+import { buildWorkspaceSyncV2Candidate, createWorkspaceSyncV2FrozenSnapshot, } from '../workspaceSyncV2SnapshotBuilder.js';
+const SNAPSHOT_PAGE_SIZE = 10_000;
+function taxonomyStateFingerprint(value) {
+    try {
+        return JSON.stringify(value && typeof value === 'object' ? value : null);
+    }
+    catch {
+        return 'null';
+    }
+}
+function stringMap(entries) {
+    return new Map(Array.isArray(entries) ? entries : []);
+}
+function stringSet(values, fallback) {
+    return new Set((Array.isArray(values) ? values : Array.from(fallback))
+        .map((value) => String(value || '').trim())
+        .filter(Boolean));
+}
+export function toWorkspaceSyncV2PushBaseline(snapshot, currentTaxonomyStateFingerprint = '') {
+    if (!snapshot) {
+        return {
+            lastPushedTaskIds: new Set(),
+            lastPushedWatermarks: new Map(),
+            lastPushedTaskChangeKeys: new Map(),
+            lastPushedTaskRelationshipChangeKeys: new Map(),
+            lastPushedTaxonomyChangeKey: '',
+            lastPushedInitiativeIds: new Set(),
+            lastPushedInitiativeWatermarks: new Map(),
+            lastPushedWorkstreamIds: new Set(),
+            lastPushedWorkstreamWatermarks: new Map(),
+            lastPushedAiProfileIds: new Set(),
+            lastPushedAiProfileWatermarks: new Map(),
+            lastPushedAiProfileChangeKeys: new Map(),
+            lastPushedDocumentPaths: new Set(),
+            lastPushedDocumentWatermarks: new Map(),
+            lastPushedAssetPaths: new Set(),
+            lastPushedAssetWatermarks: new Map(),
+            lastPushedDocumentReviewSessionIds: new Set(),
+            lastPushedDocumentReviewSessionWatermarks: new Map(),
+            lastPushedDocumentReviewCommentIds: new Set(),
+            lastPushedDocumentReviewCommentWatermarks: new Map(),
+            lastPushedAnnotatedAttachmentSessionIds: new Set(),
+            lastPushedAnnotatedAttachmentSessionWatermarks: new Map(),
+            lastPushedTaskforceAgentIds: new Set(),
+            lastPushedTaskforceAgentWatermarks: new Map(),
+            lastPushedTaskforceAgentSkillIds: new Set(),
+            lastPushedTaskforceAgentSkillWatermarks: new Map(),
+            lastPushedAgentConversationIds: new Set(),
+            lastPushedAgentConversationWatermarks: new Map(),
+            lastPushedTaskEventWatermarks: new Map(),
+            baselineResetReason: 'missing-baseline',
+        };
+    }
+    const taskWatermarks = stringMap(snapshot.taskWatermarks);
+    const taxonomyMatches = !currentTaxonomyStateFingerprint
+        || !snapshot.taxonomyStateFingerprint
+        || snapshot.taxonomyStateFingerprint === currentTaxonomyStateFingerprint;
+    const initiativeWatermarks = stringMap(snapshot.initiativeWatermarks);
+    const workstreamWatermarks = stringMap(snapshot.workstreamWatermarks);
+    const aiProfileWatermarks = stringMap(snapshot.aiProfileWatermarks);
+    const documentWatermarks = stringMap(snapshot.documentWatermarks);
+    const assetWatermarks = stringMap(snapshot.assetWatermarks);
+    const documentReviewSessionWatermarks = stringMap(snapshot.documentReviewSessionWatermarks);
+    const documentReviewCommentWatermarks = stringMap(snapshot.documentReviewCommentWatermarks);
+    const annotatedAttachmentSessionWatermarks = stringMap(snapshot.annotatedAttachmentSessionWatermarks);
+    const taskforceAgentWatermarks = stringMap(snapshot.taskforceAgentWatermarks);
+    const taskforceAgentSkillWatermarks = stringMap(snapshot.taskforceAgentSkillWatermarks);
+    const agentConversationWatermarks = stringMap(snapshot.agentConversationWatermarks);
+    return {
+        lastPushedTaskIds: stringSet(snapshot.taskIds, taskWatermarks.keys()),
+        lastPushedWatermarks: taxonomyMatches ? taskWatermarks : new Map(),
+        lastPushedTaskChangeKeys: stringMap(snapshot.taskChangeKeys),
+        lastPushedTaskRelationshipChangeKeys: stringMap(snapshot.taskRelationshipChangeKeys),
+        lastPushedTaxonomyChangeKey: String(snapshot.taxonomyChangeKey || ''),
+        lastPushedInitiativeIds: new Set(initiativeWatermarks.keys()),
+        lastPushedInitiativeWatermarks: initiativeWatermarks,
+        lastPushedWorkstreamIds: new Set(workstreamWatermarks.keys()),
+        lastPushedWorkstreamWatermarks: workstreamWatermarks,
+        lastPushedAiProfileIds: new Set(aiProfileWatermarks.keys()),
+        lastPushedAiProfileWatermarks: aiProfileWatermarks,
+        lastPushedAiProfileChangeKeys: stringMap(snapshot.aiProfileChangeKeys),
+        lastPushedDocumentPaths: new Set(documentWatermarks.keys()),
+        lastPushedDocumentWatermarks: documentWatermarks,
+        lastPushedAssetPaths: new Set(assetWatermarks.keys()),
+        lastPushedAssetWatermarks: assetWatermarks,
+        lastPushedDocumentReviewSessionIds: new Set(documentReviewSessionWatermarks.keys()),
+        lastPushedDocumentReviewSessionWatermarks: documentReviewSessionWatermarks,
+        lastPushedDocumentReviewCommentIds: new Set(documentReviewCommentWatermarks.keys()),
+        lastPushedDocumentReviewCommentWatermarks: documentReviewCommentWatermarks,
+        lastPushedAnnotatedAttachmentSessionIds: new Set(annotatedAttachmentSessionWatermarks.keys()),
+        lastPushedAnnotatedAttachmentSessionWatermarks: annotatedAttachmentSessionWatermarks,
+        lastPushedTaskforceAgentIds: new Set(taskforceAgentWatermarks.keys()),
+        lastPushedTaskforceAgentWatermarks: taskforceAgentWatermarks,
+        lastPushedTaskforceAgentSkillIds: new Set(taskforceAgentSkillWatermarks.keys()),
+        lastPushedTaskforceAgentSkillWatermarks: taskforceAgentSkillWatermarks,
+        lastPushedAgentConversationIds: new Set(agentConversationWatermarks.keys()),
+        lastPushedAgentConversationWatermarks: agentConversationWatermarks,
+        lastPushedTaskEventWatermarks: stringMap(snapshot.taskEventWatermarks),
+        baselineResetReason: null,
+    };
+}
+function sortedEntries(value) {
+    return Array.from(value.entries()).sort(([left], [right]) => left.localeCompare(right));
+}
+function acceptedTaxonomyStateFingerprint(previousBaseline, payload) {
+    const taxonomyChange = [...payload.changes]
+        .reverse()
+        .find((change) => change.op === 'taxonomy-upsert');
+    if (!taxonomyChange)
+        return previousBaseline?.taxonomyStateFingerprint || '';
+    return taxonomyStateFingerprint('taxonomyState' in taxonomyChange ? taxonomyChange.taxonomyState : null);
+}
+export function createWorkspaceSyncEngineServerPushCandidateProvider(snapshotReader) {
+    return Object.freeze({
+        async buildPushCandidate(input) {
+            const snapshot = await snapshotReader.read(input.workspaceId);
+            return buildWorkspaceSyncV2Candidate({
+                snapshot,
+                baseline: toWorkspaceSyncV2PushBaseline(input.pushBaseline, taxonomyStateFingerprint(snapshot.taxonomyState)),
+                forceAllAiProfiles: input.forceAllAiProfiles,
+                forceDocumentPaths: input.forceDocumentPaths,
+                forceAssetPaths: input.forceAssetPaths,
+            });
+        },
+        buildPushBaseline(input) {
+            if (!input.result.success) {
+                throw new Error('Cannot advance the workspace sync push baseline from a failed push.');
+            }
+            const { payload, result, previousBaseline } = input;
+            const taskWatermarks = result.currentTaskWatermarks
+                || payload.currentTaskWatermarks
+                || stringMap(previousBaseline?.taskWatermarks);
+            const taskChangeKeys = result.currentTaskChangeKeys
+                || payload.currentTaskChangeKeys
+                || stringMap(previousBaseline?.taskChangeKeys);
+            const taskRelationshipChangeKeys = result.currentTaskRelationshipChangeKeys
+                || payload.currentTaskRelationshipChangeKeys
+                || stringMap(previousBaseline?.taskRelationshipChangeKeys);
+            const aiProfileChangeKeys = result.currentAiProfileChangeKeys
+                || payload.currentAiProfileChangeKeys
+                || stringMap(previousBaseline?.aiProfileChangeKeys);
+            return {
+                taskIds: Array.from(result.currentTaskIds).sort(),
+                taskWatermarks: sortedEntries(taskWatermarks),
+                taskChangeKeys: sortedEntries(taskChangeKeys),
+                taskRelationshipChangeKeys: sortedEntries(taskRelationshipChangeKeys),
+                initiativeWatermarks: sortedEntries(result.currentInitiativeWatermarks),
+                workstreamWatermarks: sortedEntries(result.currentWorkstreamWatermarks),
+                aiProfileWatermarks: sortedEntries(result.currentAiProfileWatermarks),
+                aiProfileChangeKeys: sortedEntries(aiProfileChangeKeys),
+                taskforceAgentWatermarks: sortedEntries(result.currentTaskforceAgentWatermarks),
+                taskforceAgentSkillWatermarks: sortedEntries(result.currentTaskforceAgentSkillWatermarks),
+                agentConversationWatermarks: sortedEntries(result.currentAgentConversationWatermarks),
+                documentWatermarks: sortedEntries(result.currentDocumentWatermarks),
+                assetWatermarks: sortedEntries(result.currentAssetWatermarks),
+                documentReviewSessionWatermarks: sortedEntries(result.currentDocumentReviewSessionWatermarks),
+                documentReviewCommentWatermarks: sortedEntries(result.currentDocumentReviewCommentWatermarks),
+                annotatedAttachmentSessionWatermarks: sortedEntries(result.currentAnnotatedAttachmentSessionWatermarks),
+                taskEventWatermarks: sortedEntries(result.currentTaskEventWatermarks),
+                taxonomyStateFingerprint: acceptedTaxonomyStateFingerprint(previousBaseline, payload),
+                taxonomyChangeKey: result.currentTaxonomyChangeKey
+                    ?? payload.currentTaxonomyChangeKey
+                    ?? previousBaseline?.taxonomyChangeKey
+                    ?? '',
+            };
+        },
+    });
+}
+function relationshipCursor(relationship) {
+    return {
+        watermark: relationship.updatedAt,
+        id: `task-relationship:${relationship.id}`,
+    };
+}
+function eventCursor(event) {
+    const entityType = event.entityType === 'initiative' || event.entityType === 'workstream'
+        ? event.entityType
+        : 'task';
+    const entityId = String(event.entityId || event.taskId || '').trim();
+    return {
+        watermark: event.createdAt,
+        id: entityType === 'task'
+            ? `task-event:${event.id}`
+            : `${entityType}:${entityId}:event:${event.id}`,
+    };
+}
+function readAllTaskRelationships(core, workspaceId) {
+    const relationships = [];
+    let cursor = null;
+    for (;;) {
+        const page = core.listTaskRelationshipsForSync(workspaceId, cursor, SNAPSHOT_PAGE_SIZE);
+        relationships.push(...page);
+        if (page.length < SNAPSHOT_PAGE_SIZE)
+            return relationships;
+        const nextCursor = relationshipCursor(page[page.length - 1]);
+        if (cursor?.watermark === nextCursor.watermark && cursor.id === nextCursor.id) {
+            throw new Error('Workspace sync relationship snapshot reader made no pagination progress.');
+        }
+        cursor = nextCursor;
+    }
+}
+function readAllTaskEvents(collaborationSyncState, workspaceId) {
+    const events = [];
+    let cursor = null;
+    for (;;) {
+        const page = collaborationSyncState.listWorkspaceSyncTaskEventsSnapshot(workspaceId, {
+            cursor,
+            limit: SNAPSHOT_PAGE_SIZE,
+        });
+        events.push(...page);
+        if (page.length < SNAPSHOT_PAGE_SIZE)
+            return events;
+        const nextCursor = eventCursor(page[page.length - 1]);
+        if (cursor?.watermark === nextCursor.watermark && cursor.id === nextCursor.id) {
+            throw new Error('Workspace sync event snapshot reader made no pagination progress.');
+        }
+        cursor = nextCursor;
+    }
+}
+export function createWorkspaceSyncEngineServerSnapshotReader(options) {
+    return Object.freeze({
+        async read(rawWorkspaceId) {
+            const workspaceId = String(rawWorkspaceId || '').trim();
+            if (!workspaceId) {
+                throw new Error('Workspace sync server snapshot reader requires a workspace ID.');
+            }
+            const basePath = options.core.getPaths().basePath;
+            const tasks = options.core.listTasks(workspaceId).tasks;
+            const archivedTasks = options.core.listArchive(workspaceId).archived;
+            const deletedTasks = options.core.listDeletedTasks(workspaceId).deleted;
+            const taskRelationships = readAllTaskRelationships(options.core, workspaceId);
+            const initiatives = options.core.listInitiatives(workspaceId);
+            const workstreams = options.core.listWorkstreams(workspaceId);
+            const taxonomy = options.core.getTaxonomiesSyncSnapshot(workspaceId);
+            const aiProfiles = options.core.listAiProfiles(workspaceId, { includeArchived: true });
+            const documentReviewSessions = options.collaborationSyncState.listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId);
+            const documentReviewComments = options.collaborationSyncState.listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId);
+            const annotatedAttachmentSessions = options.collaborationSyncState.listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId);
+            const taskforceAgents = options.collaborationSyncState.listWorkspaceSyncTaskforceAgentsSnapshot(workspaceId);
+            const agentRoles = options.collaborationSyncState.listWorkspaceSyncAgentRolesSnapshot(workspaceId);
+            const taskforceAgentSkills = options.collaborationSyncState.listWorkspaceSyncTaskforceAgentSkillsSnapshot(workspaceId);
+            const agentConversations = options.collaborationSyncState.listWorkspaceSyncAgentConversationsSnapshot(workspaceId);
+            const taskEvents = readAllTaskEvents(options.collaborationSyncState, workspaceId);
+            const [documentIndex, documents, assetIndex, assets,] = await Promise.all([
+                options.contentSyncState.listWorkspaceSyncDocumentIndex(basePath, workspaceId),
+                options.contentSyncState.listWorkspaceSyncDocumentsSnapshot(basePath, workspaceId),
+                options.contentSyncState.listWorkspaceSyncBinaryAssetIndex(workspaceId),
+                options.contentSyncState.listWorkspaceSyncBinaryAssetsSnapshot(basePath, workspaceId),
+            ]);
+            return createWorkspaceSyncV2FrozenSnapshot({
+                workspaceId,
+                tasks,
+                archivedTasks,
+                deletedTasks,
+                taskRelationships,
+                initiatives,
+                workstreams,
+                taxonomies: taxonomy.taxonomies,
+                taxonomyState: taxonomy.taxonomyState,
+                aiProfiles,
+                documents,
+                assets,
+                currentDocumentPaths: new Set(documentIndex.map((entry) => entry.path)),
+                currentAssetPaths: new Set(assetIndex.map((entry) => entry.path)),
+                documentReviewSessions,
+                documentReviewComments,
+                annotatedAttachmentSessions,
+                taskforceAgents,
+                agentRoles,
+                taskforceAgentSkills,
+                agentConversations,
+                taskEvents,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,20 @@
+import type { LocalSyncExecutionPermitOwnerMode } from '../coordinator/localSyncExecutionPermitTypes.js';
+export declare const WORKSPACE_SYNC_ENGINE_TRANSFER_COMPLETION_VERSION: 1;
+export interface WorkspaceSyncEngineTransferCompletionGroup {
+    version: typeof WORKSPACE_SYNC_ENGINE_TRANSFER_COMPLETION_VERSION;
+    workspaceId: string;
+    coordinatorGeneration: number;
+    ownerMode: LocalSyncExecutionPermitOwnerMode;
+    serverInstanceId: string;
+    permitIds: readonly string[];
+    previousBoundary: unknown;
+    expectedBoundary: unknown;
+}
+export interface WorkspaceSyncEngineTransferBoundaryCommitInput {
+    previousBoundary: unknown;
+    expectedBoundary: unknown;
+    applyResult: unknown;
+}
+export type WorkspaceSyncEngineTransferBoundaryCommitter = (input: WorkspaceSyncEngineTransferBoundaryCommitInput) => unknown;
+export declare function validateWorkspaceSyncEngineTransferCompletionGroup(input: WorkspaceSyncEngineTransferCompletionGroup): void;
+export declare function assertWorkspaceSyncEngineTransferBoundary(actualBoundary: unknown, expectedBoundary: unknown): void;

package/dist/sync/engine/workspaceSyncEngineTransferCompletion.js

@@ -0,0 +1,37 @@
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
+export const WORKSPACE_SYNC_ENGINE_TRANSFER_COMPLETION_VERSION = 1;
+export function validateWorkspaceSyncEngineTransferCompletionGroup(input) {
+    if (input.version !== WORKSPACE_SYNC_ENGINE_TRANSFER_COMPLETION_VERSION) {
+        throw new TypeError('The sync transfer completion group version is unsupported.');
+    }
+    if (!input.workspaceId.trim()) {
+        throw new TypeError('The sync transfer completion group workspace is required.');
+    }
+    if (!Number.isSafeInteger(input.coordinatorGeneration) || input.coordinatorGeneration < 0) {
+        throw new TypeError('The sync transfer completion group generation is invalid.');
+    }
+    if (input.ownerMode !== 'browser-gateway' && input.ownerMode !== 'server') {
+        throw new TypeError('The sync transfer completion group owner is invalid.');
+    }
+    if (!input.serverInstanceId.trim()) {
+        throw new TypeError('The sync transfer completion group server instance is required.');
+    }
+    if (!Array.isArray(input.permitIds) || input.permitIds.length === 0) {
+        throw new TypeError('The sync transfer completion group requires at least one permit.');
+    }
+    const normalizedIds = input.permitIds.map((permitId) => permitId.trim());
+    if (normalizedIds.some((permitId, index) => (!permitId || permitId !== input.permitIds[index]))) {
+        throw new TypeError('The sync transfer completion group contains an invalid permit ID.');
+    }
+    if (new Set(normalizedIds).size !== normalizedIds.length) {
+        throw new TypeError('The sync transfer completion group contains duplicate permit IDs.');
+    }
+    canonicalWorkspaceSyncJson(input.previousBoundary);
+    canonicalWorkspaceSyncJson(input.expectedBoundary);
+}
+export function assertWorkspaceSyncEngineTransferBoundary(actualBoundary, expectedBoundary) {
+    if (canonicalWorkspaceSyncJson(actualBoundary)
+        !== canonicalWorkspaceSyncJson(expectedBoundary)) {
+        throw new Error('The committed sync transfer boundary does not match the expected boundary.');
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { WorkspaceSyncPayload } from '../workspaceSyncModel.js';
+export interface PendingWorkspacePushReplay {
+    signature: string;
+    payload: WorkspaceSyncPayload;
+    forceAllAiProfiles: boolean;
+    repairMode: boolean;
+}

package/dist/sync/engine/workspaceSyncEngineTransferTypes.js

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

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

@@ -0,0 +1,240 @@
+import { type EnsureWorkspaceReadyResult } from '../syncService.js';
+import type { WorkspaceSyncPayload } from '../workspaceSyncModel.js';
+import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
+import type { WorkspaceSyncV3CombinedCoverageSelector } from '../v3/workspaceSyncV3CombinedWireContract.js';
+import type { WorkspaceSyncEngineRuntime } from './workspaceSyncEngineRuntime.js';
+import type { WorkspaceSyncEngineLocalServices } from './workspaceSyncEngineLocalServices.js';
+import type { WorkspaceSyncEngineRemoteServices, WorkspaceSyncEngineRemoteTransferReceipt } from './workspaceSyncEngineRemoteServices.js';
+export type { PendingWorkspacePushReplay } from './workspaceSyncEngineTransferTypes.js';
+type StateSetter<T> = (value: T | ((current: T) => T)) => void;
+export declare function combinedAttachmentAssetHydrationId(input: {
+    status: number;
+    error: unknown;
+    causeCode?: string;
+    causeAssetId?: string;
+}): string | null;
+export declare function createWorkspaceSyncV3TransferBindings(input: {
+    workspaceId: string;
+    remoteServices: WorkspaceSyncEngineRemoteServices;
+    localServices: WorkspaceSyncEngineLocalServices;
+}): {
+    abandonPendingReceipts: () => Promise<void>;
+    initiative: {
+        getLocalProjection: typeof import("../cloudSyncApi.js").getLocalWorkspaceSyncV3Projection;
+        applyLocalProjection: (workspaceId: string, applyInput: Parameters<WorkspaceSyncEngineLocalServices["applyInitiativeProjection"]>[1]) => Promise<import("../cloudSyncApi.js").SyncHttpResult<{
+            success?: boolean;
+            projection?: import("../v3/workspaceSyncV3ProjectionState.js").WorkspaceSyncV3ProjectionState;
+            result?: {
+                projection?: import("../v3/workspaceSyncV3ProjectionState.js").WorkspaceSyncV3ProjectionState;
+            };
+        }>>;
+        pullFeed: (_resolveCloudAuthUrl: (path: string) => string, pullInput: any) => Promise<import("../cloudSyncApi.js").SyncHttpResult<{
+            success: true;
+            protocolVersion: 3;
+            workspaceId: string;
+            coverage: import("../v3/workspaceSyncV3FeedProfile.js").WorkspaceSyncV3CoverageProfile;
+            cycleHighWatermark: string;
+            lastScannedSequence: string;
+            entries: import("../v3/workspaceSyncV3Feed.js").WorkspaceSyncV3FeedEntry[];
+            nextCursor: string;
+            hasMore: boolean;
+            diagnostics: {
+                scannedCount: number;
+                coveredCount: number;
+                responseBytes: number;
+            };
+        } | import("../cloudSyncApi.js").WorkspaceSyncV3RepairResponse> & {
+            transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+        }>;
+        pullInitiativeRepair: (_resolveCloudAuthUrl: (path: string) => string, pullInput: any) => Promise<import("../cloudSyncApi.js").SyncHttpResult<{
+            success?: boolean;
+            workspaceId?: string;
+            entries?: import("../v3/workspaceSyncV3Feed.js").WorkspaceSyncV3FeedEntry[];
+            snapshotSequence?: string;
+            hasMore?: boolean;
+            nextRepairCursor?: string | null;
+            error?: string;
+            code?: string;
+        }> & {
+            transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+        }>;
+    };
+    combined: {
+        getLocalProjection: typeof import("../cloudSyncApi.js").getLocalWorkspaceSyncV3CombinedProjection;
+        applyLocalProjection: (workspaceId: string, applyInput: Parameters<WorkspaceSyncEngineLocalServices["applyCombinedProjection"]>[1], coverage?: Parameters<WorkspaceSyncEngineLocalServices["applyCombinedProjection"]>[2]) => Promise<import("../cloudSyncApi.js").SyncHttpResult<{
+            success?: boolean;
+            contractVersion?: number;
+            workspaceId?: string;
+            code?: string;
+            error?: string;
+            causeCode?: string;
+            causeAssetId?: string;
+            projection?: import("../v3/workspaceSyncV3CombinedProjectionState.js").WorkspaceSyncV3CombinedProjectionState;
+            result?: {
+                state?: "staged" | "activated" | "recovered" | "invalidated" | "rolled-back" | "duplicate" | "applied";
+                projection?: import("../v3/workspaceSyncV3CombinedProjectionState.js").WorkspaceSyncV3CombinedProjectionState;
+            };
+        }>>;
+        getLocalTaskCommentAudit: typeof import("../cloudSyncApi.js").getLocalWorkspaceSyncV3TaskCommentAudit;
+        applyLocalTaskCommentAudit: (workspaceId: string, page: Parameters<WorkspaceSyncEngineLocalServices["applyTaskCommentAuditPage"]>[1]) => Promise<import("../cloudSyncApi.js").SyncHttpResult<{
+            success?: boolean;
+            contractVersion?: number;
+            workspaceId?: string;
+            result?: {
+                previousCursor: string | null;
+                nextCursor: string | null;
+                nextSweepAt: string | null;
+                reconciliationsQueued: number;
+                activityEventsApplied: number;
+                busyEntriesSkipped: number;
+                stale?: boolean;
+            };
+        }>>;
+        pullFeed: (_resolveCloudAuthUrl: (path: string) => string, pullInput: any) => Promise<import("../cloudSyncApi.js").SyncHttpResult<import("../cloudSyncApi.js").WorkspaceSyncV3CombinedRepairResponse | import("../cloudSyncApi.js").WorkspaceSyncV3CombinedDeltaPage | import("../cloudSyncApi.js").WorkspaceSyncV3CombinedFailureResponse> & {
+            transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+        }>;
+        pullFallbackRepair: (_resolveCloudAuthUrl: (path: string) => string, pullInput: any) => Promise<import("../cloudSyncApi.js").SyncHttpResult<(import("../v3/workspaceSyncV3CombinedRepairMaterialization.js").WorkspaceSyncV3CombinedRepairPage & {
+            legacyV2Boundary: import("../v3/workspaceSyncV3CombinedWireContract.js").WorkspaceSyncV3CombinedFallbackBoundary;
+        }) | {
+            success: false;
+            code: string;
+            error: string;
+        }> & {
+            transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+        }>;
+        pullTaskCommentAudit: (_resolveCloudAuthUrl: (path: string) => string, pullInput: any) => Promise<import("../cloudSyncApi.js").SyncHttpResult<import("../v3/workspaceSyncV3TaskCommentAudit.js").WorkspaceSyncV3TaskCommentAuditPage | {
+            success?: false;
+            code?: string;
+            error?: string;
+        }> & {
+            transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+        }>;
+    };
+};
+export interface CreateWorkspaceTransferCoordinatorArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    initiativeFeedActivationEnabled?: boolean;
+    combinedFeedActivationEnabled?: boolean;
+    combinedFeedCoverage?: WorkspaceSyncV3CombinedCoverageSelector;
+    workspaceCloudSyncEnabled: boolean;
+    currentWorkspaceId: string;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    isAuthenticated: boolean;
+    checkAuthSession: () => Promise<boolean>;
+    resolveCloudAuthUrl: (path: string) => string;
+    ensureCloudWorkspaceReadyForSync: () => Promise<EnsureWorkspaceReadyResult>;
+    ensureWorkspaceSyncReady: () => Promise<boolean>;
+    handleSyncAuthFailure: (source: 'push' | 'pull' | 'apply' | 'handshake', statusCode: number) => Promise<void>;
+    clearWorkspaceRetry: () => void;
+    clearWorkspaceIssue: () => void;
+    isWorkspaceRetryPending: () => boolean;
+    isDurableRecoveryBlockingOrdinaryPush: () => boolean;
+    isExecutionAuthorized?: () => boolean;
+    scheduleWorkspaceSyncRetry: (minDelayMs?: number) => void;
+    persistWorkspaceSyncPatchSafely: (patch: {
+        phase: 'error';
+        lastErrorMessage: string;
+    } | {
+        phase: 'active';
+        lastPushAt?: string;
+        lastPullAt?: string;
+        lastSyncedAt: string;
+        startupFullReconcileCompletedAt?: string | null;
+        pullCursor?: string | null;
+        lastErrorMessage?: null;
+    } | {
+        pullCursor: null;
+    }) => void;
+    persistWorkspaceSyncPatchBestEffort: (patch: {
+        phase: 'active';
+        pullCursor: string | null;
+        lastPullAt: string;
+        lastSyncedAt: string;
+        startupFullReconcileCompletedAt?: string | null;
+        lastErrorMessage: null;
+    } | {
+        phase: 'error';
+        lastErrorMessage: string;
+    }) => Promise<unknown>;
+    persistWorkspaceSyncWatermarksSnapshotBestEffort: () => boolean;
+    refreshWorkspaceAiProfilePushBaselineFromPersistence?: () => boolean;
+    reportSyncEvent: (workspaceId: string, event: {
+        eventType: 'pull' | 'handshake' | 'bootstrap' | 'apply' | 'push';
+        status: 'success' | 'error';
+        statusCode?: number;
+        errorMessage?: string;
+        changeCount?: number;
+        requestMs?: number;
+        details?: Record<string, unknown>;
+    }) => void;
+    acquireWorkspaceSyncLease: (workspaceId: string, owner: 'pull' | 'push' | 'repair') => Promise<boolean>;
+    releaseWorkspaceSyncLease: (workspaceId: string) => void;
+    recordWorkspaceSyncCompletion: (workspaceId: string, operation: 'pull' | 'push' | 'repair') => void;
+    reportWorkspaceWindowContention: (operation: 'pull' | 'push' | 'repair') => void;
+    refreshWorkspaceSyncMarkdownDocumentsSnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncAiProfilesSnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncAssetsSnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncTaxonomySnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncPlanningEntitiesSnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncDocumentReviewSessionsSnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: () => Promise<boolean | void>;
+    refreshWorkspaceSyncTaskforceAgentsSnapshot?: () => Promise<boolean | void>;
+    refreshLocalWorkspaceTaskCollections: () => Promise<void>;
+    buildWorkspaceSyncPayload: (options?: {
+        forceAllAiProfiles?: boolean;
+    }) => WorkspaceSyncPayload;
+    buildWorkspaceSyncSignature: () => string;
+    seedWorkspaceSnapshotPushBaseline: () => void;
+    shouldSuppressAttachBootstrapPush: (signature: string) => boolean;
+    recordSuppressedEventIds: (eventIds: Iterable<string>, options?: {
+        queueRef?: WorkspaceSyncEngineRuntime['realtimeSuppressedEventQueue'];
+        maxQueueSize?: number;
+        ttlMs?: number;
+    }) => void;
+    runtime: WorkspaceSyncEngineRuntime;
+    localServices: WorkspaceSyncEngineLocalServices;
+    remoteServices: WorkspaceSyncEngineRemoteServices;
+    setWorkspaceSyncBusy: StateSetter<boolean>;
+    setUserGlobalSyncStatus: StateSetter<'disconnected' | 'idle' | 'syncing' | 'error'>;
+    setUserGlobalSyncError: StateSetter<string | null>;
+    setWorkspaceLastErrorMessage: StateSetter<string | null>;
+    setWorkspaceLastErrorAt: StateSetter<string | null>;
+    setWorkspaceLastPullAt: StateSetter<string | null>;
+    setWorkspaceLastPushAt: StateSetter<string | null>;
+    setWorkspaceSyncPendingChanges: StateSetter<number>;
+    setTasks: StateSetter<any[]>;
+    setArchivedTasks: StateSetter<any[]>;
+    now: () => Date;
+    scheduleTask: (callback: () => void, delayMs: number) => {
+        cancel(): void;
+    };
+    logDebug?: (event: string, details?: Record<string, unknown>) => void;
+    notifyAiProfilesMutated?: (detail: {
+        workspaceId: string;
+        reason: 'sync-apply';
+        origin: 'sync-orchestrator';
+    }) => void;
+    notifyAgentsMutated?: (detail: {
+        workspaceId: string;
+        reason: 'sync-apply';
+    }) => void;
+    notifyAgentSkillsMutated?: (detail: {
+        workspaceId: string;
+        reason: 'sync-apply';
+    }) => void;
+}
+export declare function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, initiativeFeedActivationEnabled, combinedFeedActivationEnabled, combinedFeedCoverage, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, isDurableRecoveryBlockingOrdinaryPush, isExecutionAuthorized, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, persistWorkspaceSyncWatermarksSnapshotBestEffort, refreshWorkspaceAiProfilePushBaselineFromPersistence, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, recordWorkspaceSyncCompletion, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncTaxonomySnapshot, refreshWorkspaceSyncPlanningEntitiesSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshWorkspaceSyncTaskforceAgentsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, runtime, localServices, remoteServices, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks, now, scheduleTask, logDebug, notifyAiProfilesMutated, notifyAgentsMutated, notifyAgentSkillsMutated }: CreateWorkspaceTransferCoordinatorArgs): {
+    pushWorkspaceChangesToCloud: (signature: string, options?: {
+        forceAllAiProfiles?: boolean;
+        repairMode?: boolean;
+    }) => Promise<boolean>;
+    pullWorkspaceChangesFromCloud: (options?: {
+        repairMode?: boolean;
+        forceCursorNull?: boolean;
+        forceV3AuthoritativeRepair?: boolean;
+        recoveryBatchId?: string;
+    }) => Promise<boolean>;
+    resumeDeferredWork: () => void;
+    dispose: () => void;
+};