@taskforcehq/taskforce 0.3.326 → 0.3.328

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

@@ -0,0 +1,37 @@
+import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
+export type WorkspaceSyncBlockedReason = 'cloud-auth-unconfigured' | 'runtime-not-local' | 'sync-disabled' | 'invalid-workspace' | 'repair-active' | 'attach-cloud' | 'provision-local' | 'auth-required' | 'push-in-flight' | 'pull-in-flight' | 'retry-pending' | 'lease-held';
+export type WorkspaceSyncOperation = 'pull' | 'push' | 'repair';
+export type WorkspaceSyncControlPlaneDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: WorkspaceSyncBlockedReason;
+    retainPendingSignature: boolean;
+};
+interface WorkspaceSyncControlPlaneBaseArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    currentWorkspaceId: string;
+    isAuthenticated: boolean;
+}
+interface PushSyncReadinessArgs extends WorkspaceSyncControlPlaneBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    repairModeActive: boolean;
+    repairModeBypass: boolean;
+    pushInFlight: boolean;
+    pullInFlight: boolean;
+}
+interface PullSyncReadinessArgs extends WorkspaceSyncControlPlaneBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    repairModeActive: boolean;
+    repairModeBypass: boolean;
+    retryPending: boolean;
+    pushInFlight: boolean;
+    pullInFlight: boolean;
+}
+export declare function resolvePushSyncReadiness(args: PushSyncReadinessArgs): WorkspaceSyncControlPlaneDecision;
+export declare function resolvePullSyncReadiness(args: PullSyncReadinessArgs): WorkspaceSyncControlPlaneDecision;
+export declare function resolveRetrySyncReadiness(args: WorkspaceSyncControlPlaneBaseArgs): WorkspaceSyncControlPlaneDecision;
+export declare function createWorkspaceSyncLeaseHeldDecision(operation: WorkspaceSyncOperation): WorkspaceSyncControlPlaneDecision;
+export {};

package/dist/sync/engine/workspaceSyncEngineControlPlane.js

@@ -0,0 +1,79 @@
+import { isValidWorkspaceSyncWorkspaceId } from './workspaceSyncEngineIdentity.js';
+const ALLOW_SYNC_OPERATION = { allowed: true };
+function blockSyncOperation(reason, options) {
+    return {
+        allowed: false,
+        reason,
+        retainPendingSignature: options?.retainPendingSignature === true
+    };
+}
+function resolveBaseSyncReadiness(args, options) {
+    if (!args.cloudAuthConfigured)
+        return blockSyncOperation('cloud-auth-unconfigured');
+    if (args.runtimeMode !== 'local')
+        return blockSyncOperation('runtime-not-local');
+    if (!args.workspaceCloudSyncEnabled)
+        return blockSyncOperation('sync-disabled');
+    if ((options?.requireValidWorkspace ?? true)
+        && !isValidWorkspaceSyncWorkspaceId(args.currentWorkspaceId)) {
+        return blockSyncOperation('invalid-workspace');
+    }
+    return null;
+}
+export function resolvePushSyncReadiness(args) {
+    const baseReadiness = resolveBaseSyncReadiness(args);
+    if (baseReadiness)
+        return baseReadiness;
+    if (args.repairModeActive && !args.repairModeBypass) {
+        return blockSyncOperation('repair-active', { retainPendingSignature: true });
+    }
+    if (args.workspaceSyncPhase === 'attach-cloud' && !args.repairModeBypass) {
+        return blockSyncOperation('attach-cloud', { retainPendingSignature: true });
+    }
+    if (!args.isAuthenticated) {
+        return blockSyncOperation('auth-required');
+    }
+    if (args.pushInFlight) {
+        return blockSyncOperation('push-in-flight', { retainPendingSignature: true });
+    }
+    if (args.pullInFlight) {
+        return blockSyncOperation('pull-in-flight', { retainPendingSignature: true });
+    }
+    return ALLOW_SYNC_OPERATION;
+}
+export function resolvePullSyncReadiness(args) {
+    const baseReadiness = resolveBaseSyncReadiness(args);
+    if (baseReadiness)
+        return baseReadiness;
+    if (args.repairModeActive && !args.repairModeBypass) {
+        return blockSyncOperation('repair-active');
+    }
+    if (args.workspaceSyncPhase === 'provision-local') {
+        return blockSyncOperation('provision-local');
+    }
+    if (args.retryPending) {
+        return blockSyncOperation('retry-pending');
+    }
+    if (!args.isAuthenticated) {
+        return blockSyncOperation('auth-required');
+    }
+    if (args.pullInFlight) {
+        return blockSyncOperation('pull-in-flight');
+    }
+    if (args.pushInFlight) {
+        return blockSyncOperation('push-in-flight');
+    }
+    return ALLOW_SYNC_OPERATION;
+}
+export function resolveRetrySyncReadiness(args) {
+    const baseReadiness = resolveBaseSyncReadiness(args, { requireValidWorkspace: false });
+    if (baseReadiness)
+        return baseReadiness;
+    if (!args.isAuthenticated) {
+        return blockSyncOperation('auth-required');
+    }
+    return ALLOW_SYNC_OPERATION;
+}
+export function createWorkspaceSyncLeaseHeldDecision(operation) {
+    return blockSyncOperation('lease-held', { retainPendingSignature: operation === 'push' });
+}

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

