@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/v3/workspaceSyncV3FeedOrchestrator.js

@@ -0,0 +1,228 @@
+import { applyLocalWorkspaceSyncV3Projection, getLocalWorkspaceSyncV3Projection, pullWorkspaceInitiativeRepair, pullWorkspaceSyncV3Feed, } from '../cloudSyncApi.js';
+import { isWorkspaceSyncV3ClientCoverage, validateWorkspaceSyncV3ClientEntry } from './workspaceSyncV3FeedClientContract.js';
+const DEFAULT_DEPENDENCIES = {
+    getLocalProjection: getLocalWorkspaceSyncV3Projection,
+    applyLocalProjection: applyLocalWorkspaceSyncV3Projection,
+    pullFeed: pullWorkspaceSyncV3Feed,
+    pullInitiativeRepair: pullWorkspaceInitiativeRepair,
+};
+function projectionFromRead(response, workspaceId) {
+    const projection = response.data?.projection;
+    if (!response.ok || response.data?.success !== true || response.data?.contractVersion !== 3
+        || response.data?.workspaceId !== workspaceId || !projection
+        || (projection.owner !== 'v2' && projection.owner !== 'v3') || !/^\d+$/.test(projection.epoch))
+        return null;
+    return projection;
+}
+function projectionFromApply(response) {
+    return response.data?.result?.projection || response.data?.projection || null;
+}
+function transientResult(response, owner, fallback) {
+    return { kind: 'transient-failure', status: response.status, retryAfterMs: response.retryAfterMs,
+        error: String(response.data?.error || fallback), excludeInitiativesFromV2: owner === 'v3' };
+}
+function isTransientStatus(status) {
+    return status === 0 || status === 429 || status >= 500;
+}
+function validateRepair(response, workspaceId) {
+    const data = response.data;
+    const coverage = data.coverage;
+    const repair = data?.repair;
+    if (response.status !== 409 || data?.workspaceId !== workspaceId || data?.protocolVersion !== 3
+        || data.legacyInitiativePushDisabled !== true
+        || (data.code !== 'CURSOR_EXPIRED' && data.code !== 'COVERAGE_CHANGED') || !repair
+        || !isWorkspaceSyncV3ClientCoverage(coverage)
+        || repair.mode !== 'authoritative-covered-projection-snapshot'
+        || !/^\d+$/.test(String(repair.snapshotSequence || '')) || !Array.isArray(repair.entries)
+        || typeof repair.hasMore !== 'boolean' || repair.hasMore !== Boolean(repair.nextRepairCursor)
+        || typeof repair.resumeCursor !== 'string' || !repair.resumeCursor)
+        return null;
+    try {
+        repair.entries.forEach(validateWorkspaceSyncV3ClientEntry);
+    }
+    catch {
+        return null;
+    }
+    return repair;
+}
+function validateDelta(response, workspaceId) {
+    const page = response.data;
+    if (!response.ok || page?.protocolVersion !== 3 || page?.workspaceId !== workspaceId
+        || page.legacyInitiativePushDisabled !== true
+        || !Array.isArray(page.entries) || typeof page.nextCursor !== 'string' || !page.nextCursor
+        || typeof page.hasMore !== 'boolean'
+        || !isWorkspaceSyncV3ClientCoverage(page.coverage)
+        || !/^\d+$/.test(String(page.cycleHighWatermark || ''))
+        || !/^\d+$/.test(String(page.lastScannedSequence || ''))
+        || !page.diagnostics || page.diagnostics.coveredCount !== page.entries.length
+        || page.diagnostics.scannedCount < page.entries.length)
+        return null;
+    try {
+        page.entries.forEach(validateWorkspaceSyncV3ClientEntry);
+    }
+    catch {
+        return null;
+    }
+    return page;
+}
+async function runV2InitiativeRepair(input) {
+    let projection = input.projection;
+    let cursor = projection.repair?.cursor || null;
+    const seen = new Set();
+    while (true) {
+        const page = await input.dependencies.pullInitiativeRepair(input.resolveCloudAuthUrl, { workspaceId: input.workspaceId, cursor, limit: 100 });
+        if (!page.ok) {
+            if (page.status === 401)
+                return { kind: 'auth-failure', status: 401, excludeInitiativesFromV2: false };
+            return transientResult(page, 'v2', 'Initiative fallback repair failed.');
+        }
+        const data = page.data;
+        if (data?.success !== true || data.workspaceId !== input.workspaceId || !/^\d+$/.test(String(data.snapshotSequence || ''))
+            || !Array.isArray(data.entries)
+            || typeof data.hasMore !== 'boolean' || data.hasMore !== Boolean(data.nextRepairCursor)) {
+            return { kind: 'transient-failure', status: 502, error: 'Initiative fallback repair returned an invalid page.',
+                excludeInitiativesFromV2: false };
+        }
+        const applied = await input.dependencies.applyLocalProjection(input.workspaceId, {
+            kind: 'fallback-repair', epoch: projection.epoch, previousCursor: cursor,
+            page: { snapshotSequence: String(data.snapshotSequence), entries: data.entries,
+                hasMore: data.hasMore, nextRepairCursor: data.nextRepairCursor || null },
+        });
+        const updated = projectionFromApply(applied);
+        if (!applied.ok || !updated)
+            return transientResult(applied, 'v3', 'Initiative fallback repair could not be staged locally.');
+        projection = updated;
+        if (!data.hasMore) {
+            return projection.owner === 'v2'
+                ? { kind: 'v2-fallback', excludeInitiativesFromV2: false }
+                : { kind: 'transient-failure', status: 502, error: 'Initiative fallback repair did not switch ownership.',
+                    excludeInitiativesFromV2: true };
+        }
+        const nextCursor = String(data.nextRepairCursor || '');
+        if (!nextCursor || nextCursor === cursor || seen.has(nextCursor)) {
+            return { kind: 'transient-failure', status: 502, error: 'Initiative fallback repair made no progress.',
+                excludeInitiativesFromV2: false };
+        }
+        seen.add(nextCursor);
+        cursor = nextCursor;
+    }
+}
+async function rollbackAndRepair(input) {
+    return runV2InitiativeRepair(input);
+}
+async function rollbackForV2Retry(input) {
+    const rollback = await input.dependencies.applyLocalProjection(input.workspaceId, { kind: 'rollback', epoch: input.projection.epoch });
+    const projection = projectionFromApply(rollback);
+    if (!rollback.ok || !projection || projection.owner !== 'v2') {
+        return transientResult(rollback, input.projection.owner, 'Initiative activation rollback is not ready.');
+    }
+    return { kind: 'transient-failure', status: 409,
+        error: 'Local initiative changes must complete v2 synchronization before v3 activation can retry.',
+        excludeInitiativesFromV2: false };
+}
+export async function runWorkspaceSyncV3InitiativeProjectionCycle(input) {
+    const baseDependencies = { ...DEFAULT_DEPENDENCIES, ...input.dependencies };
+    const dependencies = {
+        ...baseDependencies,
+        applyLocalProjection: async (...args) => {
+            const response = await baseDependencies.applyLocalProjection(...args);
+            if (response.ok && response.data?.success !== false && 'page' in args[1]) {
+                input.onChangesApplied?.(args[1].page.entries.length);
+            }
+            return response;
+        },
+    };
+    const local = await dependencies.getLocalProjection(input.workspaceId);
+    const initial = projectionFromRead(local, input.workspaceId);
+    if (!initial)
+        return transientResult(local, 'v2', 'Local initiative projection state is unavailable.');
+    if (initial.owner === 'v3' && initial.repair?.resumeCursor.startsWith('v2-fallback:')) {
+        return rollbackAndRepair({ ...input, projection: initial, dependencies });
+    }
+    if (!input.activationEnabled) {
+        if (initial.owner === 'v3')
+            return rollbackAndRepair({ ...input, projection: initial, dependencies });
+        if (initial.repair)
+            return rollbackForV2Retry({ workspaceId: input.workspaceId, projection: initial, dependencies });
+        return { kind: 'v2-fallback', excludeInitiativesFromV2: false };
+    }
+    let projection = initial;
+    while (projection.owner === 'v2' || projection.repair) {
+        const feed = await dependencies.pullFeed(input.resolveCloudAuthUrl, {
+            workspaceId: input.workspaceId,
+            repairCursor: projection.repair?.cursor || null,
+            limit: 100,
+        });
+        if (feed.status === 401)
+            return { kind: 'auth-failure', status: 401, excludeInitiativesFromV2: false };
+        if (feed.status === 404 || (feed.status !== 409 && !isTransientStatus(feed.status))) {
+            return projection.owner === 'v3'
+                ? rollbackAndRepair({ ...input, projection, dependencies })
+                : rollbackForV2Retry({ workspaceId: input.workspaceId, projection, dependencies });
+        }
+        if (isTransientStatus(feed.status))
+            return transientResult(feed, 'v2', 'Workspace sync v3 feed is temporarily unavailable.');
+        const repair = validateRepair(feed, input.workspaceId);
+        if (!repair)
+            return projection.owner === 'v3'
+                ? rollbackAndRepair({ ...input, projection, dependencies })
+                : rollbackForV2Retry({ workspaceId: input.workspaceId, projection, dependencies });
+        const applied = await dependencies.applyLocalProjection(input.workspaceId, { kind: 'repair', epoch: projection.epoch,
+            previousCursor: projection.repair?.cursor || null, page: repair });
+        const updated = projectionFromApply(applied);
+        if (!applied.ok || !updated) {
+            return rollbackForV2Retry({ workspaceId: input.workspaceId, projection, dependencies });
+        }
+        const priorRepairCursor = projection.repair?.cursor || null;
+        projection = updated;
+        if (projection.owner === 'v2' && projection.repair?.cursor === priorRepairCursor) {
+            return { kind: 'transient-failure', status: 502, error: 'Initiative repair made no local progress.',
+                excludeInitiativesFromV2: false };
+        }
+    }
+    while (projection.owner === 'v3') {
+        const feed = await dependencies.pullFeed(input.resolveCloudAuthUrl, { workspaceId: input.workspaceId, cursor: projection.opaqueCursor, limit: 100 });
+        if (feed.status === 401)
+            return { kind: 'auth-failure', status: 401, excludeInitiativesFromV2: true };
+        if (feed.status === 404 || (feed.status !== 409 && !feed.ok && !isTransientStatus(feed.status))) {
+            return rollbackAndRepair({ ...input, projection, dependencies });
+        }
+        if (isTransientStatus(feed.status))
+            return transientResult(feed, 'v3', 'Workspace sync v3 feed is temporarily unavailable.');
+        if (feed.status === 409) {
+            const repair = validateRepair(feed, input.workspaceId);
+            if (!repair)
+                return rollbackAndRepair({ ...input, projection, dependencies });
+            const applied = await dependencies.applyLocalProjection(input.workspaceId, { kind: 'repair', epoch: projection.epoch,
+                previousCursor: null, page: repair });
+            const updated = projectionFromApply(applied);
+            if (!applied.ok || !updated)
+                return transientResult(applied, 'v3', 'Initiative repair could not be applied locally.');
+            projection = updated;
+            if (projection.repair) {
+                return runWorkspaceSyncV3InitiativeProjectionCycle({ ...input, dependencies: baseDependencies });
+            }
+            continue;
+        }
+        const page = validateDelta(feed, input.workspaceId);
+        if (!page || !projection.opaqueCursor)
+            return rollbackAndRepair({ ...input, projection, dependencies });
+        const applied = await dependencies.applyLocalProjection(input.workspaceId, { kind: 'delta', epoch: projection.epoch,
+            previousCursor: projection.opaqueCursor, page });
+        const updated = projectionFromApply(applied);
+        if (!applied.ok || !updated)
+            return transientResult(applied, 'v3', 'Workspace sync v3 feed could not be applied locally.');
+        if (updated.owner !== 'v3' || updated.repair || updated.opaqueCursor !== page.nextCursor) {
+            return { kind: 'transient-failure', status: 502, error: 'Workspace sync v3 feed did not commit its exact cursor.',
+                excludeInitiativesFromV2: true };
+        }
+        if (!page.hasMore)
+            return { kind: 'v3-active', excludeInitiativesFromV2: true };
+        if (updated.opaqueCursor === projection.opaqueCursor) {
+            return { kind: 'transient-failure', status: 502, error: 'Workspace sync v3 feed made no local progress.',
+                excludeInitiativesFromV2: true };
+        }
+        projection = updated;
+    }
+    return { kind: 'v2-fallback', excludeInitiativesFromV2: false };
+}

