@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/coordinator/localSyncExecutionPermitStore.js

@@ -0,0 +1,1388 @@
+import { randomUUID } from 'crypto';
+import { assertSynchronousTransactionResult, } from '../../storage/databaseAdapter.js';
+import { validateWorkspaceSyncEngineTransferCompletionGroup, } from '../engine/workspaceSyncEngineTransferCompletion.js';
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
+import { LOCAL_SYNC_COORDINATOR_ID } from './localSyncCoordinatorTypes.js';
+import { LocalSyncExecutionPermitError, } from './localSyncExecutionPermitTypes.js';
+const TERMINAL_STATES = [
+    'released',
+    'abandoned-reconcile-required',
+    'abandoned-clean',
+];
+const APPLYING_OPERATION_CLASSES = new Set([
+    'pull',
+    'repair',
+]);
+const NON_APPLYING_OPERATION_CLASSES = new Set([
+    'handshake',
+    'bootstrap',
+    'push',
+]);
+const MAX_DRAIN_INSPECTION_LIMIT = 500;
+export const LOCAL_SYNC_PERMIT_RETENTION_MIN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT = 1_000;
+export const LOCAL_SYNC_PERMIT_RETENTION_DELETE_BATCH = 250;
+export const LOCAL_SYNC_PERMIT_RETENTION_SWEEP_LIMIT = 5_000;
+const LOCAL_SYNC_PERMIT_RETENTION_CHECK_INTERVAL_MS = 60 * 60 * 1000;
+function mapPermit(row) {
+    return {
+        permitId: String(row.permit_id || ''),
+        workspaceId: String(row.workspace_id || ''),
+        coordinatorGeneration: Number(row.coordinator_generation || 0),
+        serverInstanceId: String(row.server_instance_id || ''),
+        ownerMode: row.owner_mode || 'browser-gateway',
+        operationClass: row.operation_class || 'pull',
+        operationIdentity: row.operation_identity || null,
+        lastCommittedCursor: row.last_committed_cursor_json
+            ? JSON.parse(row.last_committed_cursor_json)
+            : null,
+        state: row.state || 'abandoned-reconcile-required',
+        upstreamDisposition: row.upstream_disposition || null,
+        issuedAt: String(row.issued_at || ''),
+        deadlineAt: String(row.deadline_at || ''),
+        lastTransitionAt: String(row.last_transition_at || ''),
+        completedAt: row.completed_at || null,
+        errorCode: row.error_code || null,
+    };
+}
+function mapObligation(row) {
+    return {
+        obligationId: String(row.obligation_id || ''),
+        permitId: String(row.permit_id || ''),
+        workspaceId: String(row.workspace_id || ''),
+        operationClass: row.operation_class || 'pull',
+        operationIdentity: row.operation_identity || null,
+        upstreamDisposition: row.upstream_disposition || 'unknown',
+        lastCommittedCursor: row.last_committed_cursor_json
+            ? JSON.parse(row.last_committed_cursor_json)
+            : null,
+        requiredAction: row.required_action || 'refetch-from-committed-cursor',
+        createdAt: String(row.created_at || ''),
+        resolvedAt: row.resolved_at || null,
+        resolvedBoundary: row.resolved_boundary_json
+            ? JSON.parse(row.resolved_boundary_json)
+            : null,
+    };
+}
+export class LocalSyncExecutionPermitStore {
+    db;
+    now;
+    createId;
+    invariantBlockedWorkspaces = new Set();
+    lastRetentionCheckAtMs = Number.NEGATIVE_INFINITY;
+    constructor(db, now = () => new Date().toISOString(), createId = randomUUID) {
+        this.db = db;
+        this.now = now;
+        this.createId = createId;
+    }
+    issue(input) {
+        return this.issueForOwner('browser-gateway', input);
+    }
+    issueServer(input) {
+        return this.issueForOwner('server', input);
+    }
+    issueForOwner(ownerMode, input) {
+        this.assertNoLocalCommitInvariant(input.workspaceId);
+        this.maybePruneTerminalHistory();
+        return this.db.transaction(() => {
+            if (input.operationIdentity
+                && input.operationClass !== 'push'
+                && input.operationClass !== 'v3-dispatch') {
+                throw new LocalSyncExecutionPermitError(`Execution permits for ${input.operationClass} cannot carry a replay identity.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            const permitId = input.permitId || this.createId();
+            const existing = this.read(permitId);
+            if (existing) {
+                if (existing.workspaceId !== input.workspaceId
+                    || existing.coordinatorGeneration !== input.coordinatorGeneration
+                    || existing.serverInstanceId !== input.serverInstanceId
+                    || existing.ownerMode !== ownerMode
+                    || existing.operationClass !== input.operationClass
+                    || existing.operationIdentity !== (input.operationIdentity || null)
+                    || JSON.stringify(existing.lastCommittedCursor)
+                        !== JSON.stringify(input.lastCommittedCursor ?? null)
+                    || existing.deadlineAt !== input.deadlineAt) {
+                    throw new LocalSyncExecutionPermitError(`Execution permit ${permitId} was reused with different input.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+                }
+                return existing;
+            }
+            const deadlineMs = Date.parse(input.deadlineAt);
+            if (!Number.isFinite(deadlineMs) || deadlineMs <= Date.parse(this.now())) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permitId} has an invalid or expired deadline.`, 'SYNC_COORDINATOR_PERMIT_EXPIRED');
+            }
+            const state = this.db.prepare(`
+                SELECT active_workspace_id, coordinator_generation, ownership_mode, transition_state
+                FROM local_sync_coordinator_state
+                WHERE coordinator_id = ?
+            `).get(LOCAL_SYNC_COORDINATOR_ID);
+            if (!state
+                || Number(state.coordinator_generation || 0) !== input.coordinatorGeneration) {
+                throw new LocalSyncExecutionPermitError('The coordinator generation changed before the execution permit was issued.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            if (String(state.active_workspace_id || '') !== input.workspaceId) {
+                throw new LocalSyncExecutionPermitError(`Workspace ${input.workspaceId} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+            }
+            if (state.ownership_mode !== ownerMode || state.transition_state !== 'idle') {
+                throw new LocalSyncExecutionPermitError(`${ownerMode} execution permits are not available in the current coordinator mode.`, 'SYNC_COORDINATOR_PERMITS_DISABLED');
+            }
+            const at = this.now();
+            this.db.prepare(`
+                INSERT INTO local_sync_execution_permits (
+                    permit_id, workspace_id, coordinator_generation, server_instance_id,
+                    owner_mode, operation_class, operation_identity, state, upstream_disposition,
+                    last_committed_cursor_json, issued_at, deadline_at, last_transition_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, 'issued-idle', 'not-started', ?, ?, ?, ?)
+            `).run(permitId, input.workspaceId, input.coordinatorGeneration, input.serverInstanceId, ownerMode, input.operationClass, input.operationIdentity || null, input.lastCommittedCursor === undefined || input.lastCommittedCursor === null
+                ? null
+                : JSON.stringify(input.lastCommittedCursor), at, input.deadlineAt, at);
+            return this.read(permitId);
+        })();
+    }
+    read(permitId) {
+        const row = this.db.prepare(`
+            SELECT * FROM local_sync_execution_permits WHERE permit_id = ?
+        `).get(permitId);
+        return row ? mapPermit(row) : null;
+    }
+    summarize(workspaceId) {
+        const rows = this.db.prepare(`
+            SELECT state, COUNT(*) AS count
+            FROM local_sync_execution_permits
+            WHERE workspace_id = ?
+              AND state NOT IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+            GROUP BY state
+        `).all(workspaceId);
+        const byState = {};
+        let active = 0;
+        for (const row of rows) {
+            if (!row.state)
+                continue;
+            const count = Number(row.count || 0);
+            byState[row.state] = count;
+            active += count;
+        }
+        const obligation = this.db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM local_sync_recovery_obligations
+            WHERE workspace_id = ? AND resolved_at IS NULL
+        `).get(workspaceId);
+        return {
+            active,
+            byState,
+            recoveryObligations: Number(obligation?.count || 0),
+            localCommitInvariantViolation: this.invariantBlockedWorkspaces.has(workspaceId),
+        };
+    }
+    inspectGenerationDrain(input) {
+        const limit = this.normalizeDrainLimit(input.limit);
+        return this.db.transaction(() => {
+            const rows = this.db.prepare(`
+                SELECT state, COUNT(*) AS count
+                FROM local_sync_execution_permits
+                WHERE workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND state NOT IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+                GROUP BY state
+            `).all(input.workspaceId, input.coordinatorGeneration);
+            const byState = {};
+            let active = 0;
+            for (const row of rows) {
+                if (!row.state)
+                    continue;
+                const count = Number(row.count || 0);
+                byState[row.state] = count;
+                active += count;
+            }
+            const permits = this.db.prepare(`
+                SELECT *
+                FROM local_sync_execution_permits
+                WHERE workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND state NOT IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+                ORDER BY issued_at ASC, permit_id ASC
+                LIMIT ?
+            `).all(input.workspaceId, input.coordinatorGeneration, limit).map(mapPermit);
+            const cleanEligible = this.db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM local_sync_execution_permits
+                WHERE workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND state = 'issued-idle'
+                  AND upstream_disposition = 'not-started'
+            `).get(input.workspaceId, input.coordinatorGeneration);
+            const obligations = this.db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM local_sync_recovery_obligations AS obligation
+                INNER JOIN local_sync_execution_permits AS permit
+                    ON permit.permit_id = obligation.permit_id
+                WHERE permit.workspace_id = ?
+                  AND permit.coordinator_generation = ?
+                  AND obligation.resolved_at IS NULL
+            `).get(input.workspaceId, input.coordinatorGeneration);
+            return {
+                workspaceId: input.workspaceId,
+                coordinatorGeneration: input.coordinatorGeneration,
+                active,
+                byState,
+                permits,
+                truncated: active > permits.length,
+                cleanAbandonEligible: Number(cleanEligible?.count || 0),
+                recoveryObligations: Number(obligations?.count || 0),
+            };
+        })();
+    }
+    abandonNeverStartedForDrain(input) {
+        const limit = this.normalizeDrainLimit(input.limit);
+        return this.db.transaction(() => {
+            const rows = this.db.prepare(`
+                SELECT permit_id
+                FROM local_sync_execution_permits
+                WHERE workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND state = 'issued-idle'
+                  AND upstream_disposition = 'not-started'
+                ORDER BY issued_at ASC, permit_id ASC
+                LIMIT ?
+            `).all(input.workspaceId, input.coordinatorGeneration, limit);
+            const abandonedPermitIds = [];
+            const at = this.now();
+            for (const row of rows) {
+                const permitId = String(row.permit_id || '');
+                if (!permitId)
+                    continue;
+                const result = this.db.prepare(`
+                    UPDATE local_sync_execution_permits
+                    SET state = 'abandoned-clean',
+                        upstream_disposition = 'not-started',
+                        last_transition_at = ?,
+                        completed_at = ?,
+                        error_code = ?
+                    WHERE permit_id = ?
+                      AND workspace_id = ?
+                      AND coordinator_generation = ?
+                      AND state = 'issued-idle'
+                      AND upstream_disposition = 'not-started'
+                `).run(at, at, input.errorCode || 'SYNC_COORDINATOR_PERMIT_DRAINED_NOT_STARTED', permitId, input.workspaceId, input.coordinatorGeneration);
+                if (Number(result?.changes || 0) === 1) {
+                    abandonedPermitIds.push(permitId);
+                }
+            }
+            const remaining = this.db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM local_sync_execution_permits
+                WHERE workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND state = 'issued-idle'
+                  AND upstream_disposition = 'not-started'
+            `).get(input.workspaceId, input.coordinatorGeneration);
+            return {
+                abandonedPermitIds,
+                remainingEligible: Number(remaining?.count || 0),
+            };
+        })();
+    }
+    transition(input) {
+        return this.db.transaction(() => {
+            const current = this.requirePermit(input.permitId);
+            this.assertFence(current, input);
+            if (current.state === input.nextState)
+                return current;
+            if (current.state !== input.expectedState) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is ${current.state}, not ${input.expectedState}.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (input.nextState === 'gateway-in-flight') {
+                this.assertCoordinatorEntryFence(current);
+                if (Date.parse(current.deadlineAt) <= Date.parse(this.now())) {
+                    throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} has expired.`, 'SYNC_COORDINATOR_PERMIT_EXPIRED');
+                }
+            }
+            if (input.nextState === 'local-commit-entered') {
+                this.assertLocalCommitEntryFence(current);
+            }
+            const requestedIdentity = input.operationIdentity ?? current.operationIdentity;
+            if (current.operationIdentity
+                && requestedIdentity
+                && current.operationIdentity !== requestedIdentity) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} operation identity changed.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            const at = this.now();
+            const terminal = TERMINAL_STATES.includes(input.nextState);
+            const upstreamDisposition = input.upstreamDisposition
+                ?? (input.nextState === 'gateway-in-flight' ? 'unknown' : null);
+            const result = this.db.prepare(`
+                UPDATE local_sync_execution_permits
+                SET state = ?,
+                    operation_identity = COALESCE(operation_identity, ?),
+                    upstream_disposition = COALESCE(?, upstream_disposition),
+                    error_code = ?,
+                    last_transition_at = ?,
+                    completed_at = ?
+                WHERE permit_id = ?
+                  AND workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND server_instance_id = ?
+                  AND state = ?
+            `).run(input.nextState, requestedIdentity || null, upstreamDisposition, input.errorCode || null, at, terminal ? at : null, input.permitId, input.workspaceId, input.coordinatorGeneration, input.serverInstanceId, input.expectedState);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} changed before the transition committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            return this.read(input.permitId);
+        })();
+    }
+    release(input) {
+        const current = this.requirePermit(input.permitId);
+        this.assertFence(current, input);
+        if (current.state === 'released')
+            return current;
+        if (current.state === 'abandoned-clean' || current.state === 'abandoned-reconcile-required') {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is already abandoned.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+        }
+        if (current.state === 'gateway-in-flight') {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} still has a gateway request in flight.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+        }
+        if (current.state === 'local-commit-entered') {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is owned by the server local commit.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+        }
+        if (current.state === 'gateway-complete-awaiting-apply'
+            && (!['handshake', 'bootstrap', 'push'].includes(current.operationClass)
+                || current.upstreamDisposition === 'unknown')) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} cannot be released from its current gateway disposition.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+        }
+        return this.transition({
+            ...input,
+            expectedState: current.state,
+            nextState: 'released',
+        });
+    }
+    enterLocalCommit(input) {
+        const current = this.requirePermit(input.permitId);
+        this.assertFence(current, input);
+        if (current.state === 'local-commit-entered')
+            return current;
+        const expectedState = current.operationClass === 'local-apply'
+            ? 'issued-idle'
+            : 'gateway-complete-awaiting-apply';
+        return this.transition({
+            ...input,
+            expectedState,
+            nextState: 'local-commit-entered',
+        });
+    }
+    enterLocalCommitGroup(input) {
+        return this.db.transaction(() => {
+            const permits = this.requireCompletionGroup(input, 'gateway-complete-awaiting-apply');
+            for (const permit of permits) {
+                this.assertLocalCommitEntryFence(permit);
+            }
+            this.persistCompletionGroupTransition(input, 'gateway-complete-awaiting-apply', 'local-commit-entered');
+            return input.permitIds.map((permitId) => this.read(permitId));
+        })();
+    }
+    completeLocalCommit(input) {
+        return this.transition({
+            ...input,
+            expectedState: 'local-commit-entered',
+            nextState: 'released',
+        });
+    }
+    completeLocalCommitGroup(input, beforeRelease) {
+        return this.db.transaction(() => {
+            this.requireCompletionGroup(input, 'local-commit-entered');
+            beforeRelease();
+            this.persistCompletionGroupTransition(input, 'local-commit-entered', 'released');
+            return input.permitIds.map((permitId) => this.read(permitId));
+        })();
+    }
+    acknowledgeNonApplyingCompletion(input) {
+        return this.db.transaction(() => {
+            const current = this.requirePermit(input.permitId);
+            this.assertFence(current, input);
+            if (current.ownerMode !== input.ownerMode) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} belongs to ${current.ownerMode}, not ${input.ownerMode}.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (!NON_APPLYING_OPERATION_CLASSES.has(current.operationClass)) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} requires an atomic local apply.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (current.state !== 'gateway-complete-awaiting-apply'
+                || current.upstreamDisposition !== 'accepted') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} has no accepted non-applying completion to acknowledge.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            return this.transition({
+                permitId: input.permitId,
+                workspaceId: input.workspaceId,
+                coordinatorGeneration: input.coordinatorGeneration,
+                serverInstanceId: input.serverInstanceId,
+                expectedState: 'gateway-complete-awaiting-apply',
+                nextState: 'released',
+            });
+        })();
+    }
+    completeAcceptedV3Dispatch(input, applyAuthoritativeAndAck) {
+        return this.db.transaction(() => {
+            const current = this.requirePermit(input.permitId);
+            this.assertFence(current, input);
+            if (current.ownerMode !== input.ownerMode) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} belongs to ${current.ownerMode}, not ${input.ownerMode}.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (!input.operationIdentity
+                || current.operationIdentity !== input.operationIdentity) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} belongs to a different operation identity.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (current.operationClass !== 'v3-dispatch') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is not a v3 dispatch operation.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (current.state !== 'gateway-complete-awaiting-apply'
+                || current.upstreamDisposition !== 'accepted') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is not an accepted v3 dispatch awaiting authoritative apply.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            this.assertLocalCommitEntryFence(current);
+            this.persistAcceptedV3DispatchTransition(input, 'gateway-complete-awaiting-apply', 'local-commit-entered');
+            const result = applyAuthoritativeAndAck();
+            assertSynchronousTransactionResult(result);
+            this.resolveMatchingV3DispatchRecoveryObligations({
+                workspaceId: input.workspaceId,
+                coordinatorGeneration: input.coordinatorGeneration,
+                ownerMode: input.ownerMode,
+                operationIdentity: input.operationIdentity,
+                resolvedBoundary: {
+                    version: 1,
+                    kind: 'accepted-v3-dispatch',
+                    operationIdentity: input.operationIdentity,
+                },
+            });
+            this.persistAcceptedV3DispatchTransition(input, 'local-commit-entered', 'released');
+            return result;
+        })();
+    }
+    resolveV3DispatchRecoveryObligations(input) {
+        return this.db.transaction(() => {
+            this.assertRecoveryResolutionCoordinatorFence(input);
+            const obligationIds = this.normalizeIdentityGroup(input.resolutions.map((resolution) => resolution.obligationId), 'A v3 dispatch recovery resolution');
+            const resolutions = new Map(input.resolutions.map((resolution) => [
+                resolution.obligationId,
+                resolution,
+            ]));
+            for (const obligationId of obligationIds) {
+                const resolution = resolutions.get(obligationId);
+                const row = this.db.prepare(`
+                    SELECT obligation.*,
+                           permit.workspace_id AS permit_workspace_id,
+                           permit.coordinator_generation AS permit_generation,
+                           permit.operation_class AS permit_operation_class,
+                           permit.operation_identity AS permit_operation_identity
+                    FROM local_sync_recovery_obligations AS obligation
+                    INNER JOIN local_sync_execution_permits AS permit
+                        ON permit.permit_id = obligation.permit_id
+                    WHERE obligation.obligation_id = ?
+                `).get(obligationId);
+                if (!row) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} was not found.`, 'SYNC_COORDINATOR_PERMIT_NOT_FOUND');
+                }
+                const obligation = mapObligation(row);
+                if (obligation.workspaceId !== input.workspaceId
+                    || String(row.permit_workspace_id || '') !== input.workspaceId
+                    || Number(row.permit_generation || 0) > input.coordinatorGeneration) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} belongs to a different workspace or future generation.`, Number(row.permit_generation || 0) > input.coordinatorGeneration
+                        ? 'SYNC_COORDINATOR_STALE_GENERATION'
+                        : 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+                }
+                if (obligation.operationClass !== 'v3-dispatch'
+                    || row.permit_operation_class !== 'v3-dispatch'
+                    || obligation.requiredAction !== 'replay-operation-then-reconcile'
+                    || !resolution.operationIdentity
+                    || obligation.operationIdentity !== resolution.operationIdentity
+                    || row.permit_operation_identity !== resolution.operationIdentity) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} does not match the settled v3 dispatch operation.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+                }
+                const resolvedBoundary = canonicalWorkspaceSyncJson(resolution.resolvedBoundary);
+                if (obligation.resolvedAt) {
+                    if (canonicalWorkspaceSyncJson(obligation.resolvedBoundary)
+                        !== resolvedBoundary) {
+                        throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} was resolved by different evidence.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+                    }
+                    continue;
+                }
+                const result = this.db.prepare(`
+                    UPDATE local_sync_recovery_obligations
+                    SET resolved_at = ?, resolved_boundary_json = ?
+                    WHERE obligation_id = ? AND workspace_id = ?
+                      AND resolved_at IS NULL
+                `).run(this.now(), resolvedBoundary, obligationId, input.workspaceId);
+                if (Number(result?.changes || 0) !== 1) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} changed before v3 dispatch recovery committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+                }
+            }
+            return obligationIds.map((obligationId) => mapObligation(this.db.prepare(`
+                    SELECT *
+                    FROM local_sync_recovery_obligations
+                    WHERE obligation_id = ?
+                `).get(obligationId)));
+        })();
+    }
+    completeAcceptedPushEchoGroup(input, applyAuthoritativeEchoes) {
+        return this.db.transaction(() => {
+            const permits = this.requireAcceptedPushEchoGroup(input);
+            const completionFence = this.snapshotAcceptedPushEchoCompletionFence(input);
+            for (const permit of permits) {
+                this.assertLocalCommitEntryFence(permit);
+            }
+            this.persistAcceptedPushEchoGroupTransition(completionFence, 'gateway-complete-awaiting-apply', 'local-commit-entered');
+            const result = applyAuthoritativeEchoes();
+            assertSynchronousTransactionResult(result);
+            this.resolveAcceptedPushRecoveryObligations(completionFence, permits);
+            this.persistAcceptedPushEchoGroupTransition(completionFence, 'local-commit-entered', 'released');
+            return result;
+        })();
+    }
+    completeAcceptedPushWithoutEcho(input) {
+        return this.db.transaction(() => {
+            const permits = this.requireAcceptedPushEchoGroup(input);
+            const completionFence = this.snapshotAcceptedPushEchoCompletionFence(input);
+            if (permits.length !== 1) {
+                throw new LocalSyncExecutionPermitError('A zero-echo push completion requires exactly one accepted permit.', 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            this.assertLocalCommitEntryFence(permits[0]);
+            this.persistAcceptedPushEchoGroupTransition(completionFence, 'gateway-complete-awaiting-apply', 'local-commit-entered');
+            this.resolveAcceptedPushRecoveryObligations(completionFence, permits);
+            this.persistAcceptedPushEchoGroupTransition(completionFence, 'local-commit-entered', 'released');
+            return this.read(permits[0].permitId);
+        })();
+    }
+    abandonPermit(input) {
+        return this.db.transaction(() => {
+            const current = this.requirePermit(input.permitId);
+            this.assertFence(current, input);
+            if (current.state === 'released'
+                || current.state === 'abandoned-clean'
+                || current.state === 'abandoned-reconcile-required') {
+                return current;
+            }
+            if (current.state === 'gateway-in-flight') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} still has a gateway request in flight.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (current.state === 'local-commit-entered') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is owned by the server local commit.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            const clean = current.state === 'issued-idle'
+                || (current.state === 'gateway-complete-awaiting-apply'
+                    && current.upstreamDisposition === 'rejected');
+            const disposition = current.upstreamDisposition === 'accepted'
+                ? 'accepted'
+                : current.upstreamDisposition === 'rejected'
+                    ? 'rejected'
+                    : current.state === 'issued-idle'
+                        ? 'not-started'
+                        : 'unknown';
+            this.persistAbandon(current, clean ? 'abandoned-clean' : 'abandoned-reconcile-required', disposition, input.errorCode || 'SYNC_COORDINATOR_PERMIT_ABANDONED');
+            if (!clean)
+                this.createRecoveryObligation(current, disposition, input.errorCode || 'SYNC_COORDINATOR_PERMIT_ABANDONED');
+            return this.read(input.permitId);
+        })();
+    }
+    recoverExpiredPermits(input) {
+        return this.db.transaction(() => {
+            const excluded = new Set(input.excludePermitIds || []);
+            const rows = this.db.prepare(`
+                SELECT *
+                FROM local_sync_execution_permits
+                WHERE server_instance_id = ?
+                  AND workspace_id = ?
+                  AND deadline_at <= ?
+                  AND state <> 'local-commit-entered'
+                  AND state NOT IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+                ORDER BY issued_at ASC
+            `).all(input.currentServerInstanceId, input.workspaceId, this.now());
+            let clean = 0;
+            let reconcileRequired = 0;
+            for (const row of rows) {
+                const permit = mapPermit(row);
+                if (excluded.has(permit.permitId))
+                    continue;
+                if (permit.state === 'gateway-in-flight') {
+                    this.persistAbandon(permit, 'abandoned-reconcile-required', 'unknown', 'SYNC_COORDINATOR_PERMIT_EXPIRED');
+                    this.createRecoveryObligation(permit, 'unknown', 'SYNC_COORDINATOR_PERMIT_EXPIRED');
+                    reconcileRequired += 1;
+                    continue;
+                }
+                const result = this.abandonPermit({
+                    permitId: permit.permitId,
+                    workspaceId: permit.workspaceId,
+                    coordinatorGeneration: permit.coordinatorGeneration,
+                    serverInstanceId: permit.serverInstanceId,
+                    errorCode: 'SYNC_COORDINATOR_PERMIT_EXPIRED',
+                });
+                if (result.state === 'abandoned-clean')
+                    clean += 1;
+                if (result.state === 'abandoned-reconcile-required')
+                    reconcileRequired += 1;
+            }
+            return { clean, reconcileRequired };
+        })();
+    }
+    recoverPriorServerPermits(input) {
+        const recovered = this.db.transaction(() => {
+            const params = [input.currentServerInstanceId];
+            let workspaceClause = '';
+            if (input.workspaceId) {
+                workspaceClause = 'AND workspace_id = ?';
+                params.push(input.workspaceId);
+            }
+            const rows = this.db.prepare(`
+                SELECT *
+                FROM local_sync_execution_permits
+                WHERE server_instance_id <> ?
+                  ${workspaceClause}
+                  AND state NOT IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+                ORDER BY issued_at ASC
+            `).all(...params);
+            let clean = 0;
+            let reconcileRequired = 0;
+            let localCommitPending = 0;
+            for (const row of rows) {
+                const permit = mapPermit(row);
+                if (permit.state === 'local-commit-entered') {
+                    this.invariantBlockedWorkspaces.add(permit.workspaceId);
+                    localCommitPending += 1;
+                    continue;
+                }
+                if (permit.state === 'issued-idle') {
+                    this.persistAbandon(permit, 'abandoned-clean', 'not-started', 'SYNC_COORDINATOR_SERVER_RESTARTED');
+                    clean += 1;
+                    continue;
+                }
+                const disposition = permit.upstreamDisposition === 'rejected'
+                    ? 'rejected'
+                    : permit.upstreamDisposition === 'accepted'
+                        ? 'accepted'
+                        : 'unknown';
+                this.persistAbandon(permit, 'abandoned-reconcile-required', disposition, 'SYNC_COORDINATOR_SERVER_RESTARTED');
+                this.createRecoveryObligation(permit, disposition, 'SYNC_COORDINATOR_SERVER_RESTARTED');
+                reconcileRequired += 1;
+            }
+            return { clean, reconcileRequired, localCommitPending };
+        })();
+        this.pruneTerminalHistory();
+        return recovered;
+    }
+    pruneTerminalHistory(deleteLimit = LOCAL_SYNC_PERMIT_RETENTION_DELETE_BATCH) {
+        const nowMs = Date.parse(this.now());
+        if (!Number.isFinite(nowMs))
+            return { permits: 0, obligations: 0 };
+        const boundedDeleteLimit = Math.max(1, Math.min(LOCAL_SYNC_PERMIT_RETENTION_SWEEP_LIMIT, Math.floor(Number(deleteLimit) || 0)));
+        const cutoff = new Date(nowMs - LOCAL_SYNC_PERMIT_RETENTION_MIN_AGE_MS).toISOString();
+        return this.db.transaction(() => {
+            const resolvedObligations = this.db.prepare(`
+                SELECT *
+                FROM local_sync_recovery_obligations
+                WHERE resolved_at IS NOT NULL
+                ORDER BY resolved_at DESC, obligation_id DESC
+            `).all().map(mapObligation);
+            const protectedObligationIds = new Set(resolvedObligations
+                .slice(0, LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT)
+                .map((obligation) => obligation.obligationId));
+            for (const obligation of resolvedObligations) {
+                if (obligation.resolvedAt && obligation.resolvedAt >= cutoff) {
+                    protectedObligationIds.add(obligation.obligationId);
+                }
+            }
+            const obligationCandidates = resolvedObligations
+                .filter((obligation) => (obligation.resolvedAt
+                && obligation.resolvedAt < cutoff
+                && !protectedObligationIds.has(obligation.obligationId)))
+                .reverse()
+                .slice(0, boundedDeleteLimit);
+            const removeObligation = this.db.prepare(`
+                DELETE FROM local_sync_recovery_obligations
+                WHERE obligation_id = ? AND resolved_at IS NOT NULL
+            `);
+            let obligations = 0;
+            for (const obligation of obligationCandidates) {
+                const result = removeObligation.run(obligation.obligationId);
+                obligations += Number(result?.changes || 0);
+            }
+            const terminalPermits = this.db.prepare(`
+                SELECT *
+                FROM local_sync_execution_permits
+                WHERE state IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+                  AND completed_at IS NOT NULL
+                ORDER BY completed_at DESC, permit_id DESC
+            `).all().map(mapPermit);
+            const protectedPermitIds = new Set(terminalPermits
+                .slice(0, LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT)
+                .map((permit) => permit.permitId));
+            for (const permit of terminalPermits) {
+                if (permit.completedAt && permit.completedAt >= cutoff) {
+                    protectedPermitIds.add(permit.permitId);
+                }
+            }
+            const referencedPermitRows = this.db.prepare(`
+                SELECT permit_id
+                FROM local_sync_recovery_obligations
+            `).all();
+            for (const row of referencedPermitRows) {
+                if (row.permit_id)
+                    protectedPermitIds.add(row.permit_id);
+            }
+            const permitCandidates = terminalPermits
+                .filter((permit) => (permit.completedAt
+                && permit.completedAt < cutoff
+                && !protectedPermitIds.has(permit.permitId)))
+                .reverse()
+                .slice(0, boundedDeleteLimit);
+            const removePermit = this.db.prepare(`
+                DELETE FROM local_sync_execution_permits
+                WHERE permit_id = ?
+                  AND state IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+            `);
+            let permits = 0;
+            for (const permit of permitCandidates) {
+                const result = removePermit.run(permit.permitId);
+                permits += Number(result?.changes || 0);
+            }
+            return { permits, obligations };
+        })();
+    }
+    listOpenRecoveryObligations(workspaceId) {
+        return this.db.prepare(`
+            SELECT *
+            FROM local_sync_recovery_obligations
+            WHERE workspace_id = ? AND resolved_at IS NULL
+            ORDER BY created_at ASC
+        `).all(workspaceId).map(mapObligation);
+    }
+    inspectAuthoritativeRepairRecoveryObligations(workspaceId) {
+        const result = this.db.prepare(`
+            SELECT
+                COUNT(*) AS count,
+                SUM(
+                    CASE
+                        WHEN operation_class = 'push'
+                         AND required_action = 'replay-operation-then-reconcile'
+                        THEN 1
+                        ELSE 0
+                    END
+                ) AS push_replay_count
+            FROM local_sync_recovery_obligations
+            WHERE workspace_id = ?
+              AND resolved_at IS NULL
+              AND (
+                  (
+                      operation_class IN ('pull', 'repair')
+                      AND required_action = 'refetch-from-committed-cursor'
+                  )
+                  OR (
+                      operation_class = 'push'
+                      AND required_action = 'replay-operation-then-reconcile'
+                  )
+              )
+        `).get(workspaceId);
+        return {
+            total: Number(result?.count || 0),
+            requiresV2PushReplay: Number(result?.push_replay_count || 0) > 0,
+        };
+    }
+    resolveAuthoritativeRepairRecoveryObligations(input) {
+        return this.db.transaction(() => {
+            const state = this.db.prepare(`
+                SELECT active_workspace_id, coordinator_generation, ownership_mode, transition_state
+                FROM local_sync_coordinator_state
+                WHERE coordinator_id = ?
+            `).get(LOCAL_SYNC_COORDINATOR_ID);
+            if (!state || Number(state.coordinator_generation || 0) !== input.coordinatorGeneration) {
+                throw new LocalSyncExecutionPermitError('The coordinator generation changed before authoritative repair completed.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            if (String(state.active_workspace_id || '') !== input.workspaceId) {
+                throw new LocalSyncExecutionPermitError('Authoritative repair completed for an inactive workspace.', 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+            }
+            if (state.ownership_mode !== input.ownerMode
+                || state.transition_state !== 'idle') {
+                throw new LocalSyncExecutionPermitError('Authoritative repair cannot settle recovery during an ownership transition.', 'SYNC_COORDINATOR_PERMITS_DISABLED');
+            }
+            const activePermit = this.db.prepare(`
+                SELECT permit_id
+                FROM local_sync_execution_permits
+                WHERE workspace_id = ?
+                  AND state NOT IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+                LIMIT 1
+            `).get(input.workspaceId);
+            if (activePermit?.permit_id) {
+                throw new LocalSyncExecutionPermitError('Authoritative repair cannot settle recovery while execution permits are active.', 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            const unresolvedDispatch = this.db.prepare(`
+                SELECT obligation_id
+                FROM local_sync_recovery_obligations
+                WHERE workspace_id = ?
+                  AND resolved_at IS NULL
+                  AND operation_class = 'v3-dispatch'
+                LIMIT 1
+            `).get(input.workspaceId);
+            if (unresolvedDispatch?.obligation_id) {
+                throw new LocalSyncExecutionPermitError('Authoritative repair cannot supersede unresolved durable dispatch recovery.', 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            const resolvedAt = this.now();
+            const resolvedBoundary = canonicalWorkspaceSyncJson({
+                version: 1,
+                kind: 'authoritative-repair',
+                repairId: input.repairId,
+                stateSignatureSha256: input.stateSignatureSha256,
+                coordinatorGeneration: input.coordinatorGeneration,
+                completedAt: resolvedAt,
+            });
+            const result = this.db.prepare(`
+                UPDATE local_sync_recovery_obligations
+                SET resolved_at = ?,
+                    resolved_boundary_json = ?
+                WHERE workspace_id = ?
+                  AND resolved_at IS NULL
+                  AND permit_id IN (
+                      SELECT permit_id
+                      FROM local_sync_execution_permits
+                      WHERE workspace_id = ?
+                        AND coordinator_generation <= ?
+                        AND (
+                            (
+                                operation_class IN ('pull', 'repair')
+                                AND local_sync_recovery_obligations.required_action =
+                                    'refetch-from-committed-cursor'
+                            )
+                            OR (
+                                operation_class = 'push'
+                                AND local_sync_recovery_obligations.required_action =
+                                    'replay-operation-then-reconcile'
+                            )
+                        )
+                  )
+            `).run(resolvedAt, resolvedBoundary, input.workspaceId, input.workspaceId, input.coordinatorGeneration);
+            const remaining = this.db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM local_sync_recovery_obligations
+                WHERE workspace_id = ? AND resolved_at IS NULL
+            `).get(input.workspaceId);
+            return {
+                resolved: Number(result?.changes || 0),
+                remaining: Number(remaining?.count || 0),
+            };
+        })();
+    }
+    listResolvableRecoveryObligations(completionGroup) {
+        validateWorkspaceSyncEngineTransferCompletionGroup(completionGroup);
+        this.assertRecoveryResolutionCoordinatorFence(completionGroup);
+        const completionPermits = this.requireCompletionGroup(completionGroup, 'local-commit-entered');
+        const operationClasses = new Set(completionPermits.map((permit) => permit.operationClass));
+        if (operationClasses.size !== 1)
+            return [];
+        const [operationClass] = [...operationClasses];
+        const previousBoundary = canonicalWorkspaceSyncJson(completionGroup.previousBoundary);
+        return this.db.prepare(`
+            SELECT obligation.*
+            FROM local_sync_recovery_obligations AS obligation
+            INNER JOIN local_sync_execution_permits AS permit
+                ON permit.permit_id = obligation.permit_id
+            WHERE obligation.workspace_id = ?
+              AND obligation.resolved_at IS NULL
+              AND obligation.required_action = 'refetch-from-committed-cursor'
+              AND obligation.operation_class = ?
+              AND permit.workspace_id = ?
+              AND permit.coordinator_generation <= ?
+              AND permit.operation_class = ?
+            ORDER BY obligation.created_at ASC, obligation.obligation_id ASC
+        `).all(completionGroup.workspaceId, operationClass, completionGroup.workspaceId, completionGroup.coordinatorGeneration, operationClass).filter((row) => (canonicalWorkspaceSyncJson(mapObligation(row).lastCommittedCursor)
+            === previousBoundary)).map(mapObligation);
+    }
+    resolveRecoveryObligations(input, commitBoundary) {
+        return this.db.transaction(() => {
+            validateWorkspaceSyncEngineTransferCompletionGroup(input.completionGroup);
+            const obligationIds = this.normalizeIdentityGroup(input.obligationIds, 'A recovery obligation resolution');
+            const completionGroup = input.completionGroup;
+            this.assertRecoveryResolutionCoordinatorFence(completionGroup);
+            const completionPermits = this.requireCompletionGroup(completionGroup, 'local-commit-entered');
+            const obligations = obligationIds.map((obligationId) => {
+                const row = this.db.prepare(`
+                    SELECT obligation.*,
+                           permit.workspace_id AS permit_workspace_id,
+                           permit.coordinator_generation AS permit_generation,
+                           permit.operation_class AS permit_operation_class,
+                           permit.last_committed_cursor_json AS permit_last_committed_cursor_json
+                    FROM local_sync_recovery_obligations AS obligation
+                    INNER JOIN local_sync_execution_permits AS permit
+                        ON permit.permit_id = obligation.permit_id
+                    WHERE obligation.obligation_id = ?
+                `).get(obligationId);
+                if (!row) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} was not found.`, 'SYNC_COORDINATOR_PERMIT_NOT_FOUND');
+                }
+                if (String(row.workspace_id || '') !== completionGroup.workspaceId
+                    || String(row.permit_workspace_id || '') !== completionGroup.workspaceId
+                    || Number(row.permit_generation || 0)
+                        > completionGroup.coordinatorGeneration) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} belongs to a different workspace or future generation.`, String(row.workspace_id || '') === completionGroup.workspaceId
+                        && String(row.permit_workspace_id || '')
+                            === completionGroup.workspaceId
+                        ? Number(row.permit_generation || 0)
+                            > completionGroup.coordinatorGeneration
+                            ? 'SYNC_COORDINATOR_STALE_GENERATION'
+                            : 'SYNC_COORDINATOR_INACTIVE_WORKSPACE'
+                        : 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+                }
+                const obligation = mapObligation(row);
+                const originBoundary = row.permit_last_committed_cursor_json
+                    ? JSON.parse(row.permit_last_committed_cursor_json)
+                    : null;
+                if (obligation.requiredAction !== 'refetch-from-committed-cursor') {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} requires operation replay before reconciliation.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+                }
+                if (row.permit_operation_class !== obligation.operationClass
+                    || completionPermits.some((permit) => (permit.operationClass !== obligation.operationClass))) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} does not match the completion group's operation class.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+                }
+                if (canonicalWorkspaceSyncJson(obligation.lastCommittedCursor)
+                    !== canonicalWorkspaceSyncJson(completionGroup.previousBoundary)
+                    || canonicalWorkspaceSyncJson(originBoundary)
+                        !== canonicalWorkspaceSyncJson(completionGroup.previousBoundary)) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligationId} does not start at the resolved boundary.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+                }
+                return obligation;
+            });
+            const openObligations = obligations.filter((obligation) => !obligation.resolvedAt);
+            if (obligations.some((obligation) => (obligation.resolvedAt
+                && (canonicalWorkspaceSyncJson(obligation.resolvedBoundary)
+                    !== canonicalWorkspaceSyncJson(completionGroup.expectedBoundary))))) {
+                throw new LocalSyncExecutionPermitError('The resolved recovery boundary does not match this replay.', 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (openObligations.length === 0)
+                return obligations;
+            const committedBoundary = commitBoundary({
+                previousBoundary: JSON.parse(canonicalWorkspaceSyncJson(completionGroup.previousBoundary)),
+                expectedBoundary: JSON.parse(canonicalWorkspaceSyncJson(completionGroup.expectedBoundary)),
+            });
+            if (canonicalWorkspaceSyncJson(committedBoundary)
+                !== canonicalWorkspaceSyncJson(completionGroup.expectedBoundary)) {
+                throw new LocalSyncExecutionPermitError('The committed recovery boundary does not match the expected boundary.', 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            const at = this.now();
+            const resolve = this.db.prepare(`
+                UPDATE local_sync_recovery_obligations
+                SET resolved_at = ?,
+                    resolved_boundary_json = ?
+                WHERE obligation_id = ?
+                  AND workspace_id = ?
+                  AND resolved_at IS NULL
+            `);
+            for (const obligation of openObligations) {
+                const result = resolve.run(at, canonicalWorkspaceSyncJson(completionGroup.expectedBoundary), obligation.obligationId, completionGroup.workspaceId);
+                if (Number(result?.changes || 0) !== 1) {
+                    throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligation.obligationId} changed before resolution committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+                }
+            }
+            return obligationIds.map((obligationId) => mapObligation(this.db.prepare(`
+                    SELECT *
+                    FROM local_sync_recovery_obligations
+                    WHERE obligation_id = ?
+                `).get(obligationId)));
+        })();
+    }
+    requirePermit(permitId) {
+        const permit = this.read(permitId);
+        if (!permit) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permitId} was not found.`, 'SYNC_COORDINATOR_PERMIT_NOT_FOUND');
+        }
+        return permit;
+    }
+    assertFence(permit, input) {
+        if (permit.serverInstanceId !== input.serverInstanceId) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to a different server instance.`, 'SYNC_COORDINATOR_PERMIT_SERVER_MISMATCH');
+        }
+        if (permit.coordinatorGeneration !== input.coordinatorGeneration) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to a stale coordinator generation.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        if (permit.workspaceId !== input.workspaceId) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to a different workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+        }
+    }
+    assertCoordinatorEntryFence(permit) {
+        const state = this.db.prepare(`
+            SELECT active_workspace_id, coordinator_generation, ownership_mode, transition_state
+            FROM local_sync_coordinator_state
+            WHERE coordinator_id = ?
+        `).get(LOCAL_SYNC_COORDINATOR_ID);
+        if (!state || Number(state.coordinator_generation || 0) !== permit.coordinatorGeneration) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to a stale coordinator generation.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        if (String(state.active_workspace_id || '') !== permit.workspaceId) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to an inactive workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+        }
+        if (state.ownership_mode !== permit.ownerMode || state.transition_state !== 'idle') {
+            throw new LocalSyncExecutionPermitError(`${permit.ownerMode} execution permits cannot enter work during an ownership transition.`, 'SYNC_COORDINATOR_PERMITS_DISABLED');
+        }
+    }
+    assertLocalCommitEntryFence(permit) {
+        const state = this.db.prepare(`
+            SELECT active_workspace_id, coordinator_generation, ownership_mode,
+                   transition_state, transfer_target_mode, transfer_phase
+            FROM local_sync_coordinator_state
+            WHERE coordinator_id = ?
+        `).get(LOCAL_SYNC_COORDINATOR_ID);
+        if (!state || String(state.active_workspace_id || '') !== permit.workspaceId) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to an inactive workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+        }
+        const stateGeneration = Number(state.coordinator_generation || 0);
+        const steadySourceOwner = (stateGeneration === permit.coordinatorGeneration
+            && state.ownership_mode === permit.ownerMode
+            && state.transition_state === 'idle');
+        const targetMode = permit.ownerMode === 'browser-gateway'
+            ? 'server'
+            : 'browser-gateway';
+        const transitionMode = permit.ownerMode === 'browser-gateway'
+            ? 'transitioning-to-server'
+            : 'transitioning-to-browser';
+        const drainingSourceOwner = (stateGeneration === permit.coordinatorGeneration
+            && state.ownership_mode === transitionMode
+            && state.transition_state === 'transferring-ownership'
+            && state.transfer_target_mode === targetMode
+            && (state.transfer_phase === 'preparing' || state.transfer_phase === 'draining'));
+        if (!steadySourceOwner && !drainingSourceOwner) {
+            throw new LocalSyncExecutionPermitError(`The permit cannot enter local commit outside its ${permit.ownerMode} drain window.`, stateGeneration === permit.coordinatorGeneration
+                ? 'SYNC_COORDINATOR_PERMITS_DISABLED'
+                : 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        if (Date.parse(permit.deadlineAt) <= Date.parse(this.now())) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} has expired.`, 'SYNC_COORDINATOR_PERMIT_EXPIRED');
+        }
+    }
+    requireCompletionGroup(input, expectedState) {
+        const normalizedIds = this.normalizeIdentityGroup(input.permitIds, 'A local commit completion group');
+        const permits = normalizedIds.map((permitId) => this.requirePermit(permitId));
+        for (const permit of permits) {
+            this.assertFence(permit, input);
+            if (permit.ownerMode !== input.ownerMode) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to ${permit.ownerMode}, not ${input.ownerMode}.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (!APPLYING_OPERATION_CLASSES.has(permit.operationClass)) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} is not an applying operation.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (canonicalWorkspaceSyncJson(permit.lastCommittedCursor)
+                !== canonicalWorkspaceSyncJson(input.previousBoundary)) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} does not start at the completion group's previous boundary.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (permit.state !== expectedState
+                || permit.upstreamDisposition !== 'accepted') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} is not an accepted ${expectedState} permit.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+        }
+        return permits;
+    }
+    snapshotAcceptedPushEchoCompletionFence(input) {
+        const pushBoundary = JSON.parse(canonicalWorkspaceSyncJson(input.pushBoundary));
+        return Object.freeze({
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+            ownerMode: input.ownerMode,
+            serverInstanceId: input.serverInstanceId,
+            permitIds: Object.freeze([...input.permitIds]),
+            pushBoundary: Object.freeze({
+                ...pushBoundary,
+                batchOperationIdentities: Object.freeze([
+                    ...pushBoundary.batchOperationIdentities,
+                ]),
+            }),
+        });
+    }
+    requireAcceptedPushEchoGroup(input) {
+        const normalizedIds = this.normalizeIdentityGroup(input.permitIds, 'An accepted push echo completion group');
+        const pushBoundary = input.pushBoundary;
+        const batchOperationIdentities = Array.isArray(pushBoundary?.batchOperationIdentities)
+            ? pushBoundary.batchOperationIdentities
+            : [];
+        if (!pushBoundary
+            || pushBoundary.version !== 1
+            || pushBoundary.projection !== 'v2-push'
+            || batchOperationIdentities.length === 0
+            || batchOperationIdentities.some((operationIdentity, index) => (typeof operationIdentity !== 'string'
+                || !operationIdentity
+                || operationIdentity !== operationIdentity.trim()
+                || batchOperationIdentities.indexOf(operationIdentity) !== index))
+            || Object.keys(pushBoundary).length !== 3) {
+            throw new LocalSyncExecutionPermitError('An accepted push echo completion group requires an exact V2 push boundary.', 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+        }
+        const canonicalPushBoundary = canonicalWorkspaceSyncJson(pushBoundary);
+        const permits = normalizedIds.map((permitId) => this.requirePermit(permitId));
+        const permitOperationIdentities = new Set();
+        for (const permit of permits) {
+            this.assertFence(permit, input);
+            if (permit.ownerMode !== input.ownerMode) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to ${permit.ownerMode}, not ${input.ownerMode}.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (permit.operationClass !== 'push') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} is not a push operation.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            if (!permit.operationIdentity?.trim()) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} has no stable push operation identity.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (permit.operationIdentity !== permit.operationIdentity.trim()
+                || permitOperationIdentities.has(permit.operationIdentity)
+                || !batchOperationIdentities.includes(permit.operationIdentity)) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} does not have a unique identity in the push attempt boundary.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            permitOperationIdentities.add(permit.operationIdentity);
+            if (canonicalWorkspaceSyncJson(permit.lastCommittedCursor)
+                !== canonicalPushBoundary) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} belongs to a different push attempt boundary.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (permit.state !== 'gateway-complete-awaiting-apply'
+                || permit.upstreamDisposition !== 'accepted') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permit.permitId} is not an accepted push awaiting authoritative echo apply.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+        }
+        return permits;
+    }
+    normalizeIdentityGroup(ids, label) {
+        if (!Array.isArray(ids) || ids.length === 0) {
+            throw new LocalSyncExecutionPermitError(`${label} requires at least one ID.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+        }
+        const normalizedIds = ids.map((id) => id.trim());
+        if (normalizedIds.some((id, index) => !id || id !== ids[index])
+            || new Set(normalizedIds).size !== normalizedIds.length) {
+            throw new LocalSyncExecutionPermitError(`${label} contains invalid or duplicate IDs.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+        }
+        return normalizedIds;
+    }
+    assertRecoveryResolutionCoordinatorFence(input) {
+        const state = this.db.prepare(`
+            SELECT active_workspace_id, coordinator_generation,
+                   ownership_mode, transition_state
+            FROM local_sync_coordinator_state
+            WHERE coordinator_id = ?
+        `).get(LOCAL_SYNC_COORDINATOR_ID);
+        if (!state || Number(state.coordinator_generation || 0) !== input.coordinatorGeneration) {
+            throw new LocalSyncExecutionPermitError('The coordinator generation changed before recovery obligations were resolved.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        if (String(state.active_workspace_id || '') !== input.workspaceId) {
+            throw new LocalSyncExecutionPermitError(`Workspace ${input.workspaceId} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+        }
+        if (state.ownership_mode !== input.ownerMode || state.transition_state !== 'idle') {
+            throw new LocalSyncExecutionPermitError('Recovery obligations can resolve only for the steady-state coordinator owner.', 'SYNC_COORDINATOR_PERMITS_DISABLED');
+        }
+    }
+    persistCompletionGroupTransition(input, expectedState, nextState) {
+        const at = this.now();
+        const update = this.db.prepare(`
+            UPDATE local_sync_execution_permits
+            SET state = ?,
+                error_code = NULL,
+                last_transition_at = ?,
+                completed_at = ?
+            WHERE permit_id = ?
+              AND workspace_id = ?
+              AND coordinator_generation = ?
+              AND server_instance_id = ?
+              AND owner_mode = ?
+              AND state = ?
+              AND upstream_disposition = 'accepted'
+        `);
+        for (const permitId of input.permitIds) {
+            const result = update.run(nextState, at, nextState === 'released' ? at : null, permitId, input.workspaceId, input.coordinatorGeneration, input.serverInstanceId, input.ownerMode, expectedState);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permitId} changed before the completion group committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+        }
+    }
+    persistAcceptedV3DispatchTransition(input, expectedState, nextState) {
+        const at = this.now();
+        const result = this.db.prepare(`
+            UPDATE local_sync_execution_permits
+            SET state = ?,
+                error_code = NULL,
+                last_transition_at = ?,
+                completed_at = ?
+            WHERE permit_id = ?
+              AND workspace_id = ?
+              AND coordinator_generation = ?
+              AND server_instance_id = ?
+              AND owner_mode = ?
+              AND operation_class = 'v3-dispatch'
+              AND operation_identity = ?
+              AND state = ?
+              AND upstream_disposition = 'accepted'
+        `).run(nextState, at, nextState === 'released' ? at : null, input.permitId, input.workspaceId, input.coordinatorGeneration, input.serverInstanceId, input.ownerMode, input.operationIdentity, expectedState);
+        if (Number(result?.changes || 0) !== 1) {
+            throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} changed before the v3 dispatch completion committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+        }
+    }
+    persistAcceptedPushEchoGroupTransition(input, expectedState, nextState) {
+        const at = this.now();
+        const update = this.db.prepare(`
+            UPDATE local_sync_execution_permits
+            SET state = ?,
+                error_code = NULL,
+                last_transition_at = ?,
+                completed_at = ?
+            WHERE permit_id = ?
+              AND workspace_id = ?
+              AND coordinator_generation = ?
+              AND server_instance_id = ?
+              AND owner_mode = ?
+              AND operation_class = 'push'
+              AND operation_identity IS NOT NULL
+              AND operation_identity <> ''
+              AND state = ?
+              AND upstream_disposition = 'accepted'
+        `);
+        for (const permitId of input.permitIds) {
+            const result = update.run(nextState, at, nextState === 'released' ? at : null, permitId, input.workspaceId, input.coordinatorGeneration, input.serverInstanceId, input.ownerMode, expectedState);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${permitId} changed before the push echo completion committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+        }
+    }
+    resolveAcceptedPushRecoveryObligations(input, permits) {
+        const operationIdentities = new Set(permits.map((permit) => permit.operationIdentity).filter((identity) => Boolean(identity)));
+        const canonicalBoundary = canonicalWorkspaceSyncJson(input.pushBoundary);
+        const obligations = this.db.prepare(`
+            SELECT obligation.*,
+                   permit.operation_identity AS permit_operation_identity,
+                   permit.last_committed_cursor_json AS permit_last_committed_cursor_json
+            FROM local_sync_recovery_obligations AS obligation
+            INNER JOIN local_sync_execution_permits AS permit
+                ON permit.permit_id = obligation.permit_id
+            WHERE obligation.workspace_id = ?
+              AND obligation.resolved_at IS NULL
+              AND obligation.operation_class = 'push'
+              AND obligation.required_action = 'replay-operation-then-reconcile'
+              AND permit.workspace_id = ?
+              AND permit.coordinator_generation <= ?
+              AND permit.operation_class = 'push'
+            ORDER BY obligation.created_at ASC, obligation.obligation_id ASC
+        `).all(input.workspaceId, input.workspaceId, input.coordinatorGeneration).filter((row) => {
+            const obligation = mapObligation(row);
+            const originOperationIdentity = String(row.permit_operation_identity || '');
+            return (Boolean(obligation.operationIdentity)
+                && obligation.operationIdentity === originOperationIdentity
+                && operationIdentities.has(obligation.operationIdentity)
+                && canonicalWorkspaceSyncJson(row.permit_last_committed_cursor_json
+                    ? JSON.parse(row.permit_last_committed_cursor_json)
+                    : null) === canonicalBoundary
+                && canonicalWorkspaceSyncJson(obligation.lastCommittedCursor) === canonicalBoundary);
+        });
+        if (obligations.length === 0)
+            return;
+        const at = this.now();
+        const update = this.db.prepare(`
+            UPDATE local_sync_recovery_obligations
+            SET resolved_at = ?,
+                resolved_boundary_json = ?
+            WHERE obligation_id = ?
+              AND workspace_id = ?
+              AND resolved_at IS NULL
+              AND operation_class = 'push'
+              AND operation_identity = ?
+              AND required_action = 'replay-operation-then-reconcile'
+              AND (
+                    last_committed_cursor_json = ?
+                    OR (
+                        last_committed_cursor_json IS NULL
+                        AND ? IS NULL
+                    )
+              )
+        `);
+        for (const obligation of obligations) {
+            const result = update.run(at, canonicalBoundary, obligation.obligation_id, input.workspaceId, obligation.operation_identity, obligation.last_committed_cursor_json || null, obligation.last_committed_cursor_json || null);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncExecutionPermitError(`Recovery obligation ${obligation.obligation_id} changed before push replay committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+        }
+    }
+    resolveMatchingV3DispatchRecoveryObligations(input) {
+        const rows = this.db.prepare(`
+            SELECT obligation_id
+            FROM local_sync_recovery_obligations
+            WHERE workspace_id = ? AND resolved_at IS NULL
+              AND operation_class = 'v3-dispatch'
+              AND operation_identity = ?
+              AND required_action = 'replay-operation-then-reconcile'
+            ORDER BY created_at, obligation_id
+        `).all(input.workspaceId, input.operationIdentity);
+        if (rows.length === 0)
+            return;
+        this.resolveV3DispatchRecoveryObligations({
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+            ownerMode: input.ownerMode,
+            resolutions: rows.map((row) => ({
+                obligationId: String(row.obligation_id || ''),
+                operationIdentity: input.operationIdentity,
+                resolvedBoundary: input.resolvedBoundary,
+            })),
+        });
+    }
+    normalizeDrainLimit(limit) {
+        const resolved = limit ?? 100;
+        if (!Number.isSafeInteger(resolved)
+            || resolved < 1
+            || resolved > MAX_DRAIN_INSPECTION_LIMIT) {
+            throw new RangeError(`Permit drain limit must be an integer between 1 and ${MAX_DRAIN_INSPECTION_LIMIT}.`);
+        }
+        return resolved;
+    }
+    assertNoLocalCommitInvariant(workspaceId) {
+        if (!this.invariantBlockedWorkspaces.has(workspaceId))
+            return;
+        throw new LocalSyncExecutionPermitError('Cloud sync is blocked because a prior server left a local commit in an impossible intermediate state.', 'SYNC_COORDINATOR_LOCAL_COMMIT_INVARIANT');
+    }
+    maybePruneTerminalHistory() {
+        const nowMs = Date.parse(this.now());
+        if (!Number.isFinite(nowMs)
+            || nowMs - this.lastRetentionCheckAtMs
+                < LOCAL_SYNC_PERMIT_RETENTION_CHECK_INTERVAL_MS) {
+            return;
+        }
+        this.lastRetentionCheckAtMs = nowMs;
+        this.pruneTerminalHistory(LOCAL_SYNC_PERMIT_RETENTION_SWEEP_LIMIT);
+    }
+    persistAbandon(permit, state, disposition, errorCode) {
+        const at = this.now();
+        this.db.prepare(`
+            UPDATE local_sync_execution_permits
+            SET state = ?, upstream_disposition = ?, last_transition_at = ?,
+                completed_at = ?, error_code = ?
+            WHERE permit_id = ? AND state = ?
+        `).run(state, disposition, at, at, errorCode, permit.permitId, permit.state);
+    }
+    createRecoveryObligation(permit, disposition, errorCode) {
+        const mutationReplay = (permit.operationClass === 'push'
+            || permit.operationClass === 'v3-dispatch') && Boolean(permit.operationIdentity);
+        const requiredAction = mutationReplay
+            ? 'replay-operation-then-reconcile'
+            : 'refetch-from-committed-cursor';
+        const coalescesRepeatedApplyFailure = errorCode === 'WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED'
+            || errorCode === 'WORKSPACE_SYNC_V3_ATTACHMENT_HYDRATION_NOT_COMMITTED';
+        if (coalescesRepeatedApplyFailure) {
+            const committedBoundary = canonicalWorkspaceSyncJson(permit.lastCommittedCursor);
+            const equivalentOpenObligation = this.db.prepare(`
+                SELECT obligation.*
+                FROM local_sync_recovery_obligations AS obligation
+                INNER JOIN local_sync_execution_permits AS origin
+                    ON origin.permit_id = obligation.permit_id
+                WHERE obligation.workspace_id = ?
+                  AND obligation.operation_class = ?
+                  AND obligation.upstream_disposition = ?
+                  AND obligation.required_action = ?
+                  AND obligation.resolved_at IS NULL
+                  AND origin.error_code = ?
+                ORDER BY obligation.created_at ASC
+            `).all(permit.workspaceId, permit.operationClass, disposition, requiredAction, errorCode).map(mapObligation).some((obligation) => ((obligation.operationIdentity || null) === (permit.operationIdentity || null)
+                && canonicalWorkspaceSyncJson(obligation.lastCommittedCursor) === committedBoundary));
+            if (equivalentOpenObligation)
+                return;
+        }
+        this.db.prepare(`
+            INSERT INTO local_sync_recovery_obligations (
+                obligation_id, permit_id, workspace_id, operation_class,
+                operation_identity, upstream_disposition, last_committed_cursor_json,
+                required_action, created_at, resolved_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+            ON CONFLICT (permit_id) DO NOTHING
+        `).run(this.createId(), permit.permitId, permit.workspaceId, permit.operationClass, permit.operationIdentity, disposition, permit.lastCommittedCursor === null
+            ? null
+            : JSON.stringify(permit.lastCommittedCursor), requiredAction, this.now());
+    }
+}