@taskforcehq/taskforce 0.3.324 → 0.3.327

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

@@ -0,0 +1,65 @@
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE } from './workspaceSyncV3CombinedCoverage.js';
+import { WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE } from './workspaceSyncV3NestedCoverage.js';
+import { WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_PROFILE } from './workspaceSyncV3WorkflowCoverage.js';
+import { WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_PROFILE } from './workspaceSyncV3PlanningOrderCoverage.js';
+import { type WorkspaceSyncV3FeedEntry } from './workspaceSyncV3Feed.js';
+import { type WorkspaceSyncV3FeedCursorKeyring } from './workspaceSyncV3FeedCursorKeys.js';
+export interface WorkspaceSyncV3CombinedRepairCursor {
+    protocolVersion: 3;
+    tenantId: string;
+    workspaceId: string;
+    coverageProfileId: string;
+    coverageVersion: number;
+    coverageDigest: string;
+    snapshotId: string;
+    snapshotSequence: string;
+    nextIndex: number;
+    expiresAt: string;
+}
+export interface WorkspaceSyncV3CombinedRepairPage {
+    success: true;
+    protocolVersion: 3;
+    workspaceId: string;
+    coverage: typeof WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE | typeof WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE | typeof WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_PROFILE | typeof WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_PROFILE;
+    snapshotId: string;
+    snapshotSequence: string;
+    expiresAt: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+    hasMore: boolean;
+    nextRepairCursor: string | null;
+    resumeCursor: string;
+    diagnostics: {
+        returnedEntries: number;
+        entriesBytes: number;
+        responseBytes: number;
+        materializedEntries: number;
+        insertedBaselineEntities: number;
+        insertedBaselineJournalRows: number;
+    };
+}
+export declare class WorkspaceSyncV3CombinedRepairSnapshotUnavailableError extends Error {
+    readonly code = "WORKSPACE_SYNC_V3_COMBINED_REPAIR_SNAPSHOT_UNAVAILABLE";
+    readonly statusCode = 410;
+    constructor();
+}
+export declare function decodeWorkspaceSyncV3CombinedRepairCursor(raw: string | null | undefined, keyring: WorkspaceSyncV3FeedCursorKeyring): WorkspaceSyncV3CombinedRepairCursor | null;
+export declare function decodeWorkspaceSyncV3NestedRepairCursor(raw: string | null | undefined, keyring: WorkspaceSyncV3FeedCursorKeyring): WorkspaceSyncV3CombinedRepairCursor | null;
+export declare function decodeWorkspaceSyncV3WorkflowRepairCursor(raw: string | null | undefined, keyring: WorkspaceSyncV3FeedCursorKeyring): WorkspaceSyncV3CombinedRepairCursor | null;
+export declare function decodeWorkspaceSyncV3PlanningOrderRepairCursor(raw: string | null | undefined, keyring: WorkspaceSyncV3FeedCursorKeyring): WorkspaceSyncV3CombinedRepairCursor | null;
+export declare function buildWorkspaceSyncV3CombinedRepairPage(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    cursorKeyring: WorkspaceSyncV3FeedCursorKeyring;
+    cursor?: WorkspaceSyncV3CombinedRepairCursor | null;
+    pageSize?: number;
+    maxResponseBytes?: number;
+    snapshotTtlMs?: number;
+    now?: string;
+    nestedCoverage?: boolean;
+    workflowCoverage?: boolean;
+    planningOrderCoverage?: boolean;
+}): WorkspaceSyncV3CombinedRepairPage;
+export declare function buildWorkspaceSyncV3NestedRepairPage(input: Omit<Parameters<typeof buildWorkspaceSyncV3CombinedRepairPage>[0], 'nestedCoverage' | 'workflowCoverage' | 'planningOrderCoverage'>): WorkspaceSyncV3CombinedRepairPage;
+export declare function buildWorkspaceSyncV3WorkflowRepairPage(input: Omit<Parameters<typeof buildWorkspaceSyncV3CombinedRepairPage>[0], 'nestedCoverage' | 'workflowCoverage' | 'planningOrderCoverage'>): WorkspaceSyncV3CombinedRepairPage;
+export declare function buildWorkspaceSyncV3PlanningOrderRepairPage(input: Omit<Parameters<typeof buildWorkspaceSyncV3CombinedRepairPage>[0], 'nestedCoverage' | 'workflowCoverage' | 'planningOrderCoverage'>): WorkspaceSyncV3CombinedRepairPage;