package/dist/sync/v3/workspaceSyncV3FeedProfile.d.ts

@@ -0,0 +1,32 @@
+export type WorkspaceSyncV3ProjectionDescriptor = 'initiative/full-v1' | 'workstream/full-v1' | 'task/root-v1' | 'task-comments/full-v1' | 'task-checklist/full-v1' | 'task-attachment-links/full-v1' | 'entity-event/full-v1' | 'task-relationship/full-v1' | 'taxonomy/full-v1' | 'workflow-published-definition/full-v2' | 'workflow-execution/root-v1' | 'workflow-execution-event/full-v1' | 'workstream-task-order/full-v1';
+export type WorkspaceSyncV3JournalProjectionDescriptor = WorkspaceSyncV3ProjectionDescriptor | 'task/taxonomy-remap-v1';
+export interface WorkspaceSyncV3ProjectionCoverageDescriptor {
+    projectionId: WorkspaceSyncV3ProjectionDescriptor;
+    domain: string;
+    schemaVersion: number;
+    mutationKinds: readonly string[];
+    fields?: readonly string[];
+    dependencies?: readonly WorkspaceSyncV3ProjectionDescriptor[];
+    operationAtomic: true;
+}
+export interface WorkspaceSyncV3CoverageProfile {
+    coverageProfileId: string;
+    coverageVersion: number;
+    projections: readonly WorkspaceSyncV3ProjectionCoverageDescriptor[];
+    coverageDigest: string;
+}
+export declare const WORKSPACE_SYNC_V3_COVERAGE_PROFILE: Readonly<{
+    projections: readonly [Readonly<{
+        projectionId: "initiative/full-v1";
+        domain: "initiative";
+        schemaVersion: 1;
+        mutationKinds: readonly string[];
+        fields: readonly string[];
+        dependencies: readonly never[];
+        operationAtomic: true;
+    }>];
+    coverageDigest: string;
+    coverageProfileId: "covered-metadata";
+    coverageVersion: 1;
+}>;
+export declare function resolveWorkspaceSyncV3Projection(domain: string): WorkspaceSyncV3ProjectionDescriptor | null;