@@ -0,0 +1 @@
+export declare function isValidWorkspaceSyncWorkspaceId(workspaceId: string): boolean;

package/dist/sync/engine/workspaceSyncEngineIdentity.js

@@ -0,0 +1,4 @@
+export function isValidWorkspaceSyncWorkspaceId(workspaceId) {
+    const workspaceKey = String(workspaceId || '').trim();
+    return workspaceKey.length > 0 && workspaceKey.toLowerCase() !== 'default';
+}

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

@@ -0,0 +1,68 @@
+import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
+export type WorkspaceSyncPresentationStatus = 'off' | 'syncing' | 'attention' | 'healthy';
+interface WorkspaceSyncPresentationArgs {
+    enabled: boolean;
+    phase: WorkspaceSyncPhase;
+    busy: boolean;
+    retryAt: string | null;
+    lastErrorMessage: string | null;
+    lastErrorAt: string | null;
+    lastPullAt: string | null;
+    lastPushAt: string | null;
+    nowMs: number;
+    pullLagToleranceMs?: number;
+    pendingChanges?: number;
+    durableOutbox?: {
+        pending: number;
+        inFlight: number;
+        blocked: number;
+        recovery?: {
+            state: 'awaiting_baseline' | 'baseline_ready' | 'replay_queued' | 'completed';
+            replayPending: number;
+            replayInFlight: number;
+            replayBlocked: number;
+        } | null;
+    } | null;
+}
+export declare const WORKSPACE_SYNC_PULL_FRESHNESS_WINDOW_MS: number;
+interface WorkspaceSyncLifecycleBaseArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    authSessionResolved: boolean;
+}
+interface WorkspaceSyncAutomaticPullArgs extends WorkspaceSyncLifecycleBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastPullAt: string | null;
+    retryPending: boolean;
+}
+interface WorkspaceSyncFullReconcileArgs extends WorkspaceSyncLifecycleBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    isAuthenticated: boolean;
+}
+interface WorkspaceSyncStartupRepairArgs extends WorkspaceSyncFullReconcileArgs {
+    alreadyRan: boolean;
+}
+interface WorkspaceSyncReactivePushArgs extends WorkspaceSyncLifecycleBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspaceSyncReferenceSnapshotsReady: boolean;
+}
+export declare function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt, lastErrorMessage, lastErrorAt, lastPullAt, lastPushAt, nowMs, pullLagToleranceMs, pendingChanges, durableOutbox }: WorkspaceSyncPresentationArgs): {
+    status: WorkspaceSyncPresentationStatus;
+    summary: string;
+    recommendedAction: string;
+};
+export declare function shouldScheduleWorkspaceReactivePush(args: WorkspaceSyncReactivePushArgs): boolean;
+export declare function shouldStartWorkspacePushWatchdog(args: WorkspaceSyncReactivePushArgs): boolean;
+export declare function resolveWorkspaceAutomaticPullPolicy(args: WorkspaceSyncAutomaticPullArgs): {
+    shouldStart: boolean;
+    shouldKickOffImmediately: boolean;
+};
+export declare function shouldStartWorkspacePeriodicFullReconcile(args: WorkspaceSyncFullReconcileArgs): boolean;
+export declare function shouldRunWorkspaceStartupRepair(args: WorkspaceSyncStartupRepairArgs): boolean;
+export declare function resolveWorkspaceSyncRepairPhase(args: {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastBootstrapPhase: WorkspaceSyncPhase;
+    workspaceLastPullAt: string | null;
+}): WorkspaceSyncPhase;
+export {};

