@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/v3/workspaceSyncV3CombinedProjectionState.js

@@ -0,0 +1,672 @@
+import { classifyWorkspaceSyncV3CombinedCoverageCompat } from '../../compat/workspaceSyncV3CombinedCoverageCompat.js';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE } from './workspaceSyncV3CombinedCoverage.js';
+import { resolveWorkspaceSyncV3RegisteredCoverage } from './workspaceSyncV3CoverageRegistry.js';
+import { WORKSPACE_SYNC_V3_COVERAGE_PROFILE } from './workspaceSyncV3FeedProfile.js';
+import { INITIATIVE_FULL_V1_PROJECTION, WorkspaceSyncV3ProjectionStateStore, } from './workspaceSyncV3ProjectionState.js';
+import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_COMBINED_PROJECTION_LOCK, WORKSPACE_SYNC_COMBINED_PROJECTION, WORKSPACE_SYNC_CONTRACT_VERSION, WORKSPACE_SYNC_INITIATIVE_PROJECTION_LOCK, } from './syncDurabilityStore.js';
+export const WORKSPACE_SYNC_V3_COMBINED_STATE_ID = WORKSPACE_SYNC_COMBINED_PROJECTION;
+export const WORKSPACE_SYNC_V3_REPAIR_SNAPSHOT_STALE = 'WORKSPACE_SYNC_V3_REPAIR_SNAPSHOT_STALE';
+function requiredText(value, label) {
+    const text = String(value || '').trim();
+    if (!text)
+        throw new Error(`${label} is required.`);
+    return text;
+}
+function sequence(value, label) {
+    const text = String(value ?? '').trim();
+    if (!/^\d+$/.test(text))
+        throw new Error(`${label} is invalid.`);
+    return BigInt(text).toString(10);
+}
+function timestamp(value, label) {
+    const text = requiredText(value, label);
+    const milliseconds = Date.parse(text);
+    if (!Number.isFinite(milliseconds))
+        throw new Error(`${label} is invalid.`);
+    return new Date(milliseconds).toISOString();
+}
+function synchronous(value, label) {
+    if (value && typeof value.then === 'function')
+        throw new Error(`${label} must be synchronous.`);
+}
+function registeredCoverage(value) {
+    return resolveWorkspaceSyncV3RegisteredCoverage(value);
+}
+function entryOrder(entry, profile) {
+    const rank = profile.projections.findIndex((projection) => projection.projectionId === entry.projection);
+    if (rank < 0)
+        throw new Error(`Unsupported combined repair projection: ${entry.projection}.`);
+    return `${String(rank).padStart(3, '0')}\0${entry.entityId}`;
+}
+export function validateWorkspaceSyncV3CombinedRepairPage(page, workspaceId, now, allowExpired = false) {
+    const registered = registeredCoverage(page.coverage);
+    const profile = registered?.profile;
+    if (page.success !== true || page.protocolVersion !== 3 || page.workspaceId !== workspaceId
+        || !registered || canonicalWorkspaceSyncJson(page.coverage) !== canonicalWorkspaceSyncJson(profile)
+        || !page.snapshotId || page.hasMore !== Boolean(page.nextRepairCursor)
+        || (page.hasMore && page.entries.length === 0)
+        || page.diagnostics.returnedEntries !== page.entries.length
+        || page.diagnostics.entriesBytes !== Buffer.byteLength(JSON.stringify(page.entries), 'utf8')
+        || page.diagnostics.responseBytes !== Buffer.byteLength(JSON.stringify(page), 'utf8')
+        || (!allowExpired && Date.parse(timestamp(page.expiresAt, 'Combined repair expiry')) <= Date.parse(now))) {
+        throw new Error('Combined repair page contract is invalid.');
+    }
+    const snapshotSequence = BigInt(sequence(page.snapshotSequence, 'Combined repair snapshot sequence'));
+    let prior = '';
+    const identities = new Set();
+    for (const entry of page.entries) {
+        registered.validateEntry(entry);
+        const order = entryOrder(entry, registered.profile);
+        const identity = `${entry.projection}\0${entry.domain}\0${entry.entityId}`;
+        if (order <= prior || identities.has(identity) || BigInt(entry.sequence) > snapshotSequence) {
+            throw new Error('Combined repair entries are not unique, ordered, or bounded by the snapshot.');
+        }
+        prior = order;
+        identities.add(identity);
+    }
+}
+function validateDeltaPage(page, workspaceId, current) {
+    const registered = registeredCoverage({
+        coverageProfileId: current.coverageProfileId,
+        coverageVersion: current.coverageVersion,
+        coverageDigest: current.coverageDigest,
+    });
+    const profile = registered?.profile;
+    if (page.success !== true || page.protocolVersion !== 3 || page.workspaceId !== workspaceId
+        || !registered || canonicalWorkspaceSyncJson(page.coverage) !== canonicalWorkspaceSyncJson(profile)
+        || page.diagnostics.coveredCount !== page.entries.length
+        || page.diagnostics.scannedCount < page.entries.length
+        || page.diagnostics.responseBytes !== Buffer.byteLength(JSON.stringify(page), 'utf8')) {
+        throw new Error('Combined feed page contract is invalid.');
+    }
+    const high = BigInt(sequence(page.cycleHighWatermark, 'Cycle high watermark'));
+    const last = BigInt(sequence(page.lastScannedSequence, 'Last scanned sequence'));
+    const priorHigh = BigInt(sequence(current.cycleHighWatermark, 'Persisted cycle high watermark'));
+    const priorLast = BigInt(sequence(current.lastScannedSequence, 'Persisted last scanned sequence'));
+    if (last < priorLast || last > high || page.hasMore !== (last < high)
+        || (priorLast < priorHigh && high !== priorHigh)) {
+        throw new Error('Combined feed page coordinates are invalid.');
+    }
+    let priorEntrySequence = priorLast;
+    const revisions = new Map();
+    for (const entry of page.entries) {
+        registered.validateEntry(entry);
+        const entrySequence = BigInt(entry.sequence);
+        if (entrySequence <= priorEntrySequence || entrySequence > last) {
+            throw new Error('Combined feed entries are outside page coordinates.');
+        }
+        priorEntrySequence = entrySequence;
+        const key = `${entry.domain}\0${entry.entityId}`;
+        const prior = revisions.get(key);
+        const entity = BigInt(entry.entityRevision);
+        const lifecycle = BigInt(entry.lifecycleRevision);
+        if (prior && (entity < prior.entity || lifecycle < prior.lifecycle
+            || (entity === prior.entity && lifecycle === prior.lifecycle))) {
+            throw new Error('Combined feed revisions are not monotonic within the page.');
+        }
+        revisions.set(key, { entity, lifecycle });
+    }
+}
+function validateDuplicateDeltaPage(page, workspaceId, current) {
+    const registered = registeredCoverage({
+        coverageProfileId: current.coverageProfileId,
+        coverageVersion: current.coverageVersion,
+        coverageDigest: current.coverageDigest,
+    });
+    const profile = registered?.profile;
+    if (page.success !== true || page.protocolVersion !== 3 || page.workspaceId !== workspaceId
+        || !registered || canonicalWorkspaceSyncJson(page.coverage) !== canonicalWorkspaceSyncJson(profile)
+        || page.cycleHighWatermark !== current.cycleHighWatermark
+        || page.lastScannedSequence !== current.lastScannedSequence
+        || page.hasMore !== (BigInt(page.lastScannedSequence) < BigInt(page.cycleHighWatermark))
+        || page.diagnostics.coveredCount !== page.entries.length
+        || page.diagnostics.scannedCount < page.entries.length
+        || page.diagnostics.responseBytes !== Buffer.byteLength(JSON.stringify(page), 'utf8')) {
+        throw new Error('Combined duplicate feed page contract is invalid.');
+    }
+    let prior = -1n;
+    for (const entry of page.entries) {
+        registered.validateEntry(entry);
+        const currentSequence = BigInt(entry.sequence);
+        if (currentSequence <= prior || currentSequence > BigInt(page.lastScannedSequence)) {
+            throw new Error('Combined duplicate feed entries are outside page coordinates.');
+        }
+        prior = currentSequence;
+    }
+}
+export class WorkspaceSyncV3CombinedProjectionStateStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    read(input) {
+        const tenantId = requiredText(input.tenantId, 'Tenant id');
+        const workspaceId = requiredText(input.workspaceId, 'Workspace id');
+        const row = this.readRow(tenantId, workspaceId);
+        if (!row)
+            return { coverageId: WORKSPACE_SYNC_V3_COMBINED_STATE_ID, owner: 'v2', epoch: '0',
+                coverageProfileId: WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE.coverageProfileId,
+                coverageVersion: WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE.coverageVersion,
+                coverageDigest: WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE.coverageDigest,
+                opaqueCursor: null, cycleHighWatermark: null, lastScannedSequence: null,
+                appliedSnapshotId: null, appliedPageDigest: null, coverageRepairRequired: false, repair: null };
+        return this.mapRow(row);
+    }
+    applyRepairPage(input) {
+        const tenantId = requiredText(input.tenantId, 'Tenant id');
+        const workspaceId = requiredText(input.workspaceId, 'Workspace id');
+        const expectedEpoch = sequence(input.expectedEpoch, 'Expected projection epoch');
+        const now = timestamp(input.now, 'Repair apply time');
+        validateWorkspaceSyncV3CombinedRepairPage(input.page, workspaceId, now, true);
+        const previousRepairCursor = input.previousRepairCursor == null
+            ? null : requiredText(input.previousRepairCursor, 'Previous repair cursor');
+        const finish = (result) => {
+            synchronous(input.beforeCommit?.(result), 'Combined repair pre-commit callback');
+            return result;
+        };
+        return this.db.transaction(() => {
+            this.lock(tenantId, workspaceId, now);
+            synchronous(input.beforeApply?.(), 'Combined repair pre-apply callback');
+            let current = this.read({ tenantId, workspaceId });
+            if (!current.coverageRepairRequired
+                && current.owner === 'v3' && current.epoch === (BigInt(expectedEpoch) + 1n).toString(10)
+                && canonicalWorkspaceSyncJson(registeredCoverage(current)?.profile)
+                    === canonicalWorkspaceSyncJson(input.page.coverage)
+                && current.opaqueCursor === input.page.resumeCursor
+                && current.lastScannedSequence === input.page.snapshotSequence
+                && current.appliedSnapshotId === input.page.snapshotId
+                && current.appliedPageDigest === fingerprintWorkspaceSyncPayload(input.page.entries)
+                && !current.repair && !input.page.hasMore) {
+                return finish({ state: 'duplicate', projection: current });
+            }
+            validateWorkspaceSyncV3CombinedRepairPage(input.page, workspaceId, now);
+            if (current.epoch !== expectedEpoch)
+                throw new Error('Combined projection epoch changed before repair commit.');
+            const sameRepair = current.repair?.snapshotId === input.page.snapshotId
+                && current.repair.snapshotSequence === input.page.snapshotSequence
+                && current.repair.expiresAt === input.page.expiresAt
+                && current.repair.resumeCursor === input.page.resumeCursor
+                && current.repair.epoch === (BigInt(expectedEpoch) + 1n).toString(10);
+            if (!sameRepair) {
+                if (previousRepairCursor !== null)
+                    throw new Error('Combined repair continuation has no matching local repair.');
+                const repairEpoch = (BigInt(current.epoch) + 1n).toString(10);
+                this.clearEntries(tenantId, workspaceId);
+                this.upsertState({ tenantId, workspaceId, owner: current.owner, epoch: current.epoch,
+                    coverage: registeredCoverage(current)?.profile || input.page.coverage,
+                    repairEpoch, snapshotId: input.page.snapshotId, snapshotSequence: input.page.snapshotSequence,
+                    expiresAt: input.page.expiresAt, resumeCursor: input.page.resumeCursor, repairCursor: null,
+                    opaqueCursor: current.opaqueCursor, cycleHighWatermark: current.cycleHighWatermark,
+                    lastScannedSequence: current.lastScannedSequence,
+                    appliedSnapshotId: current.appliedSnapshotId, appliedPageDigest: current.appliedPageDigest, now });
+                current = this.read({ tenantId, workspaceId });
+            }
+            if (!current.repair)
+                throw new Error('Combined repair state is missing.');
+            if (current.repair.cursor !== previousRepairCursor) {
+                if (input.page.hasMore && current.repair.cursor === input.page.nextRepairCursor
+                    && this.pageMatches(tenantId, workspaceId, current.repair.epoch, input.page.entries, input.page.coverage)) {
+                    return finish({ state: 'duplicate', projection: current });
+                }
+                throw new Error('Combined repair cursor changed before page commit.');
+            }
+            this.stageEntries(tenantId, workspaceId, current.repair.epoch, input.page.entries, input.page.coverage);
+            if (input.page.hasMore) {
+                this.updateRepairCursor(tenantId, workspaceId, requiredText(input.page.nextRepairCursor, 'Next repair cursor'), now);
+                return finish({ state: 'staged', projection: this.read({ tenantId, workspaceId }) });
+            }
+            const staged = this.readEntries(tenantId, workspaceId, current.repair.epoch, input.page.coverage);
+            try {
+                synchronous(input.assertReadyToActivate(staged), 'Combined repair activation assertion');
+            }
+            catch (error) {
+                if (error?.code !== WORKSPACE_SYNC_V3_REPAIR_SNAPSHOT_STALE) {
+                    throw error;
+                }
+                this.upsertState({
+                    tenantId,
+                    workspaceId,
+                    owner: current.owner,
+                    epoch: current.epoch,
+                    coverage: registeredCoverage(current)?.profile || input.page.coverage,
+                    repairEpoch: null,
+                    snapshotId: null,
+                    snapshotSequence: null,
+                    expiresAt: null,
+                    resumeCursor: null,
+                    repairCursor: null,
+                    opaqueCursor: current.opaqueCursor,
+                    cycleHighWatermark: current.cycleHighWatermark,
+                    lastScannedSequence: current.lastScannedSequence,
+                    appliedSnapshotId: current.appliedSnapshotId,
+                    appliedPageDigest: current.appliedPageDigest,
+                    now,
+                });
+                this.clearEntries(tenantId, workspaceId);
+                return finish({ state: 'invalidated', projection: this.read({ tenantId, workspaceId }) });
+            }
+            synchronous(input.applySnapshot(staged), 'Combined repair snapshot callback');
+            if (input.recoveryOnly) {
+                if (current.owner !== 'v3') {
+                    throw new Error('Targeted recovery requires active combined v3 ownership.');
+                }
+                this.upsertState({ tenantId, workspaceId, owner: current.owner, epoch: current.epoch,
+                    coverage: registeredCoverage(current)?.profile || input.page.coverage,
+                    repairEpoch: null, snapshotId: null, snapshotSequence: null, expiresAt: null,
+                    resumeCursor: null, repairCursor: null, opaqueCursor: current.opaqueCursor,
+                    cycleHighWatermark: current.cycleHighWatermark,
+                    lastScannedSequence: current.lastScannedSequence,
+                    appliedSnapshotId: current.appliedSnapshotId,
+                    appliedPageDigest: current.appliedPageDigest, now });
+                this.clearEntries(tenantId, workspaceId);
+                synchronous(input.afterActivate?.(), 'Combined repair post-recovery callback');
+                return finish({ state: 'recovered', projection: this.read({ tenantId, workspaceId }) });
+            }
+            this.handoffInitiativeProjection(tenantId, workspaceId, input.page.snapshotSequence, now);
+            this.upsertState({ tenantId, workspaceId, owner: 'v3', epoch: current.repair.epoch,
+                coverage: input.page.coverage,
+                repairEpoch: null, snapshotId: null, snapshotSequence: null, expiresAt: null,
+                resumeCursor: null, repairCursor: null, opaqueCursor: input.page.resumeCursor,
+                cycleHighWatermark: input.page.snapshotSequence, lastScannedSequence: input.page.snapshotSequence,
+                appliedSnapshotId: input.page.snapshotId,
+                appliedPageDigest: fingerprintWorkspaceSyncPayload(input.page.entries), now });
+            this.clearEntries(tenantId, workspaceId);
+            synchronous(input.afterActivate?.(), 'Combined repair post-activation callback');
+            return finish({ state: 'activated', projection: this.read({ tenantId, workspaceId }) });
+        })();
+    }
+    applyFallbackRepairPage(input) {
+        const tenantId = requiredText(input.tenantId, 'Tenant id');
+        const workspaceId = requiredText(input.workspaceId, 'Workspace id');
+        const expectedEpoch = sequence(input.expectedEpoch, 'Expected projection epoch');
+        const now = timestamp(input.now, 'Fallback repair apply time');
+        validateWorkspaceSyncV3CombinedRepairPage(input.page, workspaceId, now, true);
+        const previousRepairCursor = input.previousRepairCursor == null
+            ? null : requiredText(input.previousRepairCursor, 'Previous fallback repair cursor');
+        const fallbackResumeCursor = `v2-fallback:${input.page.snapshotSequence}:${input.page.snapshotId}`;
+        const finish = (result) => {
+            synchronous(input.beforeCommit?.(result), 'Combined fallback repair pre-commit callback');
+            return result;
+        };
+        return this.db.transaction(() => {
+            this.lock(tenantId, workspaceId, now);
+            synchronous(input.beforeApply?.(), 'Combined fallback repair pre-apply callback');
+            let current = this.read({ tenantId, workspaceId });
+            const currentCoverage = registeredCoverage(current);
+            if (current.owner === 'v3' && (!currentCoverage
+                || canonicalWorkspaceSyncJson(currentCoverage.profile)
+                    !== canonicalWorkspaceSyncJson(input.page.coverage))) {
+                throw new Error('Combined fallback repair coverage does not match the persisted owner selector.');
+            }
+            if (current.owner === 'v2' && !current.repair
+                && current.epoch === (BigInt(expectedEpoch) + 1n).toString(10)
+                && currentCoverage
+                && canonicalWorkspaceSyncJson(currentCoverage.profile)
+                    === canonicalWorkspaceSyncJson(input.page.coverage)
+                && current.appliedSnapshotId === input.page.snapshotId
+                && current.appliedPageDigest === fingerprintWorkspaceSyncPayload(input.page.entries)
+                && !input.page.hasMore) {
+                return finish({ state: 'duplicate', projection: current });
+            }
+            validateWorkspaceSyncV3CombinedRepairPage(input.page, workspaceId, now);
+            if (current.owner !== 'v3' || current.epoch !== expectedEpoch) {
+                throw new Error('Combined fallback repair projection owner or epoch changed before page commit.');
+            }
+            if (BigInt(input.page.snapshotSequence) < BigInt(current.lastScannedSequence || '0')) {
+                throw new Error('Combined fallback repair snapshot predates the applied feed cursor.');
+            }
+            const sameRepair = current.repair?.snapshotId === input.page.snapshotId
+                && current.repair.snapshotSequence === input.page.snapshotSequence
+                && current.repair.expiresAt === input.page.expiresAt
+                && current.repair.resumeCursor === fallbackResumeCursor
+                && current.repair.epoch === (BigInt(expectedEpoch) + 1n).toString(10);
+            if (!sameRepair) {
+                if (previousRepairCursor !== null) {
+                    throw new Error('Combined fallback repair continuation has no matching local repair.');
+                }
+                const repairEpoch = (BigInt(current.epoch) + 1n).toString(10);
+                this.clearEntries(tenantId, workspaceId);
+                this.upsertState({ tenantId, workspaceId, owner: 'v3', epoch: current.epoch,
+                    coverage: registeredCoverage(current)?.profile || input.page.coverage,
+                    repairEpoch, snapshotId: input.page.snapshotId, snapshotSequence: input.page.snapshotSequence,
+                    expiresAt: input.page.expiresAt, resumeCursor: fallbackResumeCursor, repairCursor: null,
+                    opaqueCursor: current.opaqueCursor, cycleHighWatermark: current.cycleHighWatermark,
+                    lastScannedSequence: current.lastScannedSequence,
+                    appliedSnapshotId: current.appliedSnapshotId, appliedPageDigest: current.appliedPageDigest, now });
+                current = this.read({ tenantId, workspaceId });
+            }
+            if (!current.repair)
+                throw new Error('Combined fallback repair state is missing.');
+            if (current.repair.cursor !== previousRepairCursor) {
+                if (input.page.hasMore && current.repair.cursor === input.page.nextRepairCursor
+                    && this.pageMatches(tenantId, workspaceId, current.repair.epoch, input.page.entries, input.page.coverage)) {
+                    return finish({ state: 'duplicate', projection: current });
+                }
+                throw new Error('Combined fallback repair cursor changed before page commit.');
+            }
+            this.stageEntries(tenantId, workspaceId, current.repair.epoch, input.page.entries, input.page.coverage);
+            if (input.page.hasMore) {
+                this.updateRepairCursor(tenantId, workspaceId, requiredText(input.page.nextRepairCursor, 'Next fallback repair cursor'), now);
+                return finish({ state: 'staged', projection: this.read({ tenantId, workspaceId }) });
+            }
+            const staged = this.readEntries(tenantId, workspaceId, current.repair.epoch, input.page.coverage);
+            synchronous(input.assertReadyToRollback(staged), 'Combined fallback rollback assertion');
+            synchronous(input.applySnapshot(staged), 'Combined fallback repair snapshot callback');
+            this.reactivateInitiativeProjection(tenantId, workspaceId, now);
+            this.upsertState({ tenantId, workspaceId, owner: 'v2', epoch: current.repair.epoch,
+                coverage: currentCoverage?.profile || input.page.coverage,
+                repairEpoch: null, snapshotId: null, snapshotSequence: null, expiresAt: null,
+                resumeCursor: null, repairCursor: null, opaqueCursor: null,
+                cycleHighWatermark: null, lastScannedSequence: null,
+                appliedSnapshotId: input.page.snapshotId,
+                appliedPageDigest: fingerprintWorkspaceSyncPayload(input.page.entries), now });
+            this.clearEntries(tenantId, workspaceId);
+            return finish({ state: 'rolled-back', projection: this.read({ tenantId, workspaceId }) });
+        })();
+    }
+    applyDeltaPage(input) {
+        const tenantId = requiredText(input.tenantId, 'Tenant id');
+        const workspaceId = requiredText(input.workspaceId, 'Workspace id');
+        const epoch = sequence(input.epoch, 'Projection epoch');
+        const previousCursor = requiredText(input.previousCursor, 'Previous feed cursor');
+        const nextCursor = requiredText(input.page.nextCursor, 'Next feed cursor');
+        const now = timestamp(input.now, 'Feed apply time');
+        const finish = (result) => {
+            synchronous(input.beforeCommit?.(result), 'Combined feed pre-commit callback');
+            return result;
+        };
+        return this.db.transaction(() => {
+            this.lock(tenantId, workspaceId, now);
+            synchronous(input.beforeApply?.(), 'Combined feed pre-apply callback');
+            const current = this.read({ tenantId, workspaceId });
+            if (current.coverageRepairRequired) {
+                throw new Error('Combined projection requires an authoritative coverage repair before delta apply.');
+            }
+            if (current.owner !== 'v3' || current.epoch !== epoch || current.repair) {
+                throw new Error('Combined projection is not owned by this feed epoch.');
+            }
+            if (current.opaqueCursor === nextCursor) {
+                validateDuplicateDeltaPage(input.page, workspaceId, current);
+                const terminalNoop = previousCursor === nextCursor
+                    && input.page.hasMore === false
+                    && input.page.entries.length === 0;
+                if (!terminalNoop
+                    && current.appliedPageDigest !== fingerprintWorkspaceSyncPayload(input.page.entries)) {
+                    throw new Error('Combined duplicate feed page payload does not match the committed page.');
+                }
+                return finish({ state: 'duplicate', projection: current });
+            }
+            if (current.opaqueCursor !== previousCursor)
+                throw new Error('Combined feed cursor changed before page commit.');
+            validateDeltaPage(input.page, workspaceId, current);
+            synchronous(input.applyEntries(input.page.entries), 'Combined feed apply callback');
+            const updated = this.db.prepare(`
+                UPDATE workspace_sync_projection_state
+                SET opaque_cursor = ?, cycle_high_watermark = ?, last_scanned_sequence = ?,
+                    applied_snapshot_id = NULL, applied_page_digest = ?, updated_at = ?
+                WHERE tenant_id = ? AND workspace_id = ? AND projection_id = ?
+                  AND owner_mode = 'v3' AND epoch = ?
+            `).run(nextCursor, input.page.cycleHighWatermark, input.page.lastScannedSequence, fingerprintWorkspaceSyncPayload(input.page.entries), now, tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, epoch);
+            if (Number(updated.changes || 0) !== 1)
+                throw new Error('Combined projection state changed before commit.');
+            return finish({ state: 'applied', projection: this.read({ tenantId, workspaceId }) });
+        })();
+    }
+    readRow(tenantId, workspaceId) {
+        return this.db.prepare(`
+            SELECT projection_id, contract_version, owner_mode, CAST(epoch AS TEXT) AS epoch,
+                   coverage_profile_id, coverage_version, coverage_digest, opaque_cursor,
+                   CAST(cycle_high_watermark AS TEXT) AS cycle_high_watermark,
+                   CAST(last_scanned_sequence AS TEXT) AS last_scanned_sequence,
+                   repair_snapshot_id, repair_expires_at,
+                   CAST(repair_snapshot_sequence AS TEXT) AS repair_snapshot_sequence,
+                   CAST(repair_epoch AS TEXT) AS repair_epoch, repair_resume_cursor, repair_cursor,
+                   applied_snapshot_id, applied_page_digest
+            FROM workspace_sync_projection_state
+            WHERE tenant_id = ? AND workspace_id = ? AND projection_id = ?
+        `).get(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID);
+    }
+    mapRow(row) {
+        const registered = registeredCoverage({
+            coverageProfileId: row.coverage_profile_id,
+            coverageVersion: row.coverage_version,
+            coverageDigest: row.coverage_digest,
+        });
+        const coverageCompatibility = registered ? 'current' : classifyWorkspaceSyncV3CombinedCoverageCompat({
+            coverageProfileId: row.coverage_profile_id,
+            coverageVersion: row.coverage_version,
+            coverageDigest: row.coverage_digest,
+        });
+        if (Number(row.contract_version) !== WORKSPACE_SYNC_CONTRACT_VERSION
+            || row.projection_id !== WORKSPACE_SYNC_V3_COMBINED_STATE_ID
+            || (row.owner_mode !== 'v2' && row.owner_mode !== 'v3')
+            || coverageCompatibility === 'invalid') {
+            throw new Error('Combined projection state is invalid.');
+        }
+        const repairEpoch = row.repair_epoch == null ? null : sequence(row.repair_epoch, 'Repair epoch');
+        return { coverageId: WORKSPACE_SYNC_V3_COMBINED_STATE_ID, owner: row.owner_mode, epoch: sequence(row.epoch, 'Projection epoch'),
+            coverageProfileId: requiredText(row.coverage_profile_id, 'Coverage profile id'),
+            coverageVersion: Number(row.coverage_version),
+            coverageDigest: requiredText(row.coverage_digest, 'Coverage digest'),
+            opaqueCursor: row.opaque_cursor == null ? null : String(row.opaque_cursor),
+            cycleHighWatermark: row.cycle_high_watermark == null ? null : sequence(row.cycle_high_watermark, 'Cycle high watermark'),
+            lastScannedSequence: row.last_scanned_sequence == null ? null : sequence(row.last_scanned_sequence, 'Last scanned sequence'),
+            appliedSnapshotId: row.applied_snapshot_id == null ? null : requiredText(row.applied_snapshot_id, 'Applied snapshot id'),
+            appliedPageDigest: row.applied_page_digest == null ? null : requiredText(row.applied_page_digest, 'Applied page digest'),
+            coverageRepairRequired: coverageCompatibility === 'upgrade-required',
+            repair: repairEpoch == null ? null : { epoch: repairEpoch,
+                snapshotId: requiredText(row.repair_snapshot_id, 'Repair snapshot id'),
+                snapshotSequence: sequence(row.repair_snapshot_sequence, 'Repair snapshot sequence'),
+                expiresAt: timestamp(row.repair_expires_at, 'Repair expiry'),
+                resumeCursor: requiredText(row.repair_resume_cursor, 'Repair resume cursor'),
+                cursor: row.repair_cursor == null ? null : String(row.repair_cursor) } };
+    }
+    upsertState(input) {
+        const profile = input.coverage;
+        this.db.prepare(`
+            INSERT INTO workspace_sync_projection_state (
+                tenant_id, workspace_id, projection_id, contract_version, owner_mode, epoch,
+                coverage_profile_id, coverage_version, coverage_digest, opaque_cursor,
+                cycle_high_watermark, last_scanned_sequence, repair_snapshot_id, repair_expires_at,
+                repair_snapshot_sequence, repair_epoch, repair_resume_cursor, repair_cursor,
+                applied_snapshot_id, applied_page_digest, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (tenant_id, workspace_id, projection_id) DO UPDATE SET
+                contract_version = excluded.contract_version, owner_mode = excluded.owner_mode, epoch = excluded.epoch,
+                coverage_profile_id = excluded.coverage_profile_id, coverage_version = excluded.coverage_version,
+                coverage_digest = excluded.coverage_digest, opaque_cursor = excluded.opaque_cursor,
+                cycle_high_watermark = excluded.cycle_high_watermark, last_scanned_sequence = excluded.last_scanned_sequence,
+                repair_snapshot_id = excluded.repair_snapshot_id, repair_expires_at = excluded.repair_expires_at,
+                repair_snapshot_sequence = excluded.repair_snapshot_sequence, repair_epoch = excluded.repair_epoch,
+                repair_resume_cursor = excluded.repair_resume_cursor, repair_cursor = excluded.repair_cursor,
+                applied_snapshot_id = excluded.applied_snapshot_id,
+                applied_page_digest = excluded.applied_page_digest,
+                updated_at = excluded.updated_at
+        `).run(input.tenantId, input.workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, WORKSPACE_SYNC_CONTRACT_VERSION, input.owner, input.epoch, profile.coverageProfileId, profile.coverageVersion, profile.coverageDigest, input.opaqueCursor, input.cycleHighWatermark, input.lastScannedSequence, input.snapshotId, input.expiresAt, input.snapshotSequence, input.repairEpoch, input.resumeCursor, input.repairCursor, input.appliedSnapshotId, input.appliedPageDigest, input.now);
+    }
+    stageEntries(tenantId, workspaceId, epoch, entries, profile) {
+        const start = this.entryCount(tenantId, workspaceId, epoch);
+        const prior = this.readLastEntry(tenantId, workspaceId, epoch, profile);
+        if (prior && entries[0] && entryOrder(entries[0], profile) <= entryOrder(prior, profile)) {
+            throw new Error('Combined repair page did not advance beyond staged entries.');
+        }
+        const insert = this.db.prepare(`
+            INSERT INTO workspace_sync_coverage_repair_entries (
+                tenant_id, workspace_id, coverage_id, epoch, entry_index, projection_id, domain,
+                entity_id, sequence, mutation_kind, entity_revision, lifecycle_revision,
+                canonical_fingerprint, payload_fingerprint, payload_json, occurred_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `);
+        entries.forEach((entry, index) => insert.run(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, epoch, start + index, entry.projection, entry.domain, entry.entityId, entry.sequence, entry.mutationKind, entry.entityRevision, entry.lifecycleRevision, entry.canonicalFingerprint ?? null, entry.payloadFingerprint, canonicalWorkspaceSyncJson(entry.payload), entry.occurredAt));
+    }
+    readEntries(tenantId, workspaceId, epoch, profile) {
+        const rows = this.db.prepare(`
+            SELECT entry_index, projection_id, domain, entity_id, CAST(sequence AS TEXT) AS sequence,
+                   mutation_kind, CAST(entity_revision AS TEXT) AS entity_revision,
+                   CAST(lifecycle_revision AS TEXT) AS lifecycle_revision, canonical_fingerprint, payload_fingerprint,
+                   payload_json, occurred_at
+            FROM workspace_sync_coverage_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND coverage_id = ? AND epoch = ?
+            ORDER BY entry_index ASC
+        `).all(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, epoch);
+        return this.mapEntryRows(rows, 0, profile);
+    }
+    mapEntryRows(rows, expectedStart, profile) {
+        const registered = registeredCoverage(profile);
+        if (!registered)
+            throw new Error('Combined repair coverage is not registered.');
+        return rows.map((row, index) => {
+            if (Number(row.entry_index) !== expectedStart + index) {
+                throw new Error('Combined repair staged entry order is incomplete.');
+            }
+            let payload;
+            try {
+                payload = JSON.parse(String(row.payload_json || ''));
+            }
+            catch {
+                throw new Error('Combined repair staged payload is malformed.');
+            }
+            const entry = {
+                projection: String(row.projection_id || ''),
+                domain: String(row.domain || ''), entityId: String(row.entity_id || ''),
+                sequence: sequence(row.sequence, 'Staged entry sequence'), mutationKind: String(row.mutation_kind || ''),
+                entityRevision: sequence(row.entity_revision, 'Staged entity revision'),
+                lifecycleRevision: sequence(row.lifecycle_revision, 'Staged lifecycle revision'),
+                ...(row.canonical_fingerprint
+                    ? { canonicalFingerprint: String(row.canonical_fingerprint) }
+                    : {}),
+                payloadFingerprint: String(row.payload_fingerprint || ''), payload,
+                occurredAt: timestamp(row.occurred_at, 'Staged occurrence time'),
+            };
+            registered.validateEntry(entry);
+            return entry;
+        });
+    }
+    pageMatches(tenantId, workspaceId, epoch, entries, profile) {
+        if (entries.length === 0)
+            return true;
+        const rows = this.db.prepare(`
+            SELECT entry_index, projection_id, domain, entity_id, CAST(sequence AS TEXT) AS sequence,
+                   mutation_kind, CAST(entity_revision AS TEXT) AS entity_revision,
+                   CAST(lifecycle_revision AS TEXT) AS lifecycle_revision, canonical_fingerprint, payload_fingerprint,
+                   payload_json, occurred_at
+            FROM workspace_sync_coverage_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND coverage_id = ? AND epoch = ?
+            ORDER BY entry_index DESC
+            LIMIT ?
+        `).all(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, epoch, entries.length);
+        rows.reverse();
+        if (rows.length !== entries.length)
+            return false;
+        const staged = this.mapEntryRows(rows, Number(rows[0].entry_index), profile);
+        return canonicalWorkspaceSyncJson(staged) === canonicalWorkspaceSyncJson(entries);
+    }
+    readLastEntry(tenantId, workspaceId, epoch, profile) {
+        const row = this.db.prepare(`
+            SELECT entry_index, projection_id, domain, entity_id, CAST(sequence AS TEXT) AS sequence,
+                   mutation_kind, CAST(entity_revision AS TEXT) AS entity_revision,
+                   CAST(lifecycle_revision AS TEXT) AS lifecycle_revision, canonical_fingerprint, payload_fingerprint,
+                   payload_json, occurred_at
+            FROM workspace_sync_coverage_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND coverage_id = ? AND epoch = ?
+            ORDER BY entry_index DESC
+            LIMIT 1
+        `).get(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, epoch);
+        return row ? this.mapEntryRows([row], Number(row.entry_index), profile)[0] : null;
+    }
+    entryCount(tenantId, workspaceId, epoch) {
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS count FROM workspace_sync_coverage_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND coverage_id = ? AND epoch = ?
+        `).get(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID, epoch);
+        return Number(row?.count || 0);
+    }
+    updateRepairCursor(tenantId, workspaceId, cursor, now) {
+        const result = this.db.prepare(`
+            UPDATE workspace_sync_projection_state SET repair_cursor = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND projection_id = ? AND repair_epoch IS NOT NULL
+        `).run(cursor, now, tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID);
+        if (Number(result.changes || 0) !== 1)
+            throw new Error('Combined repair state changed before cursor commit.');
+    }
+    clearEntries(tenantId, workspaceId) {
+        this.db.prepare(`DELETE FROM workspace_sync_coverage_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND coverage_id = ?`)
+            .run(tenantId, workspaceId, WORKSPACE_SYNC_V3_COMBINED_STATE_ID);
+    }
+    handoffInitiativeProjection(tenantId, workspaceId, combinedSnapshotSequence, now) {
+        const initiative = new WorkspaceSyncV3ProjectionStateStore(this.db).read({ tenantId, workspaceId });
+        if (initiative.repair) {
+            throw new Error('Combined projection cannot take ownership while the initiative projection is repairing.');
+        }
+        if (initiative.owner === 'v2')
+            return;
+        if (initiative.coverageProfileId !== WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageProfileId
+            || initiative.coverageVersion !== WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageVersion
+            || initiative.coverageDigest !== WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageDigest
+            || !initiative.opaqueCursor
+            || initiative.cycleHighWatermark == null
+            || initiative.lastScannedSequence == null
+            || BigInt(initiative.lastScannedSequence) > BigInt(initiative.cycleHighWatermark)
+            || BigInt(initiative.lastScannedSequence) > BigInt(combinedSnapshotSequence)) {
+            throw new Error('Combined projection cannot supersede the current initiative projection state.');
+        }
+        const nextEpoch = (BigInt(initiative.epoch) + 1n).toString(10);
+        const updated = this.db.prepare(`
+            UPDATE workspace_sync_projection_state
+            SET owner_mode = 'v2', epoch = ?, opaque_cursor = NULL,
+                cycle_high_watermark = NULL, last_scanned_sequence = NULL,
+                repair_snapshot_sequence = NULL, repair_epoch = NULL,
+                repair_resume_cursor = NULL, repair_cursor = NULL,
+                applied_snapshot_id = NULL, applied_page_digest = NULL,
+                updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND projection_id = ?
+              AND owner_mode = 'v3' AND epoch = ?
+        `).run(nextEpoch, now, tenantId, workspaceId, INITIATIVE_FULL_V1_PROJECTION, initiative.epoch);
+        if (Number(updated.changes || 0) !== 1) {
+            throw new Error('Initiative projection ownership changed before combined activation.');
+        }
+        this.db.prepare(`
+            DELETE FROM workspace_sync_projection_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND projection_id = ?
+        `).run(tenantId, workspaceId, INITIATIVE_FULL_V1_PROJECTION);
+    }
+    reactivateInitiativeProjection(tenantId, workspaceId, now) {
+        const initiative = new WorkspaceSyncV3ProjectionStateStore(this.db).read({ tenantId, workspaceId });
+        if (initiative.owner !== 'v2' || initiative.repair) {
+            throw new Error('Combined rollback requires an inactive initiative projection.');
+        }
+        const nextEpoch = (BigInt(initiative.epoch) + 1n).toString(10);
+        this.db.prepare(`
+            INSERT INTO workspace_sync_projection_state (
+                tenant_id, workspace_id, projection_id, contract_version, owner_mode, epoch,
+                coverage_profile_id, coverage_version, coverage_digest, opaque_cursor,
+                cycle_high_watermark, last_scanned_sequence, repair_snapshot_id, repair_expires_at,
+                repair_snapshot_sequence, repair_epoch, repair_resume_cursor, repair_cursor,
+                applied_snapshot_id, applied_page_digest, updated_at
+            ) VALUES (?, ?, ?, ?, 'v2', ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?)
+            ON CONFLICT (tenant_id, workspace_id, projection_id) DO UPDATE SET
+                contract_version = excluded.contract_version, owner_mode = 'v2', epoch = excluded.epoch,
+                coverage_profile_id = excluded.coverage_profile_id,
+                coverage_version = excluded.coverage_version, coverage_digest = excluded.coverage_digest,
+                opaque_cursor = NULL, cycle_high_watermark = NULL, last_scanned_sequence = NULL,
+                repair_snapshot_id = NULL, repair_expires_at = NULL, repair_snapshot_sequence = NULL,
+                repair_epoch = NULL, repair_resume_cursor = NULL, repair_cursor = NULL,
+                applied_snapshot_id = NULL, applied_page_digest = NULL, updated_at = excluded.updated_at
+        `).run(tenantId, workspaceId, INITIATIVE_FULL_V1_PROJECTION, WORKSPACE_SYNC_CONTRACT_VERSION, nextEpoch, WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageProfileId, WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageVersion, WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageDigest, now);
+        this.db.prepare(`
+            DELETE FROM workspace_sync_projection_repair_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND projection_id = ?
+        `).run(tenantId, workspaceId, INITIATIVE_FULL_V1_PROJECTION);
+    }
+    lock(tenantId, workspaceId, now) {
+        const lock = this.db.prepare(`
+            INSERT INTO workspace_sync_domain_locks (tenant_id, workspace_id, domain, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT (tenant_id, workspace_id, domain) DO UPDATE SET updated_at = excluded.updated_at
+        `);
+        lock.run(tenantId, workspaceId, WORKSPACE_SYNC_INITIATIVE_PROJECTION_LOCK, now);
+        lock.run(tenantId, workspaceId, WORKSPACE_SYNC_COMBINED_PROJECTION_LOCK, now);
+    }
+}