package/dist/sync/v3/workspaceSyncV3FeedProfile.js

@@ -0,0 +1,21 @@
+import { createHash } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+const projections = Object.freeze([Object.freeze({
+        projectionId: 'initiative/full-v1',
+        domain: 'initiative',
+        schemaVersion: 1,
+        mutationKinds: Object.freeze(['create', 'metadata-update', 'append-comment', 'archive', 'unarchive']),
+        fields: Object.freeze(['id', 'referenceNumber', 'referenceLabel', 'title', 'description', 'ownerId', 'comments', 'attachments', 'order', 'createdAt', 'updatedAt', 'isArchived']),
+        dependencies: Object.freeze([]),
+        operationAtomic: true,
+    })]);
+const identity = { coverageProfileId: 'covered-metadata', coverageVersion: 1, projections };
+export const WORKSPACE_SYNC_V3_COVERAGE_PROFILE = Object.freeze({
+    ...identity,
+    projections,
+    coverageDigest: createHash('sha256').update(canonicalWorkspaceSyncJson(identity)).digest('hex'),
+});
+const byDomain = Object.freeze({ initiative: 'initiative/full-v1' });
+export function resolveWorkspaceSyncV3Projection(domain) {
+    return byDomain[domain] || null;
+}

package/dist/sync/v3/workspaceSyncV3InitiativeLocalApply.d.ts