package/dist/sync/engine/workspaceSyncEngineLifecyclePolicy.js

@@ -0,0 +1,180 @@
+export const WORKSPACE_SYNC_PULL_FRESHNESS_WINDOW_MS = 5 * 60_000;
+function parseSyncTimestamp(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function canRunLocalWorkspaceSyncLifecycle(args) {
+    return args.cloudAuthConfigured
+        && args.runtimeMode === 'local'
+        && args.workspaceCloudSyncEnabled
+        && args.authSessionResolved;
+}
+export function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt, lastErrorMessage, lastErrorAt, lastPullAt, lastPushAt, nowMs, pullLagToleranceMs = WORKSPACE_SYNC_PULL_FRESHNESS_WINDOW_MS, pendingChanges = 0, durableOutbox }) {
+    if (!enabled) {
+        return {
+            status: 'off',
+            summary: 'Sync is turned off for this workspace.',
+            recommendedAction: 'Turn on sync when you are ready to back up this workspace.'
+        };
+    }
+    if (phase === 'provision-local') {
+        return {
+            status: 'syncing',
+            summary: busy
+                ? 'Uploading this workspace to cloud for the first time.'
+                : 'Preparing the first upload to cloud.',
+            recommendedAction: 'Keep this window open while the first upload finishes. If it seems stalled, press Sync.'
+        };
+    }
+    if (phase === 'attach-cloud') {
+        return {
+            status: 'syncing',
+            summary: busy
+                ? 'Pulling the cloud workspace into this device.'
+                : 'Waiting for the first cloud pull into this device.',
+            recommendedAction: 'Keep this window open for the first cloud pull. If it does not move, press Repair.'
+        };
+    }
+    if ((durableOutbox?.blocked || 0) > 0) {
+        const blocked = durableOutbox?.blocked || 0;
+        const waiting = durableOutbox?.pending || 0;
+        return {
+            status: 'attention',
+            summary: `${blocked} durable local change${blocked === 1 ? '' : 's'} could not sync${waiting > 0 ? `; ${waiting} later change${waiting === 1 ? ' is' : 's are'} waiting` : ''}.`,
+            recommendedAction: 'Press Repair to reconcile and replay supported task changes. If Repair is blocked, copy the report for diagnosis.'
+        };
+    }
+    if (durableOutbox?.recovery && durableOutbox.recovery.state !== 'completed') {
+        if (durableOutbox.recovery.state === 'awaiting_baseline') {
+            return {
+                status: 'attention',
+                summary: 'Durable local recovery is waiting for an authoritative cloud repair.',
+                recommendedAction: 'Press Repair to resume the verified cloud baseline and replay.'
+            };
+        }
+        if (durableOutbox.recovery.replayBlocked > 0) {
+            return {
+                status: 'attention',
+                summary: 'A recovered local change is still blocked during replay.',
+                recommendedAction: 'Copy the Sync Manager report so the replay conflict can be diagnosed safely.'
+            };
+        }
+        return {
+            status: 'syncing',
+            summary: 'Recovered local changes are replaying against the repaired cloud baseline.',
+            recommendedAction: 'No action needed unless the recovery state remains unchanged.'
+        };
+    }
+    if (retryAt) {
+        return {
+            status: 'attention',
+            summary: 'Sync hit a temporary problem and will retry automatically.',
+            recommendedAction: 'Wait for the automatic retry, or press Sync to retry now.'
+        };
+    }
+    if (lastErrorMessage || phase === 'error') {
+        return {
+            status: 'attention',
+            summary: 'Sync needs attention before it can continue.',
+            recommendedAction: 'Press Sync to retry. If the same error keeps returning, press Repair.'
+        };
+    }
+    if (pendingChanges > 0 || (durableOutbox?.pending || 0) > 0 || (durableOutbox?.inFlight || 0) > 0) {
+        return {
+            status: 'syncing',
+            summary: 'Local changes are waiting to sync.',
+            recommendedAction: 'No action needed unless the queue remains unchanged.'
+        };
+    }
+    if (busy) {
+        return {
+            status: 'syncing',
+            summary: 'Sync is currently running.',
+            recommendedAction: 'No action needed.'
+        };
+    }
+    const lastPullMs = parseSyncTimestamp(lastPullAt);
+    const lastPushMs = parseSyncTimestamp(lastPushAt);
+    const lastErrorMs = parseSyncTimestamp(lastErrorAt);
+    if (lastPullMs === null) {
+        return {
+            status: 'attention',
+            summary: lastPushMs === null
+                ? 'This device has not completed its first cloud pull.'
+                : 'Cloud uploads are working, but this device has not completed a cloud pull.',
+            recommendedAction: 'Press Retry now. If the cloud check still does not complete, press Repair and copy the report.'
+        };
+    }
+    if (lastErrorMs !== null && lastErrorMs > lastPullMs) {
+        return {
+            status: 'attention',
+            summary: 'A sync issue occurred after the last successful cloud pull.',
+            recommendedAction: 'Press Retry now to verify cloud changes can still be received. If the issue returns, copy the report.'
+        };
+    }
+    const pullIsStale = Number.isFinite(nowMs)
+        && nowMs - lastPullMs > Math.max(0, pullLagToleranceMs);
+    if (pullIsStale) {
+        return {
+            status: 'attention',
+            summary: lastPushMs !== null && lastPushMs > lastPullMs
+                ? 'Cloud uploads are succeeding, but this device has not received cloud changes recently.'
+                : 'This device has not checked for cloud changes recently.',
+            recommendedAction: 'Press Retry now to check cloud changes. If Last cloud check does not advance, press Repair and copy the report.'
+        };
+    }
+    return {
+        status: 'healthy',
+        summary: 'A recent cloud check succeeded and no local changes are waiting.',
+        recommendedAction: 'No action needed.'
+    };
+}
+export function shouldScheduleWorkspaceReactivePush(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.workspaceSyncPhase !== 'attach-cloud'
+        && args.workspaceSyncReferenceSnapshotsReady;
+}
+export function shouldStartWorkspacePushWatchdog(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.workspaceSyncPhase === 'active'
+        && args.workspaceSyncReferenceSnapshotsReady;
+}
+export function resolveWorkspaceAutomaticPullPolicy(args) {
+    if (!canRunLocalWorkspaceSyncLifecycle(args)) {
+        return { shouldStart: false, shouldKickOffImmediately: false };
+    }
+    if (args.workspaceSyncPhase === 'provision-local' || args.workspaceSyncPhase === 'error' || args.retryPending) {
+        return { shouldStart: false, shouldKickOffImmediately: false };
+    }
+    return {
+        shouldStart: true,
+        shouldKickOffImmediately: args.workspaceSyncPhase === 'attach-cloud' || !args.lastPullAt
+    };
+}
+export function shouldStartWorkspacePeriodicFullReconcile(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.isAuthenticated
+        && args.workspaceSyncPhase === 'active';
+}
+export function shouldRunWorkspaceStartupRepair(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.isAuthenticated
+        && args.workspaceSyncPhase !== 'provision-local'
+        && args.workspaceSyncPhase !== 'attach-cloud'
+        && !args.alreadyRan;
+}
+export function resolveWorkspaceSyncRepairPhase(args) {
+    const { workspaceSyncPhase, lastBootstrapPhase, workspaceLastPullAt } = args;
+    if (workspaceSyncPhase === 'provision-local')
+        return 'provision-local';
+    if (workspaceSyncPhase === 'attach-cloud')
+        return 'attach-cloud';
+    if (workspaceSyncPhase === 'active' || lastBootstrapPhase === 'active')
+        return 'active';
+    if (lastBootstrapPhase === 'provision-local' || lastBootstrapPhase === 'attach-cloud') {
+        return lastBootstrapPhase;
+    }
+    return workspaceLastPullAt ? 'attach-cloud' : 'provision-local';
+}

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

