@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/coordinator/localWorkspaceSyncRunnerState.js

@@ -0,0 +1,961 @@
+import { fingerprintWorkspaceSyncPayload, } from '../v3/syncDurabilityStore.js';
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
+import { WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS, } from '../v3/workspaceSyncV2ProjectionExclusions.js';
+import { WORKSPACE_PUSH_PREPARED_PLAN_VERSION, } from '../workspacePushPreparedPlan.js';
+import { LOCAL_SYNC_COORDINATOR_ID } from './localSyncCoordinatorTypes.js';
+export const LOCAL_WORKSPACE_SYNC_RUNNER_STATE_VERSION = 1;
+export const LOCAL_WORKSPACE_SYNC_PAYLOAD_CODEC_VERSION = 1;
+export const LOCAL_WORKSPACE_SYNC_MAX_PUSHES_WHILE_PULL_DUE = 3;
+export const LOCAL_WORKSPACE_SYNC_MAX_REMOTE_HINT_AGE_MS = 30_000;
+export const LOCAL_WORKSPACE_SYNC_MAX_PUSH_BOUNDARY_MS = 25_000;
+export function isLocalWorkspaceSyncPullFairnessDue(checkpoint, now) {
+    if (!checkpoint.remoteHintObservedAt)
+        return false;
+    return checkpoint.consecutivePushesWhilePullDue
+        >= LOCAL_WORKSPACE_SYNC_MAX_PUSHES_WHILE_PULL_DUE
+        || Date.parse(now) - Date.parse(checkpoint.remoteHintObservedAt)
+            >= LOCAL_WORKSPACE_SYNC_MAX_REMOTE_HINT_AGE_MS
+                - LOCAL_WORKSPACE_SYNC_MAX_PUSH_BOUNDARY_MS;
+}
+export class LocalWorkspaceSyncRunnerStateError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalWorkspaceSyncRunnerStateError';
+    }
+}
+const CONTROL_STATES = new Set([
+    'idle', 'starting', 'pulling', 'pushing', 'repairing', 'retry-wait', 'stopping', 'error',
+]);
+const SYNC_PHASES = new Set([
+    'idle', 'provision-local', 'attach-cloud', 'active', 'error',
+]);
+const RETRY_KINDS = new Set([
+    'bootstrap', 'handshake', 'pull', 'push', 'v2-content-push', 'repair', 'v3-dispatch',
+]);
+const REPAIR_KINDS = new Set([
+    'v2-reconcile', 'v3-combined', 'v3-initiative', 'final-push', 'settlement',
+]);
+const REPAIR_EXCLUDED_PROJECTIONS = new Set(WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function isNonEmptyText(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isNullableText(value) {
+    return value === null || typeof value === 'string';
+}
+function isTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const epochMs = Date.parse(value);
+    return Number.isFinite(epochMs) && new Date(epochMs).toISOString() === value;
+}
+function isNullableTimestamp(value) {
+    return value === null || isTimestamp(value);
+}
+function isNonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function isJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    if (!isRecord(value))
+        return false;
+    return Object.values(value).every(isJson);
+}
+function isStringArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => typeof entry === 'string')
+        && new Set(value).size === value.length;
+}
+function isStringPairArray(value) {
+    return Array.isArray(value) && value.every((entry) => (Array.isArray(entry)
+        && entry.length === 2
+        && typeof entry[0] === 'string'
+        && typeof entry[1] === 'string')) && new Set(value.map((entry) => entry[0])).size === value.length;
+}
+const ENCODED_PAYLOAD_REQUIRED_KEYS = [
+    'codecVersion',
+    'changes',
+    'currentTaskIds',
+    'deleteTaskIds',
+    'currentInitiativeIds',
+    'currentInitiativeWatermarks',
+    'currentWorkstreamIds',
+    'currentWorkstreamWatermarks',
+    'currentAiProfileIds',
+    'currentAiProfileWatermarks',
+    'currentDocumentPaths',
+    'deleteDocumentPaths',
+    'currentDocumentWatermarks',
+    'currentAssetPaths',
+    'deleteAssetPaths',
+    'currentAssetWatermarks',
+    'currentDocumentReviewSessionIds',
+    'deleteDocumentReviewSessionIds',
+    'currentDocumentReviewSessionWatermarks',
+    'currentDocumentReviewCommentIds',
+    'deleteDocumentReviewCommentIds',
+    'currentDocumentReviewCommentWatermarks',
+    'currentAnnotatedAttachmentSessionIds',
+    'deleteAnnotatedAttachmentSessionIds',
+    'currentAnnotatedAttachmentSessionWatermarks',
+    'currentTaskEventWatermarks',
+    'pushedWatermarks',
+];
+const ENCODED_PAYLOAD_OPTIONAL_KEYS = [
+    'currentTaskWatermarks',
+    'currentTaskChangeKeys',
+    'currentTaskRelationshipChangeKeys',
+    'currentTaxonomyChangeKey',
+    'currentAiProfileChangeKeys',
+    'currentTaskforceAgentIds',
+    'currentTaskforceAgentWatermarks',
+    'currentTaskforceAgentSkillIds',
+    'currentTaskforceAgentSkillWatermarks',
+    'currentAgentConversationIds',
+    'currentAgentConversationWatermarks',
+    'pushedTaskChangeKeys',
+    'deltaDiagnostics',
+];
+function hasRequiredAndAllowedKeys(value, required, optional) {
+    const keys = Object.keys(value);
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.prototype.hasOwnProperty.call(value, key))
+        && keys.every((key) => allowed.has(key));
+}
+function isWorkspaceSyncChangeRecord(value) {
+    return isRecord(value)
+        && isNonEmptyText(value.op)
+        && isJson(value);
+}
+const DOMAIN_DIAGNOSTIC_KEYS = ['mode', 'reason', 'currentCount', 'baselineCount', 'changeCount'];
+const BASELINE_RESET_REASONS = new Set([
+    'missing-baseline', 'repair-reset', 'storage-write-failed', 'full-state-domain',
+]);
+const DOMAIN_DIAGNOSTIC_MODES = new Set(['none', 'delta', 'send-all']);
+function isDomainDiagnostic(value) {
+    return isRecord(value)
+        && hasExactKeys(value, DOMAIN_DIAGNOSTIC_KEYS)
+        && DOMAIN_DIAGNOSTIC_MODES.has(String(value.mode))
+        && (value.reason === null || BASELINE_RESET_REASONS.has(String(value.reason)))
+        && isNonNegativeInteger(value.currentCount)
+        && isNonNegativeInteger(value.baselineCount)
+        && isNonNegativeInteger(value.changeCount);
+}
+const REQUIRED_DIAGNOSTIC_DOMAINS = [
+    'tasks',
+    'initiatives',
+    'workstreams',
+    'aiProfiles',
+    'documents',
+    'assets',
+    'documentReviewSessions',
+    'documentReviewComments',
+    'annotatedAttachmentSessions',
+    'taskEvents',
+    'taxonomy',
+];
+const OPTIONAL_DIAGNOSTIC_DOMAINS = [
+    'taskRelationships',
+    'taskforceAgents',
+    'taskforceAgentSkills',
+    'agentConversations',
+];
+function isDeltaDiagnostics(value) {
+    if (!isRecord(value) || !hasExactKeys(value, [
+        'totalChanges', 'byOp', 'baselineResetReason', 'domains',
+    ]))
+        return false;
+    const domains = value.domains;
+    if (!isNonNegativeInteger(value.totalChanges)
+        || !isRecord(value.byOp)
+        || Object.values(value.byOp).some((count) => !isNonNegativeInteger(count))
+        || (value.baselineResetReason !== null
+            && !['missing-baseline', 'repair-reset', 'storage-write-failed']
+                .includes(String(value.baselineResetReason)))
+        || !isRecord(domains)
+        || !hasRequiredAndAllowedKeys(domains, REQUIRED_DIAGNOSTIC_DOMAINS, OPTIONAL_DIAGNOSTIC_DOMAINS))
+        return false;
+    return REQUIRED_DIAGNOSTIC_DOMAINS.every((key) => isDomainDiagnostic(domains[key]))
+        && OPTIONAL_DIAGNOSTIC_DOMAINS.every((key) => domains[key] === undefined || isDomainDiagnostic(domains[key]));
+}
+function isEncodedWorkspaceSyncPayload(value) {
+    if (!isRecord(value)
+        || !hasRequiredAndAllowedKeys(value, ENCODED_PAYLOAD_REQUIRED_KEYS, ENCODED_PAYLOAD_OPTIONAL_KEYS)
+        || value.codecVersion !== LOCAL_WORKSPACE_SYNC_PAYLOAD_CODEC_VERSION
+        || !Array.isArray(value.changes)
+        || !value.changes.every(isWorkspaceSyncChangeRecord))
+        return false;
+    const requiredSets = [
+        'currentTaskIds',
+        'deleteTaskIds',
+        'currentInitiativeIds',
+        'currentWorkstreamIds',
+        'currentAiProfileIds',
+        'currentDocumentPaths',
+        'deleteDocumentPaths',
+        'currentAssetPaths',
+        'deleteAssetPaths',
+        'currentDocumentReviewSessionIds',
+        'deleteDocumentReviewSessionIds',
+        'currentDocumentReviewCommentIds',
+        'deleteDocumentReviewCommentIds',
+        'currentAnnotatedAttachmentSessionIds',
+        'deleteAnnotatedAttachmentSessionIds',
+    ];
+    const optionalSets = [
+        'currentTaskforceAgentIds',
+        'currentTaskforceAgentSkillIds',
+        'currentAgentConversationIds',
+    ];
+    const requiredMaps = [
+        'currentInitiativeWatermarks',
+        'currentWorkstreamWatermarks',
+        'currentAiProfileWatermarks',
+        'currentDocumentWatermarks',
+        'currentAssetWatermarks',
+        'currentDocumentReviewSessionWatermarks',
+        'currentDocumentReviewCommentWatermarks',
+        'currentAnnotatedAttachmentSessionWatermarks',
+        'currentTaskEventWatermarks',
+        'pushedWatermarks',
+    ];
+    const optionalMaps = [
+        'currentTaskWatermarks',
+        'currentTaskChangeKeys',
+        'currentTaskRelationshipChangeKeys',
+        'currentAiProfileChangeKeys',
+        'currentTaskforceAgentWatermarks',
+        'currentTaskforceAgentSkillWatermarks',
+        'currentAgentConversationWatermarks',
+        'pushedTaskChangeKeys',
+    ];
+    return requiredSets.every((key) => isStringArray(value[key]))
+        && optionalSets.every((key) => value[key] === undefined || isStringArray(value[key]))
+        && requiredMaps.every((key) => isStringPairArray(value[key]))
+        && optionalMaps.every((key) => value[key] === undefined || isStringPairArray(value[key]))
+        && (value.currentTaxonomyChangeKey === undefined || typeof value.currentTaxonomyChangeKey === 'string')
+        && (value.deltaDiagnostics === undefined || isDeltaDiagnostics(value.deltaDiagnostics));
+}
+function encodeStringSet(value, label) {
+    if (!(value instanceof Set) || [...value].some((entry) => typeof entry !== 'string')) {
+        throw new LocalWorkspaceSyncRunnerStateError(`${label} must be a string Set.`, 'SYNC_RUNNER_STATE_INVALID');
+    }
+    return [...value].sort();
+}
+function encodeStringMap(value, label) {
+    if (!(value instanceof Map)
+        || [...value].some(([key, entry]) => typeof key !== 'string' || typeof entry !== 'string')) {
+        throw new LocalWorkspaceSyncRunnerStateError(`${label} must be a string Map.`, 'SYNC_RUNNER_STATE_INVALID');
+    }
+    return [...value].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+}
+function encodeOptionalStringSet(value, label) {
+    return value === undefined ? undefined : encodeStringSet(value, label);
+}
+function encodeOptionalStringMap(value, label) {
+    return value === undefined ? undefined : encodeStringMap(value, label);
+}
+function encodeChanges(changes) {
+    if (!Array.isArray(changes)) {
+        throw new LocalWorkspaceSyncRunnerStateError('Workspace sync payload changes must be an array.', 'SYNC_RUNNER_STATE_INVALID');
+    }
+    let encoded;
+    try {
+        encoded = JSON.parse(canonicalWorkspaceSyncJson(changes));
+    }
+    catch {
+        encoded = null;
+    }
+    if (!Array.isArray(encoded) || !encoded.every(isWorkspaceSyncChangeRecord)) {
+        throw new LocalWorkspaceSyncRunnerStateError('Workspace sync payload changes cannot be encoded losslessly.', 'SYNC_RUNNER_STATE_INVALID');
+    }
+    return encoded;
+}
+export function encodeWorkspaceSyncPayload(payload) {
+    const encoded = {
+        codecVersion: LOCAL_WORKSPACE_SYNC_PAYLOAD_CODEC_VERSION,
+        changes: encodeChanges(payload.changes),
+        currentTaskIds: encodeStringSet(payload.currentTaskIds, 'Current task ids'),
+        currentTaskWatermarks: encodeOptionalStringMap(payload.currentTaskWatermarks, 'Current task watermarks'),
+        currentTaskChangeKeys: encodeOptionalStringMap(payload.currentTaskChangeKeys, 'Current task change keys'),
+        currentTaskRelationshipChangeKeys: encodeOptionalStringMap(payload.currentTaskRelationshipChangeKeys, 'Current task relationship change keys'),
+        currentTaxonomyChangeKey: payload.currentTaxonomyChangeKey,
+        deleteTaskIds: encodeStringSet(payload.deleteTaskIds, 'Deleted task ids'),
+        currentInitiativeIds: encodeStringSet(payload.currentInitiativeIds, 'Current initiative ids'),
+        currentInitiativeWatermarks: encodeStringMap(payload.currentInitiativeWatermarks, 'Initiative watermarks'),
+        currentWorkstreamIds: encodeStringSet(payload.currentWorkstreamIds, 'Current workstream ids'),
+        currentWorkstreamWatermarks: encodeStringMap(payload.currentWorkstreamWatermarks, 'Workstream watermarks'),
+        currentAiProfileIds: encodeStringSet(payload.currentAiProfileIds, 'Current AI profile ids'),
+        currentAiProfileWatermarks: encodeStringMap(payload.currentAiProfileWatermarks, 'AI profile watermarks'),
+        currentAiProfileChangeKeys: encodeOptionalStringMap(payload.currentAiProfileChangeKeys, 'AI profile change keys'),
+        currentDocumentPaths: encodeStringSet(payload.currentDocumentPaths, 'Current document paths'),
+        deleteDocumentPaths: encodeStringSet(payload.deleteDocumentPaths, 'Deleted document paths'),
+        currentDocumentWatermarks: encodeStringMap(payload.currentDocumentWatermarks, 'Document watermarks'),
+        currentAssetPaths: encodeStringSet(payload.currentAssetPaths, 'Current asset paths'),
+        deleteAssetPaths: encodeStringSet(payload.deleteAssetPaths, 'Deleted asset paths'),
+        currentAssetWatermarks: encodeStringMap(payload.currentAssetWatermarks, 'Asset watermarks'),
+        currentDocumentReviewSessionIds: encodeStringSet(payload.currentDocumentReviewSessionIds, 'Current document review session ids'),
+        deleteDocumentReviewSessionIds: encodeStringSet(payload.deleteDocumentReviewSessionIds, 'Deleted document review session ids'),
+        currentDocumentReviewSessionWatermarks: encodeStringMap(payload.currentDocumentReviewSessionWatermarks, 'Document review session watermarks'),
+        currentDocumentReviewCommentIds: encodeStringSet(payload.currentDocumentReviewCommentIds, 'Current document review comment ids'),
+        deleteDocumentReviewCommentIds: encodeStringSet(payload.deleteDocumentReviewCommentIds, 'Deleted document review comment ids'),
+        currentDocumentReviewCommentWatermarks: encodeStringMap(payload.currentDocumentReviewCommentWatermarks, 'Document review comment watermarks'),
+        currentAnnotatedAttachmentSessionIds: encodeStringSet(payload.currentAnnotatedAttachmentSessionIds, 'Current annotated attachment session ids'),
+        deleteAnnotatedAttachmentSessionIds: encodeStringSet(payload.deleteAnnotatedAttachmentSessionIds, 'Deleted annotated attachment session ids'),
+        currentAnnotatedAttachmentSessionWatermarks: encodeStringMap(payload.currentAnnotatedAttachmentSessionWatermarks, 'Annotated attachment session watermarks'),
+        currentTaskforceAgentIds: encodeOptionalStringSet(payload.currentTaskforceAgentIds, 'Current Taskforce agent ids'),
+        currentTaskforceAgentWatermarks: encodeOptionalStringMap(payload.currentTaskforceAgentWatermarks, 'Taskforce agent watermarks'),
+        currentTaskforceAgentSkillIds: encodeOptionalStringSet(payload.currentTaskforceAgentSkillIds, 'Current Taskforce agent skill ids'),
+        currentTaskforceAgentSkillWatermarks: encodeOptionalStringMap(payload.currentTaskforceAgentSkillWatermarks, 'Taskforce agent skill watermarks'),
+        currentAgentConversationIds: encodeOptionalStringSet(payload.currentAgentConversationIds, 'Current agent conversation ids'),
+        currentAgentConversationWatermarks: encodeOptionalStringMap(payload.currentAgentConversationWatermarks, 'Agent conversation watermarks'),
+        currentTaskEventWatermarks: encodeStringMap(payload.currentTaskEventWatermarks, 'Task event watermarks'),
+        pushedWatermarks: encodeStringMap(payload.pushedWatermarks, 'Pushed watermarks'),
+        pushedTaskChangeKeys: encodeOptionalStringMap(payload.pushedTaskChangeKeys, 'Pushed task change keys'),
+        deltaDiagnostics: payload.deltaDiagnostics,
+    };
+    const serialized = JSON.parse(canonicalWorkspaceSyncJson(encoded));
+    if (!isEncodedWorkspaceSyncPayload(serialized)) {
+        throw new LocalWorkspaceSyncRunnerStateError('Workspace sync payload encoding is invalid.', 'SYNC_RUNNER_STATE_INVALID');
+    }
+    return serialized;
+}
+export function decodeWorkspaceSyncPayload(encoded) {
+    if (!isEncodedWorkspaceSyncPayload(encoded)) {
+        throw new LocalWorkspaceSyncRunnerStateError('The encoded workspace sync payload is invalid.', 'SYNC_RUNNER_STATE_CORRUPT');
+    }
+    return {
+        changes: encoded.changes,
+        currentTaskIds: new Set(encoded.currentTaskIds),
+        currentTaskWatermarks: encoded.currentTaskWatermarks
+            ? new Map(encoded.currentTaskWatermarks) : undefined,
+        currentTaskChangeKeys: encoded.currentTaskChangeKeys
+            ? new Map(encoded.currentTaskChangeKeys) : undefined,
+        currentTaskRelationshipChangeKeys: encoded.currentTaskRelationshipChangeKeys
+            ? new Map(encoded.currentTaskRelationshipChangeKeys) : undefined,
+        currentTaxonomyChangeKey: encoded.currentTaxonomyChangeKey,
+        deleteTaskIds: new Set(encoded.deleteTaskIds),
+        currentInitiativeIds: new Set(encoded.currentInitiativeIds),
+        currentInitiativeWatermarks: new Map(encoded.currentInitiativeWatermarks),
+        currentWorkstreamIds: new Set(encoded.currentWorkstreamIds),
+        currentWorkstreamWatermarks: new Map(encoded.currentWorkstreamWatermarks),
+        currentAiProfileIds: new Set(encoded.currentAiProfileIds),
+        currentAiProfileWatermarks: new Map(encoded.currentAiProfileWatermarks),
+        currentAiProfileChangeKeys: encoded.currentAiProfileChangeKeys
+            ? new Map(encoded.currentAiProfileChangeKeys) : undefined,
+        currentDocumentPaths: new Set(encoded.currentDocumentPaths),
+        deleteDocumentPaths: new Set(encoded.deleteDocumentPaths),
+        currentDocumentWatermarks: new Map(encoded.currentDocumentWatermarks),
+        currentAssetPaths: new Set(encoded.currentAssetPaths),
+        deleteAssetPaths: new Set(encoded.deleteAssetPaths),
+        currentAssetWatermarks: new Map(encoded.currentAssetWatermarks),
+        currentDocumentReviewSessionIds: new Set(encoded.currentDocumentReviewSessionIds),
+        deleteDocumentReviewSessionIds: new Set(encoded.deleteDocumentReviewSessionIds),
+        currentDocumentReviewSessionWatermarks: new Map(encoded.currentDocumentReviewSessionWatermarks),
+        currentDocumentReviewCommentIds: new Set(encoded.currentDocumentReviewCommentIds),
+        deleteDocumentReviewCommentIds: new Set(encoded.deleteDocumentReviewCommentIds),
+        currentDocumentReviewCommentWatermarks: new Map(encoded.currentDocumentReviewCommentWatermarks),
+        currentAnnotatedAttachmentSessionIds: new Set(encoded.currentAnnotatedAttachmentSessionIds),
+        deleteAnnotatedAttachmentSessionIds: new Set(encoded.deleteAnnotatedAttachmentSessionIds),
+        currentAnnotatedAttachmentSessionWatermarks: new Map(encoded.currentAnnotatedAttachmentSessionWatermarks),
+        currentTaskforceAgentIds: encoded.currentTaskforceAgentIds
+            ? new Set(encoded.currentTaskforceAgentIds) : undefined,
+        currentTaskforceAgentWatermarks: encoded.currentTaskforceAgentWatermarks
+            ? new Map(encoded.currentTaskforceAgentWatermarks) : undefined,
+        currentTaskforceAgentSkillIds: encoded.currentTaskforceAgentSkillIds
+            ? new Set(encoded.currentTaskforceAgentSkillIds) : undefined,
+        currentTaskforceAgentSkillWatermarks: encoded.currentTaskforceAgentSkillWatermarks
+            ? new Map(encoded.currentTaskforceAgentSkillWatermarks) : undefined,
+        currentAgentConversationIds: encoded.currentAgentConversationIds
+            ? new Set(encoded.currentAgentConversationIds) : undefined,
+        currentAgentConversationWatermarks: encoded.currentAgentConversationWatermarks
+            ? new Map(encoded.currentAgentConversationWatermarks) : undefined,
+        currentTaskEventWatermarks: new Map(encoded.currentTaskEventWatermarks),
+        pushedWatermarks: new Map(encoded.pushedWatermarks),
+        pushedTaskChangeKeys: encoded.pushedTaskChangeKeys
+            ? new Map(encoded.pushedTaskChangeKeys) : undefined,
+        deltaDiagnostics: encoded.deltaDiagnostics,
+    };
+}
+export function createLocalWorkspaceSyncPendingV2Push(input) {
+    const frozenPayload = encodeWorkspaceSyncPayload(input.payload);
+    return {
+        signature: input.signature,
+        payloadFingerprint: fingerprintWorkspaceSyncPayload(frozenPayload),
+        frozenPayload,
+        forceAllAiProfiles: input.forceAllAiProfiles,
+        repairMode: input.repairMode,
+        preparedPlan: null,
+        preparedPlanFingerprint: null,
+        acknowledgedNonApplyingBatchOperationIdentities: [],
+        lastBatchProgress: null,
+    };
+}
+export function fingerprintLocalWorkspaceSyncPreparedPlan(plan) {
+    return fingerprintWorkspaceSyncPayload(plan);
+}
+function isPushBaseline(value) {
+    if (!isRecord(value))
+        return false;
+    const allowed = new Set([
+        'taskIds',
+        'taskWatermarks',
+        'taskChangeKeys',
+        'taskRelationshipChangeKeys',
+        'initiativeWatermarks',
+        'workstreamWatermarks',
+        'aiProfileWatermarks',
+        'aiProfileChangeKeys',
+        'taskforceAgentWatermarks',
+        'taskforceAgentSkillWatermarks',
+        'agentConversationWatermarks',
+        'documentWatermarks',
+        'assetWatermarks',
+        'documentReviewSessionWatermarks',
+        'documentReviewCommentWatermarks',
+        'annotatedAttachmentSessionWatermarks',
+        'taskEventWatermarks',
+        'taxonomyStateFingerprint',
+        'taxonomyChangeKey',
+    ]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return false;
+    const requiredPairs = [
+        'taskWatermarks',
+        'initiativeWatermarks',
+        'workstreamWatermarks',
+        'aiProfileWatermarks',
+        'documentWatermarks',
+        'assetWatermarks',
+        'documentReviewSessionWatermarks',
+        'documentReviewCommentWatermarks',
+        'annotatedAttachmentSessionWatermarks',
+        'taskEventWatermarks',
+    ];
+    if (requiredPairs.some((key) => !isStringPairArray(value[key])))
+        return false;
+    const optionalPairs = [
+        'taskChangeKeys',
+        'taskRelationshipChangeKeys',
+        'aiProfileChangeKeys',
+        'taskforceAgentWatermarks',
+        'taskforceAgentSkillWatermarks',
+        'agentConversationWatermarks',
+    ];
+    if (optionalPairs.some((key) => value[key] !== undefined && !isStringPairArray(value[key])))
+        return false;
+    if (value.taskIds !== undefined && !isStringArray(value.taskIds))
+        return false;
+    if (typeof value.taxonomyStateFingerprint !== 'string')
+        return false;
+    if (value.taxonomyChangeKey !== undefined && typeof value.taxonomyChangeKey !== 'string')
+        return false;
+    return true;
+}
+function isPendingV2Push(value) {
+    if (!isRecord(value) || !hasExactKeys(value, [
+        'signature',
+        'payloadFingerprint',
+        'frozenPayload',
+        'forceAllAiProfiles',
+        'repairMode',
+        'preparedPlan',
+        'preparedPlanFingerprint',
+        'acknowledgedNonApplyingBatchOperationIdentities',
+        'lastBatchProgress',
+    ]))
+        return false;
+    return isNonEmptyText(value.signature)
+        && typeof value.payloadFingerprint === 'string'
+        && /^[a-f0-9]{64}$/.test(value.payloadFingerprint)
+        && isEncodedWorkspaceSyncPayload(value.frozenPayload)
+        && fingerprintWorkspaceSyncPayload(value.frozenPayload) === value.payloadFingerprint
+        && typeof value.forceAllAiProfiles === 'boolean'
+        && typeof value.repairMode === 'boolean'
+        && ((value.preparedPlan === null && value.preparedPlanFingerprint === null)
+            || (isPreparedV2PushPlan(value.preparedPlan)
+                && typeof value.preparedPlanFingerprint === 'string'
+                && /^[a-f0-9]{64}$/.test(value.preparedPlanFingerprint)
+                && fingerprintLocalWorkspaceSyncPreparedPlan(value.preparedPlan)
+                    === value.preparedPlanFingerprint
+                && value.preparedPlan.batches.every((batch) => batch.every((entry) => entry.sourceChangeIndex
+                    < value.frozenPayload.changes.length))))
+        && isStringArray(value.acknowledgedNonApplyingBatchOperationIdentities)
+        && value.acknowledgedNonApplyingBatchOperationIdentities.every((identity) => /^[a-f0-9]{64}$/.test(identity))
+        && (value.lastBatchProgress === null
+            || (isPendingV2PushBatchProgress(value.lastBatchProgress)
+                && value.lastBatchProgress.completedChanges <= value.frozenPayload.changes.length
+                && value.lastBatchProgress.failedChangeCount
+                    <= value.frozenPayload.changes.length
+                        - value.lastBatchProgress.completedChanges));
+}
+function isPreparedV2PushPlan(value) {
+    if (!isRecord(value) || !hasExactKeys(value, [
+        'contractVersion',
+        'ownership',
+        'batches',
+        'batchOperationIdentities',
+    ]))
+        return false;
+    if (value.contractVersion !== WORKSPACE_PUSH_PREPARED_PLAN_VERSION
+        || !isRecord(value.ownership)
+        || !Array.isArray(value.batches)
+        || value.batches.length === 0
+        || !isStringArray(value.batchOperationIdentities)
+        || value.batchOperationIdentities.length !== value.batches.length
+        || !value.batchOperationIdentities.every((identity) => /^[a-f0-9]{64}$/.test(identity)))
+        return false;
+    const sourceIndexes = new Set();
+    const isCanonicalEmptyPlan = value.batches.length === 1
+        && Array.isArray(value.batches[0])
+        && value.batches[0].length === 0;
+    return value.batches.every((batch) => Array.isArray(batch)
+        && (batch.length > 0 || isCanonicalEmptyPlan)
+        && batch.every((entry) => {
+            if (!isRecord(entry) || !hasRequiredAndAllowedKeys(entry, ['sourceChangeIndex'], ['preparedChange']))
+                return false;
+            const sourceChangeIndex = Number(entry.sourceChangeIndex);
+            if (!isNonNegativeInteger(sourceChangeIndex)
+                || sourceIndexes.has(sourceChangeIndex)
+                || (entry.preparedChange !== undefined && !isWorkspaceSyncChangeRecord(entry.preparedChange)))
+                return false;
+            sourceIndexes.add(sourceChangeIndex);
+            return true;
+        }));
+}
+function isPendingV2PushBatchProgress(value) {
+    if (!isRecord(value) || !hasExactKeys(value, [
+        'totalBatches',
+        'completedBatches',
+        'completedChanges',
+        'failedBatchIndex',
+        'failedChangeCount',
+        'failedOperations',
+        'failureDomain',
+    ]))
+        return false;
+    return isNonNegativeInteger(value.totalBatches)
+        && Number(value.totalBatches) > 0
+        && isNonNegativeInteger(value.completedBatches)
+        && Number(value.completedBatches) < Number(value.totalBatches)
+        && isNonNegativeInteger(value.completedChanges)
+        && isNonNegativeInteger(value.failedBatchIndex)
+        && Number(value.failedBatchIndex) === Number(value.completedBatches)
+        && isNonNegativeInteger(value.failedChangeCount)
+        && Number(value.failedChangeCount) > 0
+        && isStringArray(value.failedOperations)
+        && value.failedOperations.length > 0
+        && value.failedOperations.every(isNonEmptyText)
+        && new Set(value.failedOperations).size === value.failedOperations.length
+        && (value.failureDomain === 'content'
+            || value.failureDomain === 'metadata'
+            || value.failureDomain === 'mixed');
+}
+function normalizePendingV2Push(value) {
+    if (!isRecord(value))
+        return value;
+    const legacyKeys = [
+        'signature',
+        'payloadFingerprint',
+        'frozenPayload',
+        'forceAllAiProfiles',
+        'repairMode',
+    ];
+    if (!hasRequiredAndAllowedKeys(value, legacyKeys, [
+        'preparedPlan',
+        'preparedPlanFingerprint',
+        'acknowledgedNonApplyingBatchOperationIdentities',
+        'lastBatchProgress',
+    ])) {
+        return value;
+    }
+    return {
+        ...value,
+        preparedPlan: value.preparedPlan || null,
+        preparedPlanFingerprint: value.preparedPlan
+            ? value.preparedPlanFingerprint || fingerprintLocalWorkspaceSyncPreparedPlan(value.preparedPlan)
+            : null,
+        acknowledgedNonApplyingBatchOperationIdentities: value.acknowledgedNonApplyingBatchOperationIdentities || [],
+        lastBatchProgress: value.lastBatchProgress || null,
+    };
+}
+function isRetry(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ['kind', 'attempt', 'retryAt']))
+        return false;
+    return RETRY_KINDS.has(value.kind)
+        && isPositiveInteger(value.attempt)
+        && isTimestamp(value.retryAt);
+}
+function isRepairContinuation(value) {
+    if (!isRecord(value))
+        return false;
+    const commonValid = REPAIR_KINDS.has(value.kind)
+        && isNullableText(value.cursor)
+        && isNonNegativeInteger(value.attempt);
+    if (!commonValid)
+        return false;
+    if (hasExactKeys(value, ['kind', 'cursor', 'attempt']))
+        return true;
+    if (!hasExactKeys(value, [
+        'continuationVersion',
+        'kind',
+        'cursor',
+        'attempt',
+        'coordinatorGeneration',
+        'ownershipFingerprint',
+        'recoveryBatchId',
+        'forceAuthoritativeRepair',
+        'excludeInitiatives',
+        'excludedProjections',
+        'completedPushSignatureSha256',
+    ]))
+        return false;
+    return (value.continuationVersion === 1 || value.continuationVersion === 2)
+        && isPositiveInteger(value.coordinatorGeneration)
+        && typeof value.ownershipFingerprint === 'string'
+        && /^[a-f0-9]{64}$/.test(value.ownershipFingerprint)
+        && isNullableText(value.recoveryBatchId)
+        && typeof value.forceAuthoritativeRepair === 'boolean'
+        && typeof value.excludeInitiatives === 'boolean'
+        && Array.isArray(value.excludedProjections)
+        && value.excludedProjections.every((projection) => (typeof projection === 'string'
+            && REPAIR_EXCLUDED_PROJECTIONS.has(projection)))
+        && new Set(value.excludedProjections).size === value.excludedProjections.length
+        && (value.completedPushSignatureSha256 === null
+            || (typeof value.completedPushSignatureSha256 === 'string'
+                && /^[a-f0-9]{64}$/.test(value.completedPushSignatureSha256)));
+}
+function parseCheckpoint(value) {
+    if (!isRecord(value)) {
+        throw new LocalWorkspaceSyncRunnerStateError('The local sync runner checkpoint shape is invalid.', 'SYNC_RUNNER_STATE_CORRUPT');
+    }
+    const legacyKeys = [
+        'controlState',
+        'syncEnabled',
+        'syncPhase',
+        'pullCursor',
+        'pendingV2Push',
+        'retry',
+        'repairContinuation',
+        'pushBaseline',
+        'lastPullAt',
+        'lastPushAt',
+        'lastSyncedAt',
+        'lastError',
+    ];
+    const currentKeys = [
+        ...legacyKeys,
+        'remoteHintObservedAt',
+        'consecutivePushesWhilePullDue',
+    ];
+    const isLegacyCheckpoint = hasExactKeys(value, legacyKeys);
+    if (!isLegacyCheckpoint && !hasExactKeys(value, currentKeys)) {
+        throw new LocalWorkspaceSyncRunnerStateError('The local sync runner checkpoint shape is invalid.', 'SYNC_RUNNER_STATE_CORRUPT');
+    }
+    const normalizedCheckpoint = isLegacyCheckpoint
+        ? {
+            ...value,
+            remoteHintObservedAt: null,
+            consecutivePushesWhilePullDue: 0,
+        }
+        : value;
+    const normalized = {
+        ...normalizedCheckpoint,
+        pendingV2Push: normalizePendingV2Push(normalizedCheckpoint.pendingV2Push),
+    };
+    if (!CONTROL_STATES.has(normalized.controlState)
+        || typeof normalized.syncEnabled !== 'boolean'
+        || !SYNC_PHASES.has(normalized.syncPhase)
+        || !isNullableText(normalized.pullCursor)
+        || !isNullableTimestamp(normalized.remoteHintObservedAt)
+        || !isNonNegativeInteger(normalized.consecutivePushesWhilePullDue)
+        || (normalized.pendingV2Push !== null && !isPendingV2Push(normalized.pendingV2Push))
+        || (normalized.retry !== null && !isRetry(normalized.retry))
+        || (normalized.repairContinuation !== null
+            && !isRepairContinuation(normalized.repairContinuation))
+        || (normalized.pushBaseline !== null && !isPushBaseline(normalized.pushBaseline))
+        || !isNullableTimestamp(normalized.lastPullAt)
+        || !isNullableTimestamp(normalized.lastPushAt)
+        || !isNullableTimestamp(normalized.lastSyncedAt)
+        || !isNullableText(normalized.lastError)) {
+        throw new LocalWorkspaceSyncRunnerStateError('The local sync runner checkpoint contains invalid values.', 'SYNC_RUNNER_STATE_CORRUPT');
+    }
+    return normalized;
+}
+function serializeCheckpoint(checkpoint) {
+    try {
+        const encoded = canonicalWorkspaceSyncJson(checkpoint);
+        parseCheckpoint(JSON.parse(encoded));
+        return encoded;
+    }
+    catch (error) {
+        if (error instanceof LocalWorkspaceSyncRunnerStateError) {
+            throw new LocalWorkspaceSyncRunnerStateError(error.message, 'SYNC_RUNNER_STATE_INVALID');
+        }
+        throw new LocalWorkspaceSyncRunnerStateError('The local sync runner checkpoint cannot be serialized.', 'SYNC_RUNNER_STATE_INVALID');
+    }
+}
+function requiredCoordinate(value, label) {
+    const normalized = String(value || '').trim();
+    if (!normalized) {
+        throw new LocalWorkspaceSyncRunnerStateError(`${label} is required.`, 'SYNC_RUNNER_STATE_INVALID');
+    }
+    return normalized;
+}
+function mapRow(row) {
+    const stateVersion = Number(row.state_version);
+    if (stateVersion !== LOCAL_WORKSPACE_SYNC_RUNNER_STATE_VERSION) {
+        throw new LocalWorkspaceSyncRunnerStateError(`Local sync runner state version ${stateVersion} is unsupported.`, 'SYNC_RUNNER_STATE_VERSION_UNSUPPORTED');
+    }
+    const coordinatorGeneration = Number(row.coordinator_generation);
+    const checkpointRevision = Number(row.checkpoint_revision);
+    if (!isNonNegativeInteger(coordinatorGeneration)
+        || !isNonNegativeInteger(checkpointRevision)
+        || !isNonEmptyText(row.tenant_id)
+        || !isNonEmptyText(row.workspace_id)
+        || !isTimestamp(row.created_at)
+        || !isTimestamp(row.updated_at)) {
+        throw new LocalWorkspaceSyncRunnerStateError('The local sync runner state row is corrupt.', 'SYNC_RUNNER_STATE_CORRUPT');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(String(row.checkpoint_json || ''));
+    }
+    catch {
+        throw new LocalWorkspaceSyncRunnerStateError('The local sync runner checkpoint JSON is corrupt.', 'SYNC_RUNNER_STATE_CORRUPT');
+    }
+    return {
+        stateVersion: LOCAL_WORKSPACE_SYNC_RUNNER_STATE_VERSION,
+        tenantId: row.tenant_id,
+        workspaceId: row.workspace_id,
+        coordinatorGeneration,
+        checkpointRevision,
+        checkpoint: parseCheckpoint(parsed),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function createDefaultLocalWorkspaceSyncRunnerCheckpoint() {
+    return {
+        controlState: 'idle',
+        syncEnabled: false,
+        syncPhase: 'idle',
+        pullCursor: null,
+        remoteHintObservedAt: null,
+        consecutivePushesWhilePullDue: 0,
+        pendingV2Push: null,
+        retry: null,
+        repairContinuation: null,
+        pushBaseline: null,
+        lastPullAt: null,
+        lastPushAt: null,
+        lastSyncedAt: null,
+        lastError: null,
+    };
+}
+export class LocalWorkspaceSyncRunnerStateStore {
+    db;
+    now;
+    constructor(db, now = () => new Date().toISOString()) {
+        this.db = db;
+        this.now = now;
+    }
+    initialize(input) {
+        const tenantId = requiredCoordinate(input.tenantId, 'Tenant id');
+        const workspaceId = requiredCoordinate(input.workspaceId, 'Workspace id');
+        if (!isNonNegativeInteger(input.coordinatorGeneration)) {
+            throw new LocalWorkspaceSyncRunnerStateError('Coordinator generation must be a non-negative integer.', 'SYNC_RUNNER_STATE_INVALID');
+        }
+        const checkpointJson = serializeCheckpoint(input.checkpoint ?? createDefaultLocalWorkspaceSyncRunnerCheckpoint());
+        const at = this.now();
+        this.db.prepare(`
+            INSERT INTO local_workspace_sync_runner_state (
+                tenant_id, workspace_id, state_version, coordinator_generation,
+                checkpoint_revision, checkpoint_json, created_at, updated_at
+            ) VALUES (?, ?, ?, ?, 0, ?, ?, ?)
+            ON CONFLICT (tenant_id, workspace_id) DO NOTHING
+        `).run(tenantId, workspaceId, LOCAL_WORKSPACE_SYNC_RUNNER_STATE_VERSION, input.coordinatorGeneration, checkpointJson, at, at);
+        const state = this.readRequired(tenantId, workspaceId);
+        if (state.coordinatorGeneration !== input.coordinatorGeneration) {
+            throw new LocalWorkspaceSyncRunnerStateError('The local sync runner state belongs to a different coordinator generation.', 'SYNC_RUNNER_STATE_STALE_GENERATION');
+        }
+        return state;
+    }
+    read(tenantIdInput, workspaceIdInput) {
+        const tenantId = requiredCoordinate(tenantIdInput, 'Tenant id');
+        const workspaceId = requiredCoordinate(workspaceIdInput, 'Workspace id');
+        const row = this.db.prepare(`
+            SELECT *
+            FROM local_workspace_sync_runner_state
+            WHERE tenant_id = ? AND workspace_id = ?
+        `).get(tenantId, workspaceId);
+        return row ? mapRow(row) : null;
+    }
+    compareAndSet(input) {
+        const tenantId = requiredCoordinate(input.tenantId, 'Tenant id');
+        const workspaceId = requiredCoordinate(input.workspaceId, 'Workspace id');
+        if (!isNonNegativeInteger(input.expectedCoordinatorGeneration)
+            || !isNonNegativeInteger(input.expectedCheckpointRevision)) {
+            throw new LocalWorkspaceSyncRunnerStateError('Expected generation and checkpoint revision must be non-negative integers.', 'SYNC_RUNNER_STATE_INVALID');
+        }
+        const checkpointJson = serializeCheckpoint(input.checkpoint);
+        return this.db.transaction(() => {
+            const current = this.readRequired(tenantId, workspaceId);
+            if (current.coordinatorGeneration !== input.expectedCoordinatorGeneration) {
+                throw new LocalWorkspaceSyncRunnerStateError('The coordinator generation changed before the runner checkpoint was committed.', 'SYNC_RUNNER_STATE_STALE_GENERATION');
+            }
+            if (current.checkpointRevision !== input.expectedCheckpointRevision) {
+                throw new LocalWorkspaceSyncRunnerStateError('The runner checkpoint revision changed before the checkpoint was committed.', 'SYNC_RUNNER_STATE_STALE_REVISION');
+            }
+            const updatedAt = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_workspace_sync_runner_state
+                SET checkpoint_revision = checkpoint_revision + 1,
+                    checkpoint_json = ?,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND checkpoint_revision = ?
+            `).run(checkpointJson, updatedAt, tenantId, workspaceId, input.expectedCoordinatorGeneration, input.expectedCheckpointRevision);
+            if (Number(result?.changes || 0) !== 1) {
+                const latest = this.readRequired(tenantId, workspaceId);
+                const code = latest.coordinatorGeneration !== input.expectedCoordinatorGeneration
+                    ? 'SYNC_RUNNER_STATE_STALE_GENERATION'
+                    : 'SYNC_RUNNER_STATE_STALE_REVISION';
+                throw new LocalWorkspaceSyncRunnerStateError('The runner checkpoint changed before the checkpoint was committed.', code);
+            }
+            input.beforeCommit?.();
+            return this.readRequired(tenantId, workspaceId);
+        })();
+    }
+    compareAndSetWithCommandTransition(input) {
+        const tenantId = requiredCoordinate(input.tenantId, 'Tenant id');
+        const workspaceId = requiredCoordinate(input.workspaceId, 'Workspace id');
+        const commandId = requiredCoordinate(input.commandId, 'Command id');
+        const checkpointJson = serializeCheckpoint(input.checkpoint);
+        if (!isNonNegativeInteger(input.expectedCoordinatorGeneration)
+            || !isNonNegativeInteger(input.expectedCheckpointRevision)) {
+            throw new LocalWorkspaceSyncRunnerStateError('Expected generation and checkpoint revision must be non-negative integers.', 'SYNC_RUNNER_STATE_INVALID');
+        }
+        return this.db.transaction(() => {
+            const coordinator = this.db.prepare(`
+                SELECT active_workspace_id, coordinator_generation, ownership_mode, transition_state
+                FROM local_sync_coordinator_state
+                WHERE coordinator_id = ?
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(LOCAL_SYNC_COORDINATOR_ID);
+            if (!coordinator
+                || String(coordinator.active_workspace_id || '') !== workspaceId
+                || Number(coordinator.coordinator_generation) !== input.expectedCoordinatorGeneration
+                || coordinator.ownership_mode !== 'server'
+                || coordinator.transition_state !== 'idle') {
+                throw new LocalWorkspaceSyncRunnerStateError('The coordinator ownership fence changed before command completion.', 'SYNC_RUNNER_STATE_STALE_GENERATION');
+            }
+            const current = this.readRequired(tenantId, workspaceId);
+            if (current.coordinatorGeneration !== input.expectedCoordinatorGeneration) {
+                throw new LocalWorkspaceSyncRunnerStateError('The coordinator generation changed before command completion.', 'SYNC_RUNNER_STATE_STALE_GENERATION');
+            }
+            if (current.checkpointRevision !== input.expectedCheckpointRevision) {
+                throw new LocalWorkspaceSyncRunnerStateError('The runner checkpoint changed before command completion.', 'SYNC_RUNNER_STATE_STALE_REVISION');
+            }
+            const at = this.now();
+            const checkpointResult = this.db.prepare(`
+                UPDATE local_workspace_sync_runner_state
+                SET checkpoint_revision = checkpoint_revision + 1,
+                    checkpoint_json = ?,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND checkpoint_revision = ?
+            `).run(checkpointJson, at, tenantId, workspaceId, input.expectedCoordinatorGeneration, input.expectedCheckpointRevision);
+            if (Number(checkpointResult?.changes || 0) !== 1) {
+                throw new LocalWorkspaceSyncRunnerStateError('The runner checkpoint changed before command completion.', 'SYNC_RUNNER_STATE_STALE_REVISION');
+            }
+            const terminal = input.nextCommandStatus !== 'accepted';
+            const commandResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = ?,
+                    completed_at = ?,
+                    result_json = ?,
+                    error_code = ?,
+                    error_message = ?,
+                    updated_at = ?
+                WHERE command_id = ?
+                  AND workspace_id = ?
+                  AND expected_coordinator_generation = ?
+                  AND command_type IN ('EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair')
+                  AND status = 'running'
+            `).run(input.nextCommandStatus, terminal ? at : null, input.result === undefined ? null : canonicalWorkspaceSyncJson(input.result), input.errorCode || null, input.errorMessage || null, at, commandId, workspaceId, input.expectedCoordinatorGeneration);
+            if (Number(commandResult?.changes || 0) !== 1) {
+                throw new LocalWorkspaceSyncRunnerStateError(`Runner command ${commandId} changed before checkpoint completion.`, 'SYNC_RUNNER_STATE_COMMAND_CONFLICT');
+            }
+            return this.readRequired(tenantId, workspaceId);
+        })();
+    }
+    advanceGeneration(input) {
+        const tenantId = requiredCoordinate(input.tenantId, 'Tenant id');
+        const workspaceId = requiredCoordinate(input.workspaceId, 'Workspace id');
+        if (!isNonNegativeInteger(input.expectedCoordinatorGeneration)
+            || !isNonNegativeInteger(input.expectedCheckpointRevision)
+            || !isNonNegativeInteger(input.targetCoordinatorGeneration)
+            || input.targetCoordinatorGeneration !== input.expectedCoordinatorGeneration + 1) {
+            throw new LocalWorkspaceSyncRunnerStateError('Runner state generation advancement must move exactly one generation forward.', 'SYNC_RUNNER_STATE_INVALID');
+        }
+        const checkpointJson = serializeCheckpoint(input.checkpoint);
+        return this.db.transaction(() => {
+            const current = this.readRequired(tenantId, workspaceId);
+            if (current.coordinatorGeneration !== input.expectedCoordinatorGeneration) {
+                throw new LocalWorkspaceSyncRunnerStateError('The coordinator generation changed before runner state generation advancement.', 'SYNC_RUNNER_STATE_STALE_GENERATION');
+            }
+            if (current.checkpointRevision !== input.expectedCheckpointRevision) {
+                throw new LocalWorkspaceSyncRunnerStateError('The runner checkpoint revision changed before generation advancement.', 'SYNC_RUNNER_STATE_STALE_REVISION');
+            }
+            const updatedAt = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_workspace_sync_runner_state
+                SET coordinator_generation = ?,
+                    checkpoint_revision = checkpoint_revision + 1,
+                    checkpoint_json = ?,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND checkpoint_revision = ?
+            `).run(input.targetCoordinatorGeneration, checkpointJson, updatedAt, tenantId, workspaceId, input.expectedCoordinatorGeneration, input.expectedCheckpointRevision);
+            if (Number(result?.changes || 0) !== 1) {
+                const latest = this.readRequired(tenantId, workspaceId);
+                const code = latest.coordinatorGeneration !== input.expectedCoordinatorGeneration
+                    ? 'SYNC_RUNNER_STATE_STALE_GENERATION'
+                    : 'SYNC_RUNNER_STATE_STALE_REVISION';
+                throw new LocalWorkspaceSyncRunnerStateError('The runner state changed before generation advancement.', code);
+            }
+            return this.readRequired(tenantId, workspaceId);
+        })();
+    }
+    readRequired(tenantId, workspaceId) {
+        const state = this.read(tenantId, workspaceId);
+        if (!state) {
+            throw new LocalWorkspaceSyncRunnerStateError('The local sync runner state does not exist.', 'SYNC_RUNNER_STATE_INVALID');
+        }
+        return state;
+    }
+}