@@ -0,0 +1,36 @@
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import type { WorkspaceSyncV3FeedPage } from './workspaceSyncV3Feed.js';
+import { WorkspaceSyncV3ProjectionStateStore, type WorkspaceSyncV3InitiativeApplyTransactionHooks, type WorkspaceSyncV3InitiativeFallbackRepairApplyPage, type WorkspaceSyncV3InitiativeRepairApplyPage } from './workspaceSyncV3ProjectionState.js';
+export declare function applyWorkspaceSyncV3InitiativeRepairPage(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    expectedEpoch: string;
+    previousRepairCursor: string | null;
+    page: WorkspaceSyncV3InitiativeRepairApplyPage;
+    now?: string;
+    transactionHooks?: WorkspaceSyncV3InitiativeApplyTransactionHooks;
+}): ReturnType<WorkspaceSyncV3ProjectionStateStore['applyRepairPage']>;
+export declare function applyWorkspaceSyncV3InitiativeDeltaPage(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    epoch: string;
+    previousCursor: string;
+    page: WorkspaceSyncV3FeedPage;
+    now?: string;
+    transactionHooks?: WorkspaceSyncV3InitiativeApplyTransactionHooks;
+}): ReturnType<WorkspaceSyncV3ProjectionStateStore['applyDeltaPage']>;
+export declare function applyWorkspaceSyncV3InitiativeFallbackRepairPage(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    expectedEpoch: string;
+    previousRepairCursor: string | null;
+    page: WorkspaceSyncV3InitiativeFallbackRepairApplyPage;
+    now?: string;
+    transactionHooks?: WorkspaceSyncV3InitiativeApplyTransactionHooks;
+}): ReturnType<WorkspaceSyncV3ProjectionStateStore['applyFallbackRepairPage']>;
+export declare function rollbackWorkspaceSyncV3InitiativeProjection(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    expectedEpoch: string;
+    now?: string;
+}): ReturnType<WorkspaceSyncV3ProjectionStateStore['switchToV2']>;