@@ -0,0 +1,72 @@
+import type { WorkspaceSyncChange, WorkspaceSyncWorkspaceMemberSnapshot } from '../workspaceSyncModel.js';
+import type { WorkspaceSyncV2ProjectionExclusion } from '../v3/workspaceSyncV2ProjectionExclusions.js';
+import type { WorkspaceSyncV2PreparedContentPlan } from './workspaceSyncV2PreparedContent.js';
+export interface WorkspaceSyncEngineLocalApplyOptions {
+    allowReferenceNumberReassignment?: boolean;
+    workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+    coexistenceDirection: 'local-pull';
+    v2ExcludedProjections: readonly WorkspaceSyncV2ProjectionExclusion[];
+}
+export interface WorkspaceSyncEngineLocalApplyResult {
+    result: unknown;
+    deleteCount: number;
+    emittedEventIds: string[];
+}
+export interface WorkspaceSyncEngineLocalContentReader {
+    loadDocument(workspaceId: string, path: string): Promise<{
+        content: string;
+    } | null>;
+    loadAsset(workspaceId: string, path: string): Promise<{
+        contentBase64: string;
+    } | null>;
+}
+export interface WorkspaceSyncEngineLocalApplyDispatcher {
+    dispatch(workspaceId: string, changes: WorkspaceSyncChange[], options: WorkspaceSyncEngineLocalApplyOptions): Promise<WorkspaceSyncEngineLocalApplyResult>;
+}
+export interface WorkspaceSyncEngineLocalMetadataApplyTransactionHooks {
+    beforeApply?: () => unknown;
+    beforeCommit?: (result: WorkspaceSyncEngineLocalApplyResult) => unknown;
+}
+export interface WorkspaceSyncEngineLocalMetadataApplyOptions extends WorkspaceSyncEngineLocalApplyOptions {
+    transactionHooks?: WorkspaceSyncEngineLocalMetadataApplyTransactionHooks;
+}
+export interface WorkspaceSyncEngineLocalMetadataApplyDispatcher {
+    dispatchMetadataAtomically(workspaceId: string, changes: WorkspaceSyncChange[], options: WorkspaceSyncEngineLocalMetadataApplyOptions): WorkspaceSyncEngineLocalApplyResult;
+}
+export interface WorkspaceSyncEngineLocalPreparedContentApplyDispatcher {
+    dispatchPreparedContentAtomically(workspaceId: string, plan: WorkspaceSyncV2PreparedContentPlan, options: WorkspaceSyncEngineLocalMetadataApplyOptions): WorkspaceSyncEngineLocalApplyResult;
+}
+export interface ApplyWorkspaceSyncLocalBatchInput {
+    workspaceId: string;
+    changes: WorkspaceSyncChange[];
+    allowReferenceNumberReassignment: boolean;
+    workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+    v2ExcludedProjections: readonly WorkspaceSyncV2ProjectionExclusion[];
+}
+export type SyncApplyError = Error & {
+    statusCode?: number;
+    code?: string;
+    details?: {
+        reconciliationRequired?: boolean;
+    };
+};
+export declare const SYNC_V2_CONTENT_STAGING_REQUIRED: "SYNC_V2_CONTENT_STAGING_REQUIRED";
+export declare function assertWorkspaceSyncV2MetadataOnlyApplyPreflight(changes: readonly WorkspaceSyncChange[]): void;
+export declare function applyWorkspaceSyncV2MetadataOnlyBatch(input: ApplyWorkspaceSyncLocalBatchInput, dependencies: {
+    dispatcher: WorkspaceSyncEngineLocalMetadataApplyDispatcher;
+}, transactionHooks?: WorkspaceSyncEngineLocalMetadataApplyTransactionHooks): WorkspaceSyncEngineLocalApplyResult;
+export declare function applyWorkspaceSyncV2PreparedContentBatch(input: Omit<ApplyWorkspaceSyncLocalBatchInput, 'changes'> & {
+    plan: WorkspaceSyncV2PreparedContentPlan;
+}, dependencies: {
+    dispatcher: WorkspaceSyncEngineLocalPreparedContentApplyDispatcher;
+}, transactionHooks?: WorkspaceSyncEngineLocalMetadataApplyTransactionHooks): WorkspaceSyncEngineLocalApplyResult;
+export declare function hydrateWorkspaceSyncV2ManifestChanges(workspaceId: string, changes: readonly WorkspaceSyncChange[], content: WorkspaceSyncEngineLocalContentReader): Promise<WorkspaceSyncChange[]>;
+export declare function applyWorkspaceSyncLocalBatch(input: ApplyWorkspaceSyncLocalBatchInput, dependencies: {
+    content: WorkspaceSyncEngineLocalContentReader;
+    dispatcher: WorkspaceSyncEngineLocalApplyDispatcher;
+    preparedContent?: {
+        prepare(workspaceId: string, changes: readonly WorkspaceSyncChange[]): Promise<WorkspaceSyncV2PreparedContentPlan>;
+        dispatcher: WorkspaceSyncEngineLocalPreparedContentApplyDispatcher;
+        transactionHooks: WorkspaceSyncEngineLocalMetadataApplyTransactionHooks;
+    };
+}): Promise<WorkspaceSyncEngineLocalApplyResult>;