package/dist/sync/v3/workspaceSyncV3CombinedRepairMaterialization.js

@@ -0,0 +1,505 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { decodeCanonicalWorkspaceSyncBase64Url } from './workspaceSyncV3CursorEncoding.js';
+import { prepareWorkspaceSyncV3CombinedRepairSnapshot, prepareWorkspaceSyncV3NestedRepairSnapshot, prepareWorkspaceSyncV3PlanningOrderRepairSnapshot, prepareWorkspaceSyncV3WorkflowRepairSnapshot, } from './workspaceSyncV3CombinedRepairBaseline.js';
+import { validateWorkspaceSyncV3CombinedFeedEntry, WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE, } from './workspaceSyncV3CombinedCoverage.js';
+import { validateWorkspaceSyncV3NestedCoverageFeedEntry, WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE, } from './workspaceSyncV3NestedCoverage.js';
+import { validateWorkspaceSyncV3WorkflowCoverageFeedEntry, WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_PROFILE, } from './workspaceSyncV3WorkflowCoverage.js';
+import { validateWorkspaceSyncV3PlanningOrderCoverageFeedEntry, WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_PROFILE, } from './workspaceSyncV3PlanningOrderCoverage.js';
+import { createWorkspaceSyncV3FeedResumeCursor, WorkspaceSyncV3FeedOperationTooLargeError, } from './workspaceSyncV3Feed.js';
+import { findWorkspaceSyncV3FeedCursorVerificationKey, } from './workspaceSyncV3FeedCursorKeys.js';
+import { WORKSPACE_SYNC_COMBINED_PROJECTION, WORKSPACE_SYNC_CONTRACT_VERSION, } from './syncDurabilityStore.js';
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 100;
+const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+const DEFAULT_SNAPSHOT_TTL_MS = 60 * 60_000;
+const MAX_SNAPSHOT_TTL_MS = 24 * 60 * 60_000;
+const INSERT_BATCH_SIZE = 50;
+export class WorkspaceSyncV3CombinedRepairSnapshotUnavailableError extends Error {
+    code = 'WORKSPACE_SYNC_V3_COMBINED_REPAIR_SNAPSHOT_UNAVAILABLE';
+    statusCode = 410;
+    constructor() {
+        super('The combined repair snapshot is unavailable or expired.');
+    }
+}
+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 = String(value ?? '').trim();
+    const milliseconds = Date.parse(text);
+    if (!Number.isFinite(milliseconds))
+        throw new Error(`${label} is invalid.`);
+    return new Date(milliseconds).toISOString();
+}
+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}`;
+}
+function decodeRepairCursor(raw, keyring, profile) {
+    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 || ''),
+            coverageProfileId: String(value.coverageProfileId || ''),
+            coverageVersion: Number(value.coverageVersion),
+            coverageDigest: String(value.coverageDigest || ''),
+            snapshotId: String(value.snapshotId || ''),
+            snapshotSequence: sequence(value.snapshotSequence, 'Combined repair cursor snapshot sequence'),
+            nextIndex: Number(value.nextIndex),
+            expiresAt: timestamp(value.expiresAt, 'Combined repair cursor expiry'),
+        };
+        if (cursor.protocolVersion !== 3 || !cursor.tenantId || !cursor.workspaceId || !cursor.snapshotId
+            || cursor.coverageProfileId !== profile.coverageProfileId
+            || cursor.coverageVersion !== profile.coverageVersion
+            || cursor.coverageDigest !== profile.coverageDigest
+            || !Number.isSafeInteger(cursor.nextIndex) || cursor.nextIndex < 1)
+            return null;
+        return cursor;
+    }
+    catch {
+        return null;
+    }
+}
+export function decodeWorkspaceSyncV3CombinedRepairCursor(raw, keyring) {
+    return decodeRepairCursor(raw, keyring, WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE);
+}
+export function decodeWorkspaceSyncV3NestedRepairCursor(raw, keyring) {
+    return decodeRepairCursor(raw, keyring, WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE);
+}
+export function decodeWorkspaceSyncV3WorkflowRepairCursor(raw, keyring) {
+    return decodeRepairCursor(raw, keyring, WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_PROFILE);
+}
+export function decodeWorkspaceSyncV3PlanningOrderRepairCursor(raw, keyring) {
+    return decodeRepairCursor(raw, keyring, WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_PROFILE);
+}
+function repairProfile(coverage) {
+    return coverage === 'workflow'
+        ? WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_PROFILE
+        : coverage === 'planning-order'
+            ? WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_PROFILE
+            : coverage === 'nested'
+                ? WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE
+                : WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE;
+}
+function containsCurrentEntityEventInventory(input) {
+    if (input.coverage === 'combined')
+        return true;
+    const missing = input.core.getDatabaseAdapter().prepare(`
+        SELECT 1 AS missing
+        FROM entity_events event
+        WHERE event.tenant_id = ? AND event.workspace_id = ?
+          AND (
+              (event.entity_type = 'task' AND EXISTS (
+                  SELECT 1 FROM tasks task
+                  WHERE task.tenant_id = event.tenant_id
+                    AND task.workspace_id = event.workspace_id
+                    AND task.id = event.entity_id
+              ))
+              OR (event.entity_type = 'initiative' AND EXISTS (
+                  SELECT 1 FROM initiatives initiative
+                  WHERE initiative.tenant_id = event.tenant_id
+                    AND initiative.workspace_id = event.workspace_id
+                    AND initiative.id = event.entity_id
+              ))
+              OR (event.entity_type = 'workstream' AND EXISTS (
+                  SELECT 1 FROM workstreams workstream
+                  WHERE workstream.tenant_id = event.tenant_id
+                    AND workstream.workspace_id = event.workspace_id
+                    AND workstream.id = event.entity_id
+              ))
+          )
+          AND NOT EXISTS (
+              SELECT 1
+              FROM workspace_sync_repair_snapshot_entries entry
+              WHERE entry.tenant_id = event.tenant_id
+                AND entry.workspace_id = event.workspace_id
+                AND entry.snapshot_id = ?
+                AND entry.domain = 'entity-event'
+                AND entry.entity_id = event.id
+          )
+        LIMIT 1
+    `).get(input.tenantId, input.workspaceId, input.snapshotId);
+    return !missing;
+}
+function cleanupExpired(core, tenantId, workspaceId, now, excludingSnapshotId) {
+    const db = core.getDatabaseAdapter();
+    const exclusion = excludingSnapshotId ? ' AND snapshot_id <> ?' : '';
+    const args = excludingSnapshotId
+        ? [tenantId, workspaceId, now, excludingSnapshotId]
+        : [tenantId, workspaceId, now];
+    db.prepare(`
+        DELETE FROM workspace_sync_repair_snapshot_entries
+        WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id IN (
+            SELECT snapshot_id FROM workspace_sync_repair_snapshots
+            WHERE tenant_id = ? AND workspace_id = ? AND expires_at <= ?${exclusion}
+        )
+    `).run(tenantId, workspaceId, ...args);
+    db.prepare(`
+        DELETE FROM workspace_sync_repair_snapshots
+        WHERE tenant_id = ? AND workspace_id = ? AND expires_at <= ?${exclusion}
+    `).run(...args);
+}
+function persistMaterialization(input) {
+    const db = input.core.getDatabaseAdapter();
+    const snapshot = input.snapshot;
+    const snapshotId = `repair-snapshot-${randomUUID()}`;
+    const profile = repairProfile(input.coverage);
+    const provisionalExpiresAt = new Date(Date.parse(input.startedAt) + input.ttlMs).toISOString();
+    db.prepare(`
+        INSERT INTO workspace_sync_repair_snapshots (
+            tenant_id, workspace_id, snapshot_id, contract_version, coverage_profile_id,
+            coverage_version, coverage_digest, snapshot_sequence, entry_count, created_at, expires_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(input.tenantId, input.workspaceId, snapshotId, WORKSPACE_SYNC_CONTRACT_VERSION, profile.coverageProfileId, profile.coverageVersion, profile.coverageDigest, snapshot.snapshotSequence, snapshot.entries.length, input.startedAt, provisionalExpiresAt);
+    for (let offset = 0; offset < snapshot.entries.length; offset += INSERT_BATCH_SIZE) {
+        const batch = snapshot.entries.slice(offset, offset + INSERT_BATCH_SIZE);
+        const values = batch.map(() => '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').join(', ');
+        const args = [];
+        batch.forEach((entry, index) => args.push(input.tenantId, input.workspaceId, snapshotId, offset + 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));
+        db.prepare(`
+            INSERT INTO workspace_sync_repair_snapshot_entries (
+                tenant_id, workspace_id, snapshot_id, entry_index, projection_id, domain, entity_id,
+                sequence, mutation_kind, entity_revision, lifecycle_revision, canonical_fingerprint,
+                payload_fingerprint, payload_json, occurred_at
+            ) VALUES ${values}
+        `).run(...args);
+    }
+    const completedAt = input.fixedCompletionTime
+        || timestamp(new Date().toISOString(), 'Combined repair materialization completion time');
+    const expiresAt = new Date(Date.parse(completedAt) + input.ttlMs).toISOString();
+    db.prepare(`
+        UPDATE workspace_sync_repair_snapshots
+        SET created_at = ?, expires_at = ?
+        WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id = ?
+    `).run(completedAt, expiresAt, input.tenantId, input.workspaceId, snapshotId);
+    return {
+        snapshotId, snapshotSequence: snapshot.snapshotSequence, entryCount: snapshot.entries.length,
+        expiresAt, insertedBaselineEntities: input.insertedBaselineEntities,
+        insertedBaselineJournalRows: input.insertedBaselineJournalRows,
+    };
+}
+function readMetadata(input) {
+    const row = input.core.getDatabaseAdapter().prepare(`
+        SELECT snapshot_id, contract_version, coverage_profile_id, coverage_version, coverage_digest,
+               CAST(snapshot_sequence AS TEXT) AS snapshot_sequence, entry_count, expires_at
+        FROM workspace_sync_repair_snapshots
+        WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id = ?
+    `).get(input.tenantId, input.workspaceId, input.cursor.snapshotId);
+    const profile = repairProfile(input.coverage);
+    if (!row || Number(row.contract_version) !== WORKSPACE_SYNC_CONTRACT_VERSION
+        || row.coverage_profile_id !== profile.coverageProfileId
+        || Number(row.coverage_version) !== profile.coverageVersion
+        || row.coverage_digest !== profile.coverageDigest
+        || sequence(row.snapshot_sequence, 'Combined repair snapshot sequence') !== input.cursor.snapshotSequence
+        || timestamp(row.expires_at, 'Combined repair snapshot expiry') !== input.cursor.expiresAt
+        || !Number.isSafeInteger(Number(row.entry_count)) || Number(row.entry_count) < input.cursor.nextIndex
+        || Date.parse(String(row.expires_at)) <= Date.parse(input.now)
+        || !containsCurrentEntityEventInventory({
+            core: input.core,
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            snapshotId: input.cursor.snapshotId,
+            coverage: input.coverage,
+        })) {
+        throw new WorkspaceSyncV3CombinedRepairSnapshotUnavailableError();
+    }
+    return { snapshotId: input.cursor.snapshotId, snapshotSequence: input.cursor.snapshotSequence,
+        entryCount: Number(row.entry_count), expiresAt: input.cursor.expiresAt };
+}
+function readReusableMetadata(input) {
+    const profile = repairProfile(input.coverage);
+    const row = input.core.getDatabaseAdapter().prepare(`
+        SELECT s.snapshot_id, CAST(s.snapshot_sequence AS TEXT) AS snapshot_sequence,
+               s.entry_count, s.expires_at
+        FROM workspace_sync_repair_snapshots s
+        JOIN workspace_sync_projection_state p
+          ON p.tenant_id = s.tenant_id AND p.workspace_id = s.workspace_id
+         AND p.projection_id = ?
+        WHERE s.tenant_id = ? AND s.workspace_id = ?
+          AND s.contract_version = ? AND s.coverage_profile_id = ?
+          AND s.coverage_version = ? AND s.coverage_digest = ?
+          AND s.expires_at > ?
+          AND p.owner_mode = 'v3' AND p.contract_version = s.contract_version
+          AND p.coverage_profile_id = s.coverage_profile_id
+          AND p.coverage_version = s.coverage_version
+          AND p.coverage_digest = s.coverage_digest
+          AND p.updated_at < s.created_at
+          AND (SELECT COUNT(*) FROM workspace_sync_repair_snapshot_entries e
+               WHERE e.tenant_id = s.tenant_id AND e.workspace_id = s.workspace_id
+                 AND e.snapshot_id = s.snapshot_id) = s.entry_count
+          AND (s.entry_count = 0 OR (
+              (SELECT MIN(e.entry_index) FROM workspace_sync_repair_snapshot_entries e
+               WHERE e.tenant_id = s.tenant_id AND e.workspace_id = s.workspace_id
+                 AND e.snapshot_id = s.snapshot_id) = 0
+              AND
+              (SELECT MAX(e.entry_index) FROM workspace_sync_repair_snapshot_entries e
+               WHERE e.tenant_id = s.tenant_id AND e.workspace_id = s.workspace_id
+                 AND e.snapshot_id = s.snapshot_id) = s.entry_count - 1
+          ))
+        ORDER BY s.created_at DESC, s.snapshot_id DESC
+        LIMIT 1
+    `).get(WORKSPACE_SYNC_COMBINED_PROJECTION, input.tenantId, input.workspaceId, WORKSPACE_SYNC_CONTRACT_VERSION, profile.coverageProfileId, profile.coverageVersion, profile.coverageDigest, input.now);
+    if (!row)
+        return null;
+    const entryCount = Number(row.entry_count);
+    if (!Number.isSafeInteger(entryCount) || entryCount < 0)
+        return null;
+    if (!containsCurrentEntityEventInventory({
+        core: input.core,
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+        snapshotId: String(row.snapshot_id),
+        coverage: input.coverage,
+    }))
+        return null;
+    return {
+        snapshotId: String(row.snapshot_id),
+        snapshotSequence: sequence(row.snapshot_sequence, 'Combined repair snapshot sequence'),
+        entryCount,
+        expiresAt: timestamp(row.expires_at, 'Combined repair snapshot expiry'),
+    };
+}
+function mapEntry(row, coverage) {
+    let payload;
+    try {
+        payload = JSON.parse(String(row.payload_json || ''));
+    }
+    catch {
+        throw new Error('Combined repair materialized payload is malformed.');
+    }
+    const entry = {
+        sequence: sequence(row.sequence, 'Combined repair entry sequence'),
+        projection: String(row.projection_id || ''),
+        domain: String(row.domain || ''), entityId: String(row.entity_id || ''),
+        mutationKind: String(row.mutation_kind || ''),
+        entityRevision: sequence(row.entity_revision, 'Combined repair entity revision'),
+        lifecycleRevision: sequence(row.lifecycle_revision, 'Combined repair lifecycle revision'),
+        ...(row.canonical_fingerprint ? { canonicalFingerprint: String(row.canonical_fingerprint) } : {}),
+        payloadFingerprint: String(row.payload_fingerprint || ''), payload,
+        occurredAt: timestamp(row.occurred_at, 'Combined repair occurrence time'),
+    };
+    (coverage === 'workflow'
+        ? validateWorkspaceSyncV3WorkflowCoverageFeedEntry
+        : coverage === 'planning-order'
+            ? validateWorkspaceSyncV3PlanningOrderCoverageFeedEntry
+            : coverage === 'nested'
+                ? validateWorkspaceSyncV3NestedCoverageFeedEntry
+                : validateWorkspaceSyncV3CombinedFeedEntry)(entry);
+    return entry;
+}
+function finalizePage(input) {
+    const followingIndex = input.nextIndex + input.entries.length;
+    const hasMore = followingIndex < input.metadata.entryCount;
+    const profile = repairProfile(input.coverage);
+    const nextRepairCursor = hasMore ? encodeCursor({
+        protocolVersion: 3, tenantId: input.tenantId, workspaceId: input.workspaceId,
+        coverageProfileId: profile.coverageProfileId,
+        coverageVersion: profile.coverageVersion,
+        coverageDigest: profile.coverageDigest,
+        snapshotId: input.metadata.snapshotId,
+        snapshotSequence: input.metadata.snapshotSequence,
+        nextIndex: followingIndex,
+        expiresAt: input.metadata.expiresAt,
+    }, input.cursorKeyring) : null;
+    const resumeCursor = createWorkspaceSyncV3FeedResumeCursor({
+        tenantId: input.tenantId, workspaceId: input.workspaceId,
+        sequence: input.metadata.snapshotSequence, cursorKeyring: input.cursorKeyring, profile,
+    });
+    const entriesBytes = Buffer.byteLength(JSON.stringify(input.entries), 'utf8');
+    const base = {
+        success: true, protocolVersion: 3, workspaceId: input.workspaceId, coverage: profile,
+        snapshotId: input.metadata.snapshotId, snapshotSequence: input.metadata.snapshotSequence,
+        expiresAt: input.metadata.expiresAt, entries: input.entries, hasMore, nextRepairCursor, resumeCursor,
+    };
+    let responseBytes = 0;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const page = { ...base,
+            diagnostics: { returnedEntries: input.entries.length, entriesBytes, responseBytes,
+                materializedEntries: input.materializedEntries,
+                insertedBaselineEntities: input.insertedBaselineEntities,
+                insertedBaselineJournalRows: input.insertedBaselineJournalRows } };
+        const measured = Buffer.byteLength(JSON.stringify(page), 'utf8');
+        if (measured === responseBytes)
+            return page;
+        responseBytes = measured;
+    }
+    return { ...base, diagnostics: { returnedEntries: input.entries.length, entriesBytes, responseBytes,
+            materializedEntries: input.materializedEntries,
+            insertedBaselineEntities: input.insertedBaselineEntities,
+            insertedBaselineJournalRows: input.insertedBaselineJournalRows } };
+}
+export function buildWorkspaceSyncV3CombinedRepairPage(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('Combined repair cursor scope mismatch.');
+    }
+    const now = timestamp(input.now || new Date().toISOString(), 'Combined repair time');
+    const ttlMs = Math.max(60_000, Math.min(MAX_SNAPSHOT_TTL_MS, Math.floor(input.snapshotTtlMs || DEFAULT_SNAPSHOT_TTL_MS)));
+    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 db = input.core.getDatabaseAdapter();
+    const coverage = input.workflowCoverage
+        ? 'workflow'
+        : input.planningOrderCoverage
+            ? 'planning-order'
+            : input.nestedCoverage
+                ? 'nested'
+                : 'combined';
+    if (input.cursor && Date.parse(input.cursor.expiresAt) <= Date.parse(now)) {
+        db.transaction(() => {
+            db.prepare(`DELETE FROM workspace_sync_repair_snapshot_entries
+                WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id = ? AND EXISTS (
+                    SELECT 1 FROM workspace_sync_repair_snapshots
+                    WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id = ? AND expires_at <= ?
+                )`).run(tenantId, workspaceId, input.cursor.snapshotId, tenantId, workspaceId, input.cursor.snapshotId, now);
+            db.prepare(`DELETE FROM workspace_sync_repair_snapshots
+                WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id = ? AND expires_at <= ?`)
+                .run(tenantId, workspaceId, input.cursor.snapshotId, now);
+        })();
+        throw new WorkspaceSyncV3CombinedRepairSnapshotUnavailableError();
+    }
+    let insertedBaselineEntities = 0;
+    let insertedBaselineJournalRows = 0;
+    let materializedEntries = 0;
+    let metadata;
+    let nextIndex;
+    if (input.cursor) {
+        metadata = db.transaction(() => {
+            const current = readMetadata({
+                core: input.core, tenantId, workspaceId, cursor: input.cursor, now,
+                coverage,
+            });
+            cleanupExpired(input.core, tenantId, workspaceId, now, current.snapshotId);
+            return current;
+        })();
+        nextIndex = input.cursor.nextIndex;
+    }
+    else {
+        const materialized = db.transaction(() => {
+            // Serialize cursorless materialization and reuse decisions with
+            // durable writers and competing repair requests.
+            db.prepare(`
+                INSERT INTO workspace_sync_sequences (tenant_id, workspace_id, last_sequence, updated_at)
+                VALUES (?, ?, 0, ?)
+                ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET updated_at = excluded.updated_at
+                RETURNING CAST(last_sequence AS TEXT) AS last_sequence
+            `).get(tenantId, workspaceId, now);
+            cleanupExpired(input.core, tenantId, workspaceId, now);
+            const reusable = readReusableMetadata({
+                core: input.core, tenantId, workspaceId, now,
+                coverage,
+            });
+            if (reusable)
+                return { metadata: reusable, reused: true,
+                    insertedBaselineEntities: 0, insertedBaselineJournalRows: 0 };
+            const prepared = coverage === 'workflow'
+                ? prepareWorkspaceSyncV3WorkflowRepairSnapshot({ core: input.core, workspaceId, now })
+                : coverage === 'planning-order'
+                    ? prepareWorkspaceSyncV3PlanningOrderRepairSnapshot({ core: input.core, workspaceId, now })
+                    : coverage === 'nested'
+                        ? prepareWorkspaceSyncV3NestedRepairSnapshot({ core: input.core, workspaceId, now })
+                        : prepareWorkspaceSyncV3CombinedRepairSnapshot({ core: input.core, workspaceId, now });
+            // Production expiry is sampled at the end of persistence, after
+            // every immutable payload row has committed in the same lock.
+            const materializationStartedAt = input.now
+                ? now
+                : timestamp(new Date().toISOString(), 'Combined repair materialization start time');
+            const persisted = persistMaterialization({
+                core: input.core, tenantId, workspaceId, startedAt: materializationStartedAt,
+                fixedCompletionTime: input.now ? now : undefined, ttlMs,
+                snapshot: prepared.snapshot,
+                insertedBaselineEntities: prepared.insertedEntities,
+                insertedBaselineJournalRows: prepared.insertedJournalRows,
+                coverage,
+            });
+            return { metadata: persisted, reused: false,
+                insertedBaselineEntities: prepared.insertedEntities,
+                insertedBaselineJournalRows: prepared.insertedJournalRows };
+        })();
+        metadata = materialized.metadata;
+        nextIndex = 0;
+        insertedBaselineEntities = materialized.insertedBaselineEntities;
+        insertedBaselineJournalRows = materialized.insertedBaselineJournalRows;
+        materializedEntries = materialized.reused ? 0 : metadata.entryCount;
+    }
+    return db.transaction(() => {
+        if (input.cursor) {
+            // Re-read inside the page transaction so expiry or metadata tampering
+            // cannot race between cursor validation and entry selection.
+            metadata = readMetadata({
+                core: input.core, tenantId, workspaceId, cursor: input.cursor, now,
+                coverage,
+            });
+        }
+        const rows = 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_repair_snapshot_entries
+            WHERE tenant_id = ? AND workspace_id = ? AND snapshot_id = ? AND entry_index >= ?
+            ORDER BY entry_index ASC
+            LIMIT ?
+        `).all(tenantId, workspaceId, metadata.snapshotId, nextIndex, pageSize);
+        const entries = [];
+        for (const row of rows) {
+            if (Number(row.entry_index) !== nextIndex + entries.length) {
+                throw new Error('Combined repair materialized entry order is incomplete.');
+            }
+            const entry = mapEntry(row, coverage);
+            const candidate = finalizePage({ tenantId, workspaceId, metadata,
+                entries: [...entries, entry], nextIndex, cursorKeyring: input.cursorKeyring,
+                materializedEntries,
+                insertedBaselineEntities, insertedBaselineJournalRows,
+                coverage });
+            if (candidate.diagnostics.responseBytes > maxResponseBytes) {
+                if (entries.length === 0) {
+                    throw new WorkspaceSyncV3FeedOperationTooLargeError(`Combined repair page beginning with ${entry.entityId} exceeds the repair byte limit.`);
+                }
+                break;
+            }
+            entries.push(entry);
+        }
+        const page = finalizePage({ tenantId, workspaceId, metadata, entries, nextIndex,
+            cursorKeyring: input.cursorKeyring, materializedEntries,
+            insertedBaselineEntities, insertedBaselineJournalRows,
+            coverage });
+        if (page.hasMore && entries.length === 0)
+            throw new Error('Combined repair page made no progress.');
+        if (page.diagnostics.responseBytes > maxResponseBytes) {
+            throw new WorkspaceSyncV3FeedOperationTooLargeError('Combined repair response envelope exceeds the repair byte limit.');
+        }
+        return page;
+    })();
+}
+export function buildWorkspaceSyncV3NestedRepairPage(input) {
+    return buildWorkspaceSyncV3CombinedRepairPage({ ...input, nestedCoverage: true });
+}
+export function buildWorkspaceSyncV3WorkflowRepairPage(input) {
+    return buildWorkspaceSyncV3CombinedRepairPage({ ...input, workflowCoverage: true });
+}
+export function buildWorkspaceSyncV3PlanningOrderRepairPage(input) {
+    return buildWorkspaceSyncV3CombinedRepairPage({ ...input, planningOrderCoverage: true });
+}

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

@@ -0,0 +1,78 @@
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import type { WorkspaceSyncV3FeedEntry } from './workspaceSyncV3Feed.js';
+import { type WorkspaceSyncV3NestedTaskRepairCandidate } from './workspaceSyncV3NestedTaskRepairSnapshot.js';
+type WorkspaceSyncV3RootRepairCandidate = {
+    domain: 'initiative' | 'workstream' | 'task' | 'task-relationship' | 'taxonomy';
+    entityId: string;
+    payload: unknown;
+};
+type WorkspaceSyncV3WorkflowRepairCandidate = {
+    domain: 'workflow-published-definition' | 'workflow-execution' | 'workflow-execution-event';
+    entityId: string;
+    payload: unknown;
+};
+type WorkspaceSyncV3PlanningOrderRepairCandidate = {
+    domain: 'workstream-task-order';
+    entityId: string;
+    payload: unknown;
+};
+export type WorkspaceSyncV3CombinedRepairCandidate = WorkspaceSyncV3RootRepairCandidate | WorkspaceSyncV3NestedTaskRepairCandidate | WorkspaceSyncV3WorkflowRepairCandidate | WorkspaceSyncV3PlanningOrderRepairCandidate;
+export declare class WorkspaceSyncV3CombinedRepairBaselineRequiredError extends Error {
+    readonly missing: ReadonlyArray<{
+        domain: string;
+        entityId: string;
+    }>;
+    readonly code = "WORKSPACE_SYNC_V3_COMBINED_REPAIR_BASELINE_REQUIRED";
+    constructor(missing: ReadonlyArray<{
+        domain: string;
+        entityId: string;
+    }>);
+}
+export declare function listWorkspaceSyncV3CombinedRepairCandidates(core: TaskforceCore, workspaceId: string): WorkspaceSyncV3CombinedRepairCandidate[];
+/** Candidate v4 inventory. The coverage-v3 inventory above intentionally remains unchanged. */
+export declare function listWorkspaceSyncV3NestedRepairCandidates(core: TaskforceCore, workspaceId: string): WorkspaceSyncV3CombinedRepairCandidate[];
+/** Candidate v5 inventory. Coverage-v3/v4 inventories intentionally remain unchanged. */
+export declare function listWorkspaceSyncV3WorkflowRepairCandidates(core: TaskforceCore, workspaceId: string): WorkspaceSyncV3CombinedRepairCandidate[];
+/** Candidate v6 inventory. Workflow v5 remains an independent dark contract. */
+export declare function listWorkspaceSyncV3PlanningOrderRepairCandidates(core: TaskforceCore, workspaceId: string): WorkspaceSyncV3CombinedRepairCandidate[];
+export declare function buildWorkspaceSyncV3CombinedRepairSnapshot(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+}): {
+    snapshotSequence: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+};
+export declare function buildWorkspaceSyncV3CombinedRepairSnapshotFromLockedCandidates(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+    snapshotSequence: string;
+    inventory: WorkspaceSyncV3CombinedRepairCandidate[];
+    nestedCoverage?: boolean;
+    workflowCoverage?: boolean;
+    planningOrderCoverage?: boolean;
+}): {
+    snapshotSequence: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+};
+export declare function buildWorkspaceSyncV3NestedRepairSnapshot(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+}): {
+    snapshotSequence: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+};
+export declare function buildWorkspaceSyncV3WorkflowRepairSnapshot(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+}): {
+    snapshotSequence: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+};
+export declare function buildWorkspaceSyncV3PlanningOrderRepairSnapshot(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+}): {
+    snapshotSequence: string;
+    entries: WorkspaceSyncV3FeedEntry[];
+};
+export {};