package/dist/sync/v3/workspaceSyncV3InitiativeLocalApply.js

@@ -0,0 +1,163 @@
+import { serializeInitiativeForSync } from '../planningSyncPayload.js';
+import { applyInitiativeSyncChangesWithCoexistence } from './initiativeCoexistence.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+import { WorkspaceSyncV3ProjectionStateStore, } from './workspaceSyncV3ProjectionState.js';
+function toMarkedInitiatives(entries) {
+    return new Map(entries.map((entry) => [entry.entityId, {
+            ...entry.payload,
+            durableRevision: {
+                contractVersion: 3,
+                domain: 'initiative',
+                entityId: entry.entityId,
+                mutationKind: entry.mutationKind,
+                sequence: entry.sequence,
+                entityRevision: entry.entityRevision,
+                lifecycleRevision: entry.lifecycleRevision,
+                canonicalFingerprint: entry.payloadFingerprint,
+            },
+        }]));
+}
+function notify(core, workspaceId, ids) {
+    for (const initiativeId of ids) {
+        try {
+            core.notifyDurableInitiativeCommitted(workspaceId, initiativeId);
+        }
+        catch { /* authoritative body, revision, and cursor are already committed */ }
+    }
+}
+function hasActiveInitiativeOutbox(core, tenantId, workspaceId) {
+    const row = core.getDatabaseAdapter().prepare(`
+        SELECT 1 AS active
+        FROM workspace_sync_outbox AS outbox
+        WHERE outbox.tenant_id = ? AND outbox.workspace_id = ?
+          AND outbox.status IN ('pending', 'in_flight', 'blocked')
+          AND (
+            outbox.domain = 'initiative'
+            OR EXISTS (
+                SELECT 1 FROM workspace_sync_outbox_targets AS target
+                WHERE target.tenant_id = outbox.tenant_id
+                  AND target.workspace_id = outbox.workspace_id
+                  AND target.client_id = outbox.client_id
+                  AND target.operation_id = outbox.operation_id
+                  AND target.domain = 'initiative'
+            )
+          )
+        LIMIT 1
+    `).get(tenantId, workspaceId);
+    return Number(row?.active || 0) === 1;
+}
+function applyEntries(input) {
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    const result = applyInitiativeSyncChangesWithCoexistence({
+        store, core: input.core,
+        tenantId: input.tenantId, workspaceId: input.workspaceId, direction: 'local-pull',
+        incomingInitiatives: toMarkedInitiatives(input.entries), deferNotifications: true, now: input.now,
+    });
+    const blockedIds = result.protectedIds.filter((entityId) => result.revisionStates[entityId] == null);
+    if (blockedIds.length > 0) {
+        throw new Error('Workspace sync feed page is blocked by active local initiative operations.');
+    }
+    return result.notificationIds;
+}
+export function applyWorkspaceSyncV3InitiativeRepairPage(input) {
+    const tenantId = input.core.getTenantId();
+    const workspaceId = String(input.workspaceId || '').trim();
+    const now = input.now || new Date().toISOString();
+    const stateStore = new WorkspaceSyncV3ProjectionStateStore(input.core.getDatabaseAdapter());
+    let notificationIds = [];
+    const result = stateStore.applyRepairPage({ tenantId, workspaceId, expectedEpoch: input.expectedEpoch,
+        previousRepairCursor: input.previousRepairCursor, page: input.page, now,
+        assertReadyToActivate: (entries) => {
+            if (hasActiveInitiativeOutbox(input.core, tenantId, workspaceId)) {
+                throw new Error('Initiative repair cannot activate while local initiative operations are pending.');
+            }
+            const authoritativeById = new Map(entries.map((entry) => [entry.entityId, entry]));
+            const local = input.core.listInitiatives(workspaceId);
+            const localExtras = local
+                .map((initiative) => initiative.id)
+                .filter((initiativeId) => !authoritativeById.has(initiativeId));
+            if (localExtras.length > 0) {
+                throw new Error('Initiative repair snapshot is missing local initiatives; complete v2 reconciliation before activation.');
+            }
+            for (let offset = 0; offset < local.length; offset += 100) {
+                const page = local.slice(offset, offset + 100);
+                const ownership = new Map(new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter())
+                    .listWorkspaceDomainOwnership({ tenantId, workspaceId, domain: 'initiative',
+                    entityIds: page.map((initiative) => initiative.id) })
+                    .map((entry) => [entry.entityId, entry]));
+                const divergentLegacy = page.find((initiative) => {
+                    if (ownership.get(initiative.id)?.owned)
+                        return false;
+                    return fingerprintWorkspaceSyncPayload(serializeInitiativeForSync(initiative))
+                        !== authoritativeById.get(initiative.id)?.payloadFingerprint;
+                });
+                if (divergentLegacy) {
+                    throw new Error('Initiative repair found divergent legacy local state; complete v2 reconciliation before activation.');
+                }
+            }
+        },
+        applySnapshot: (entries) => { notificationIds = applyEntries({ core: input.core, tenantId, workspaceId, entries, now }); },
+        transactionHooks: input.transactionHooks,
+    });
+    if (result.state === 'activated')
+        notify(input.core, workspaceId, notificationIds);
+    return result;
+}
+export function applyWorkspaceSyncV3InitiativeDeltaPage(input) {
+    const tenantId = input.core.getTenantId();
+    const workspaceId = String(input.workspaceId || '').trim();
+    const now = input.now || new Date().toISOString();
+    const stateStore = new WorkspaceSyncV3ProjectionStateStore(input.core.getDatabaseAdapter());
+    let notificationIds = [];
+    const result = stateStore.applyDeltaPage({ tenantId, workspaceId, epoch: input.epoch,
+        previousCursor: input.previousCursor, page: input.page, now,
+        applyEntries: (entries) => { notificationIds = applyEntries({ core: input.core, tenantId, workspaceId, entries, now }); },
+        transactionHooks: input.transactionHooks,
+    });
+    if (result.state === 'applied')
+        notify(input.core, workspaceId, notificationIds);
+    return result;
+}
+export function applyWorkspaceSyncV3InitiativeFallbackRepairPage(input) {
+    const tenantId = input.core.getTenantId();
+    const workspaceId = String(input.workspaceId || '').trim();
+    const now = input.now || new Date().toISOString();
+    const stateStore = new WorkspaceSyncV3ProjectionStateStore(input.core.getDatabaseAdapter());
+    let notificationIds = [];
+    const result = stateStore.applyFallbackRepairPage({
+        tenantId,
+        workspaceId,
+        expectedEpoch: input.expectedEpoch,
+        previousRepairCursor: input.previousRepairCursor,
+        page: input.page,
+        now,
+        assertReadyToRollback: () => {
+            if (hasActiveInitiativeOutbox(input.core, tenantId, workspaceId)) {
+                throw new Error('Initiative projection cannot roll back while local initiative operations are pending.');
+            }
+        },
+        applySnapshot: (entries) => {
+            notificationIds = applyEntries({ core: input.core, tenantId, workspaceId, entries, now });
+        },
+        transactionHooks: input.transactionHooks,
+    });
+    if (result.state === 'rolled-back')
+        notify(input.core, workspaceId, notificationIds);
+    return result;
+}
+export function rollbackWorkspaceSyncV3InitiativeProjection(input) {
+    const tenantId = input.core.getTenantId();
+    const workspaceId = String(input.workspaceId || '').trim();
+    const stateStore = new WorkspaceSyncV3ProjectionStateStore(input.core.getDatabaseAdapter());
+    return stateStore.switchToV2({
+        tenantId,
+        workspaceId,
+        expectedEpoch: input.expectedEpoch,
+        now: input.now || new Date().toISOString(),
+        assertReadyToRollback: () => {
+            if (hasActiveInitiativeOutbox(input.core, tenantId, workspaceId)) {
+                throw new Error('Initiative projection cannot roll back while local initiative operations are pending.');
+            }
+        },
+    });
+}