package/dist/sync/engine/workspaceSyncEngineLocalApply.js

@@ -0,0 +1,132 @@
+import { createHash } from 'crypto';
+function syncApplyError(message, code, statusCode, details) {
+    const error = new Error(message);
+    error.code = code;
+    error.statusCode = statusCode;
+    if (details)
+        error.details = details;
+    return error;
+}
+function assertExcludedProjectionsAbsent(changes, exclusions) {
+    const exclusionSet = new Set(exclusions);
+    const excludedChange = changes.find((change) => ((exclusionSet.has('task/root-v1') && change.op === 'delete')
+        || (exclusionSet.has('task-relationship/full-v1')
+            && (change.op === 'task-relationship-upsert' || change.op === 'task-relationship-delete'))
+        || (exclusionSet.has('taxonomy/full-v1') && change.op === 'taxonomy-upsert')
+        || (exclusionSet.has('initiative/full-v1') && change.op === 'initiative-upsert')
+        || (exclusionSet.has('workstream/full-v1') && change.op === 'workstream-upsert')));
+    if (excludedChange) {
+        throw syncApplyError(`Cloud pull returned excluded v2 projection content: ${excludedChange.op}.`, 'SYNC_V2_EXCLUDED_PROJECTION_PRESENT', 409);
+    }
+}
+const CONTENT_BEARING_V2_OPERATIONS = new Set([
+    'document-upsert',
+    'document-delete',
+    'document-manifest',
+    'asset-upsert',
+    'asset-delete',
+    'asset-manifest',
+]);
+export const SYNC_V2_CONTENT_STAGING_REQUIRED = 'SYNC_V2_CONTENT_STAGING_REQUIRED';
+export function assertWorkspaceSyncV2MetadataOnlyApplyPreflight(changes) {
+    const contentChange = changes.find((change) => CONTENT_BEARING_V2_OPERATIONS.has(change.op));
+    if (!contentChange)
+        return;
+    throw syncApplyError(`V2 content change ${contentChange.op} requires staged content reconciliation.`, SYNC_V2_CONTENT_STAGING_REQUIRED, 409, { reconciliationRequired: true });
+}
+export function applyWorkspaceSyncV2MetadataOnlyBatch(input, dependencies, transactionHooks) {
+    assertWorkspaceSyncV2MetadataOnlyApplyPreflight(input.changes);
+    assertExcludedProjectionsAbsent(input.changes, input.v2ExcludedProjections);
+    return dependencies.dispatcher.dispatchMetadataAtomically(input.workspaceId, input.changes, {
+        allowReferenceNumberReassignment: input.allowReferenceNumberReassignment,
+        coexistenceDirection: 'local-pull',
+        v2ExcludedProjections: input.v2ExcludedProjections,
+        ...(input.workspaceMembers ? { workspaceMembers: input.workspaceMembers } : {}),
+        ...(transactionHooks ? { transactionHooks } : {}),
+    });
+}
+export function applyWorkspaceSyncV2PreparedContentBatch(input, dependencies, transactionHooks) {
+    const nonContentChanges = input.plan.changes.flatMap((change) => ('preparedKind' in change ? [] : [change]));
+    assertExcludedProjectionsAbsent(nonContentChanges, input.v2ExcludedProjections);
+    return dependencies.dispatcher.dispatchPreparedContentAtomically(input.workspaceId, input.plan, {
+        allowReferenceNumberReassignment: input.allowReferenceNumberReassignment,
+        coexistenceDirection: 'local-pull',
+        v2ExcludedProjections: input.v2ExcludedProjections,
+        ...(input.workspaceMembers ? { workspaceMembers: input.workspaceMembers } : {}),
+        ...(transactionHooks ? { transactionHooks } : {}),
+    });
+}
+export async function hydrateWorkspaceSyncV2ManifestChanges(workspaceId, changes, content) {
+    const applicableChanges = [];
+    for (const change of changes) {
+        if (change.op !== 'document-manifest' && change.op !== 'asset-manifest') {
+            applicableChanges.push(change);
+            continue;
+        }
+        const manifest = change.manifest;
+        if (manifest.kind !== (change.op === 'document-manifest' ? 'document' : 'asset')
+            || !manifest.path) {
+            throw syncApplyError('Invalid workspace content manifest apply request.', 'INVALID_CONTENT_MANIFEST', 400);
+        }
+        if (change.op === 'document-manifest') {
+            const local = await content.loadDocument(workspaceId, manifest.path);
+            const sha256 = local ? createHash('sha256').update(local.content).digest('hex') : '';
+            const sizeBytes = local ? Buffer.byteLength(local.content, 'utf8') : -1;
+            if (!local || sha256 !== manifest.sha256.toLowerCase() || sizeBytes !== manifest.sizeBytes) {
+                throw syncApplyError(`Local document changed during metadata reconciliation: ${manifest.path}`, 'LOCAL_CONTENT_MANIFEST_MISMATCH', 409);
+            }
+            const { assetId, links, ...metadata } = change.metadata;
+            applicableChanges.push({
+                op: 'document-upsert',
+                path: manifest.path,
+                updatedAt: manifest.updatedAt,
+                content: local.content,
+                ...metadata,
+                ...(typeof assetId === 'string' && assetId ? { assetId } : {}),
+                ...(Array.isArray(links) ? { links } : {}),
+                linkRole: change.metadata.linkRole === 'reference' ? 'reference' : 'attachment',
+            });
+            continue;
+        }
+        const local = await content.loadAsset(workspaceId, manifest.path);
+        const body = local ? Buffer.from(local.contentBase64, 'base64') : null;
+        const sha256 = body ? createHash('sha256').update(body).digest('hex') : '';
+        const sizeBytes = body?.length ?? -1;
+        if (!local || sha256 !== manifest.sha256.toLowerCase() || sizeBytes !== manifest.sizeBytes) {
+            throw syncApplyError(`Local asset changed during metadata reconciliation: ${manifest.path}`, 'LOCAL_CONTENT_MANIFEST_MISMATCH', 409);
+        }
+        const { assetId, assetKind, links, linkRole, ...metadata } = change.metadata;
+        applicableChanges.push({
+            op: 'asset-upsert',
+            path: manifest.path,
+            updatedAt: manifest.updatedAt,
+            contentBase64: local.contentBase64,
+            ...metadata,
+            ...(typeof assetId === 'string' && assetId ? { assetId } : {}),
+            ...(Array.isArray(links) ? { links } : {}),
+            ...(linkRole ? { linkRole } : {}),
+            kind: assetKind === 'image' ? 'image' : 'file',
+            mimeType: change.metadata.mimeType || 'application/octet-stream',
+        });
+    }
+    return applicableChanges;
+}
+export async function applyWorkspaceSyncLocalBatch(input, dependencies) {
+    assertExcludedProjectionsAbsent(input.changes, input.v2ExcludedProjections);
+    const changes = await hydrateWorkspaceSyncV2ManifestChanges(input.workspaceId, input.changes, dependencies.content);
+    if (dependencies.preparedContent) {
+        const plan = await dependencies.preparedContent.prepare(input.workspaceId, changes);
+        return applyWorkspaceSyncV2PreparedContentBatch({
+            ...input,
+            plan,
+        }, {
+            dispatcher: dependencies.preparedContent.dispatcher,
+        }, dependencies.preparedContent.transactionHooks);
+    }
+    return dependencies.dispatcher.dispatch(input.workspaceId, changes, {
+        allowReferenceNumberReassignment: input.allowReferenceNumberReassignment,
+        coexistenceDirection: 'local-pull',
+        v2ExcludedProjections: input.v2ExcludedProjections,
+        ...(input.workspaceMembers ? { workspaceMembers: input.workspaceMembers } : {}),
+    });
+}

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