package/dist/sync/v3/workspaceSyncV3InitiativeRepair.d.ts

@@ -0,0 +1,33 @@
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import { type WorkspaceSyncV3FeedEntry } from './workspaceSyncV3Feed.js';
+import { type WorkspaceSyncV3FeedCursorKeyring } from './workspaceSyncV3FeedCursorKeys.js';
+export interface WorkspaceSyncV3InitiativeRepairCursor {
+    protocolVersion: 3;
+    tenantId: string;
+    workspaceId: string;
+    coverageDigest: string;
+    snapshotSequence: string;
+    afterEntityId: string;
+}
+export interface WorkspaceSyncV3InitiativeRepairPage {
+    snapshotSequence: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+    hasMore: boolean;
+    nextRepairCursor: string | null;
+    diagnostics: {
+        returnedEntries: number;
+        entriesBytes: number;
+        insertedEntities: number;
+        insertedJournalRows: number;
+    };
+}
+export declare function decodeWorkspaceSyncV3InitiativeRepairCursor(raw: string | null | undefined, keyring: WorkspaceSyncV3FeedCursorKeyring): WorkspaceSyncV3InitiativeRepairCursor | null;
+export declare function buildWorkspaceSyncV3InitiativeRepairPage(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    cursorKeyring: WorkspaceSyncV3FeedCursorKeyring;
+    cursor?: WorkspaceSyncV3InitiativeRepairCursor | null;
+    pageSize?: number;
+    maxResponseBytes?: number;
+    now?: string;
+}): WorkspaceSyncV3InitiativeRepairPage;

package/dist/sync/v3/workspaceSyncV3InitiativeRepair.js

@@ -0,0 +1,118 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { decodeCanonicalWorkspaceSyncBase64Url } from './workspaceSyncV3CursorEncoding.js';
+import { serializeInitiativeForSync } from '../planningSyncPayload.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+import { WORKSPACE_SYNC_V3_COVERAGE_PROFILE } from './workspaceSyncV3FeedProfile.js';
+import { validateWorkspaceSyncV3FeedEntry, WorkspaceSyncV3FeedOperationTooLargeError } from './workspaceSyncV3Feed.js';
+import { findWorkspaceSyncV3FeedCursorVerificationKey } from './workspaceSyncV3FeedCursorKeys.js';
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 100;
+const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+function sequence(value) {
+    const normalized = String(value ?? '').trim();
+    if (!/^\d+$/.test(normalized))
+        throw new Error('Invalid initiative repair sequence.');
+    return BigInt(normalized).toString(10);
+}
+function encodeCursor(cursor, keyring) {
+    const payload = Buffer.from(canonicalWorkspaceSyncJson(cursor), 'utf8').toString('base64url');
+    const signature = createHmac('sha256', keyring.active.secret).update(`${keyring.active.id}.${payload}`).digest('base64url');
+    return `${keyring.active.id}.${payload}.${signature}`;
+}
+export function decodeWorkspaceSyncV3InitiativeRepairCursor(raw, keyring) {
+    if (!String(raw || '').trim())
+        return null;
+    try {
+        const [keyId, payload, signature, extra] = String(raw).split('.');
+        const key = findWorkspaceSyncV3FeedCursorVerificationKey(keyring, keyId);
+        if (!keyId || !payload || !signature || extra || !key)
+            return null;
+        const expected = createHmac('sha256', key.secret).update(`${keyId}.${payload}`).digest();
+        const received = decodeCanonicalWorkspaceSyncBase64Url(signature);
+        const decodedPayload = decodeCanonicalWorkspaceSyncBase64Url(payload);
+        if (!received || !decodedPayload || received.length !== expected.length || !timingSafeEqual(received, expected))
+            return null;
+        const value = JSON.parse(decodedPayload.toString('utf8'));
+        const cursor = {
+            protocolVersion: Number(value.protocolVersion),
+            tenantId: String(value.tenantId || ''),
+            workspaceId: String(value.workspaceId || ''),
+            coverageDigest: String(value.coverageDigest || ''),
+            snapshotSequence: sequence(value.snapshotSequence),
+            afterEntityId: String(value.afterEntityId || ''),
+        };
+        if (cursor.protocolVersion !== 3 || !cursor.tenantId || !cursor.workspaceId || !cursor.afterEntityId
+            || cursor.coverageDigest !== WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageDigest)
+            return null;
+        return cursor;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildWorkspaceSyncV3InitiativeRepairPage(input) {
+    const tenantId = input.core.getTenantId();
+    const workspaceId = String(input.workspaceId || '').trim();
+    if (!workspaceId)
+        throw new Error('Workspace id is required.');
+    if (input.cursor && (input.cursor.tenantId !== tenantId || input.cursor.workspaceId !== workspaceId)) {
+        throw new Error('Initiative repair cursor scope mismatch.');
+    }
+    const db = input.core.getDatabaseAdapter();
+    return db.transaction(() => {
+        const store = new WorkspaceSyncDurabilityStore(db);
+        const all = input.core.listInitiatives(workspaceId)
+            .map((initiative) => serializeInitiativeForSync(initiative))
+            .sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+        const baseline = store.ensureInitiativeRevisionBaselines({
+            tenantId, workspaceId, now: input.now || new Date().toISOString(),
+            initiatives: all.map((initiative) => {
+                const currentPayload = initiative;
+                const activePayload = initiative.isArchived ? { ...initiative, isArchived: false } : initiative;
+                return { entityId: initiative.id, activePayload, currentPayload,
+                    currentFingerprint: fingerprintWorkspaceSyncPayload(currentPayload),
+                    occurredAt: initiative.updatedAt || initiative.createdAt, archived: Boolean(initiative.isArchived) };
+            }),
+        });
+        const snapshotSequence = input.cursor?.snapshotSequence || baseline.highWatermark;
+        const pageSize = Math.max(1, Math.min(MAX_PAGE_SIZE, Math.floor(input.pageSize || DEFAULT_PAGE_SIZE)));
+        const maxResponseBytes = Math.max(1024, Math.min(8 * 1024 * 1024, Math.floor(input.maxResponseBytes || DEFAULT_MAX_RESPONSE_BYTES)));
+        const after = input.cursor?.afterEntityId || '';
+        const eligible = all.filter((initiative) => initiative.id > after);
+        const pageItems = eligible.slice(0, pageSize);
+        const projections = new Map(store.listPlanningRevisionProjections({
+            tenantId, workspaceId, domain: 'initiative', entityIds: pageItems.map((initiative) => initiative.id),
+        }).map((projection) => [projection.entityId, projection]));
+        const entries = [];
+        let responseBytes = 2;
+        for (const payload of pageItems) {
+            const revision = projections.get(payload.id);
+            if (!revision || revision.canonicalFingerprint !== fingerprintWorkspaceSyncPayload(payload)) {
+                throw new Error(`Initiative repair revision does not match canonical state: ${payload.id}.`);
+            }
+            const entry = { sequence: revision.lastSequence, projection: 'initiative/full-v1',
+                domain: 'initiative', entityId: payload.id, mutationKind: revision.mutationKind,
+                entityRevision: revision.entityRevision, lifecycleRevision: revision.lifecycleRevision,
+                payloadFingerprint: revision.canonicalFingerprint, payload, occurredAt: revision.occurredAt };
+            validateWorkspaceSyncV3FeedEntry(entry);
+            const nextBytes = Buffer.byteLength(JSON.stringify([...entries, entry]), 'utf8');
+            if (nextBytes > maxResponseBytes) {
+                if (entries.length === 0) {
+                    throw new WorkspaceSyncV3FeedOperationTooLargeError(`Initiative repair entry ${payload.id} exceeds the repair byte limit.`);
+                }
+                break;
+            }
+            entries.push(entry);
+            responseBytes = nextBytes;
+        }
+        const hasMore = entries.length < eligible.length;
+        const lastEntityId = entries.at(-1)?.entityId || after;
+        const nextRepairCursor = hasMore ? encodeCursor({ protocolVersion: 3, tenantId, workspaceId,
+            coverageDigest: WORKSPACE_SYNC_V3_COVERAGE_PROFILE.coverageDigest, snapshotSequence: sequence(snapshotSequence),
+            afterEntityId: lastEntityId }, input.cursorKeyring) : null;
+        return { snapshotSequence: sequence(snapshotSequence), entries, hasMore, nextRepairCursor,
+            diagnostics: { returnedEntries: entries.length, entriesBytes: responseBytes, insertedEntities: baseline.insertedEntities,
+                insertedJournalRows: baseline.insertedJournalRows } };
+    })();
+}

package/dist/sync/v3/workspaceSyncV3LegacyBoundaryAttestation.d.ts

@@ -0,0 +1,10 @@
+import { type WorkspaceSyncV2ProjectionExclusion } from './workspaceSyncV2ProjectionExclusions.js';
+import { type WorkspaceSyncV3CombinedCoverageSelector } from './workspaceSyncV3CombinedWireContract.js';
+export declare function isWorkspaceSyncV3NestedLegacyFenceEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function resolveWorkspaceSyncV3RequiredCloudCoverage(env?: NodeJS.ProcessEnv): WorkspaceSyncV3CombinedCoverageSelector | null;
+export declare const resolveWorkspaceSyncV3RequiredPushCoverage: typeof resolveWorkspaceSyncV3RequiredCloudCoverage;
+export declare function resolveWorkspaceSyncV3AttestedV2Exclusions(input: {
+    coverage: unknown;
+    excludedProjections: unknown;
+    env?: NodeJS.ProcessEnv;
+}): readonly WorkspaceSyncV2ProjectionExclusion[] | null;