@@ -0,0 +1,70 @@
+import { applyLocalWorkspaceChanges, applyLocalWorkspaceSyncV3CombinedProjection, applyLocalWorkspaceSyncV3Projection, applyLocalWorkspaceSyncV3TaskCommentAudit, completeLocalSyncAuthoritativeRepair, getLocalTaskMetadataOwnership, getLocalWorkspaceContentManifest, getLocalWorkspaceSyncV3CombinedProjection, getLocalWorkspaceSyncV3Projection, getLocalWorkspaceSyncV3TaskCommentAudit } from '../cloudSyncApi.js';
+import { type LocalOutboxRecoveryPreparation } from '../v3/localOutboxRecoveryClient.js';
+import type { WorkspaceSyncWorkspaceMemberSnapshot } from '../workspaceSyncModel.js';
+import type { WorkspaceSyncV2ProjectionExclusion } from '../v3/workspaceSyncV2ProjectionExclusions.js';
+import type { WorkspaceSyncEngineTransferCompletionGroup } from './workspaceSyncEngineTransferCompletion.js';
+import type { WorkspaceSyncContentPullObligation, WorkspaceSyncContentPullObligationInput, WorkspaceSyncContentPullObligationResolutionClaim } from './workspaceSyncContentPullObligationStore.js';
+export interface WorkspaceSyncEngineV2ApplyOptions {
+    workspaceMembers?: WorkspaceSyncWorkspaceMemberSnapshot[];
+    bootstrapSnapshot?: {
+        currentAnnotatedAttachmentSessionIds?: string[];
+    };
+    repairMode?: boolean;
+    excludedProjections?: readonly WorkspaceSyncV2ProjectionExclusion[];
+    completionGroup?: WorkspaceSyncEngineTransferCompletionGroup;
+    contentPullObligations?: WorkspaceSyncContentPullObligationInput[];
+    contentPullResolutionClaims?: WorkspaceSyncContentPullObligationResolutionClaim[];
+    /**
+     * Server-runner-only settlement that must commit with authoritative push
+     * echoes and their accepted transfer permits. Browser callers never send
+     * this callback across the local HTTP boundary.
+     */
+    commitServerCheckpoint?: () => unknown;
+}
+export interface WorkspaceSyncEngineV3ApplyOptions {
+    completionGroup?: WorkspaceSyncEngineTransferCompletionGroup;
+}
+/**
+ * Local-runtime operations used by the workspace sync engine.
+ *
+ * The browser adapter delegates these operations to same-origin HTTP routes.
+ * A server-owned runner must implement the same semantic operations directly
+ * against the local core and stores rather than issuing requests to localhost.
+ */
+export interface WorkspaceSyncEngineLocalServices {
+    readPushOwnership: typeof getLocalTaskMetadataOwnership;
+    readContentManifest: typeof getLocalWorkspaceContentManifest;
+    applyV2Batch(workspaceId: string, changes: Parameters<typeof applyLocalWorkspaceChanges>[1], options?: WorkspaceSyncEngineV2ApplyOptions): ReturnType<typeof applyLocalWorkspaceChanges>;
+    listContentPullObligations?(workspaceId: string, limit?: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            success?: boolean;
+            obligations?: WorkspaceSyncContentPullObligation[];
+            error?: string;
+        };
+    }>;
+    recordContentPullObligationFailures?(workspaceId: string, obligationIds: readonly string[], error: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            success?: boolean;
+            error?: string;
+        };
+    }>;
+    readInitiativeProjection: typeof getLocalWorkspaceSyncV3Projection;
+    applyInitiativeProjection(workspaceId: string, input: Parameters<typeof applyLocalWorkspaceSyncV3Projection>[1], options?: WorkspaceSyncEngineV3ApplyOptions): ReturnType<typeof applyLocalWorkspaceSyncV3Projection>;
+    readCombinedProjection: typeof getLocalWorkspaceSyncV3CombinedProjection;
+    applyCombinedProjection(workspaceId: string, input: Parameters<typeof applyLocalWorkspaceSyncV3CombinedProjection>[1], coverage?: Parameters<typeof applyLocalWorkspaceSyncV3CombinedProjection>[2], options?: WorkspaceSyncEngineV3ApplyOptions): ReturnType<typeof applyLocalWorkspaceSyncV3CombinedProjection>;
+    readTaskCommentAuditCursor: typeof getLocalWorkspaceSyncV3TaskCommentAudit;
+    applyTaskCommentAuditPage(workspaceId: string, page: Parameters<typeof applyLocalWorkspaceSyncV3TaskCommentAudit>[1], options?: WorkspaceSyncEngineV3ApplyOptions): ReturnType<typeof applyLocalWorkspaceSyncV3TaskCommentAudit>;
+    prepareOutboxRecovery(workspaceId: string): Promise<LocalOutboxRecoveryPreparation>;
+    completeAuthoritativeRepair?(input: Parameters<typeof completeLocalSyncAuthoritativeRepair>[0]): ReturnType<typeof completeLocalSyncAuthoritativeRepair>;
+}
+export interface BrowserWorkspaceSyncEngineLocalServicesOptions {
+    recoveryFetchImpl?: typeof fetch;
+}
+/**
+ * Same-origin HTTP implementation used while the browser owns orchestration.
+ */
+export declare function createBrowserWorkspaceSyncEngineLocalServices(options?: BrowserWorkspaceSyncEngineLocalServicesOptions): WorkspaceSyncEngineLocalServices;