@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/v3/workspaceSyncV3Feed.js

@@ -0,0 +1,243 @@
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { decodeCanonicalWorkspaceSyncBase64Url } from './workspaceSyncV3CursorEncoding.js';
+import { createHmac, timingSafeEqual } from 'crypto';
+import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION } from './syncDurabilityStore.js';
+import { WORKSPACE_SYNC_V3_COVERAGE_PROFILE, resolveWorkspaceSyncV3Projection } from './workspaceSyncV3FeedProfile.js';
+import { serializeInitiativeForSync } from '../planningSyncPayload.js';
+import { findWorkspaceSyncV3FeedCursorVerificationKey } from './workspaceSyncV3FeedCursorKeys.js';
+const MAX_OPERATION_ROWS = 100;
+const INITIATIVE_MUTATION_KINDS = new Set(['create', 'metadata-update', 'append-comment', 'archive', 'unarchive']);
+export class WorkspaceSyncV3FeedOperationTooLargeError extends Error {
+    code = 'WORKSPACE_SYNC_V3_FEED_OPERATION_TOO_LARGE';
+    statusCode = 413;
+}
+function seq(value) {
+    const text = String(value ?? '').trim();
+    if (!/^\d+$/.test(text))
+        throw new Error('Invalid workspace sync feed sequence.');
+    return BigInt(text).toString(10);
+}
+function makeCursor(tenantId, workspaceId, cycleHighWatermark, lastScannedSequence, profile = WORKSPACE_SYNC_V3_COVERAGE_PROFILE) {
+    return { protocolVersion: 3, tenantId, workspaceId,
+        coverageProfileId: profile.coverageProfileId,
+        coverageVersion: profile.coverageVersion,
+        coverageDigest: profile.coverageDigest,
+        cycleHighWatermark: seq(cycleHighWatermark), lastScannedSequence: seq(lastScannedSequence) };
+}
+export function createWorkspaceSyncV3FeedResumeCursor(input) {
+    return encodeWorkspaceSyncV3FeedCursor(makeCursor(input.tenantId, input.workspaceId, input.sequence, input.sequence, input.profile), input.cursorKeyring);
+}
+export function encodeWorkspaceSyncV3FeedCursor(cursor, keyring) {
+    const { id, secret } = keyring.active;
+    const payload = Buffer.from(canonicalWorkspaceSyncJson(cursor), 'utf8').toString('base64url');
+    const signature = createHmac('sha256', secret).update(`${id}.${payload}`).digest('base64url');
+    return `${id}.${payload}.${signature}`;
+}
+export function decodeWorkspaceSyncV3FeedCursor(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 || ''), coverageProfileId: String(value.coverageProfileId || ''),
+            coverageVersion: Number(value.coverageVersion), coverageDigest: String(value.coverageDigest || ''),
+            cycleHighWatermark: seq(value.cycleHighWatermark), lastScannedSequence: seq(value.lastScannedSequence) };
+        if (!cursor.tenantId || !cursor.workspaceId || !cursor.coverageProfileId || !cursor.coverageDigest
+            || !Number.isSafeInteger(cursor.protocolVersion) || !Number.isSafeInteger(cursor.coverageVersion)
+            || BigInt(cursor.lastScannedSequence) > BigInt(cursor.cycleHighWatermark))
+            return null;
+        return cursor;
+    }
+    catch {
+        return null;
+    }
+}
+function metadataOnly(value, path = 'payload') {
+    if (Array.isArray(value))
+        return value.forEach((entry, index) => metadataOnly(entry, `${path}[${index}]`));
+    if (!value || typeof value !== 'object')
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === 'content' || key === 'contentBase64')
+            throw new Error(`Covered feed cannot include ${path}.${key}.`);
+        metadataOnly(child, `${path}.${key}`);
+    }
+}
+function canonicalInitiativePayload(payload, entityId, mutationKind, label) {
+    metadataOnly(payload);
+    if (!INITIATIVE_MUTATION_KINDS.has(mutationKind))
+        throw new Error(`Unsupported initiative mutation at ${label}.`);
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        throw new Error(`Invalid initiative payload at ${label}.`);
+    const canonical = serializeInitiativeForSync(payload);
+    if (canonical.id !== entityId || canonicalWorkspaceSyncJson(canonical) !== canonicalWorkspaceSyncJson(payload)) {
+        throw new Error(`Initiative payload is not canonical at ${label}.`);
+    }
+    if (mutationKind === 'archive' && !canonical.isArchived)
+        throw new Error(`Archive payload is active at ${label}.`);
+    if (mutationKind === 'unarchive' && canonical.isArchived)
+        throw new Error(`Unarchive payload is archived at ${label}.`);
+    if (mutationKind === 'create' && (canonical.isArchived || canonical.referenceNumber === null
+        || canonical.referenceNumber === undefined || canonical.referenceLabel !== `IN-${canonical.referenceNumber}`)) {
+        throw new Error(`Create payload lacks active canonical identity at ${label}.`);
+    }
+    return canonical;
+}
+export function validateWorkspaceSyncV3FeedEntry(entry) {
+    if (entry.projection !== 'initiative/full-v1' || entry.domain !== 'initiative')
+        throw new Error('Unsupported workspace sync feed projection.');
+    seq(entry.sequence);
+    seq(entry.entityRevision);
+    seq(entry.lifecycleRevision);
+    if (BigInt(entry.entityRevision) < 1n || BigInt(entry.lifecycleRevision) > BigInt(entry.entityRevision)) {
+        throw new Error(`Initiative feed revisions are invalid at ${entry.sequence}.`);
+    }
+    if (entry.mutationKind === 'create' && (entry.entityRevision !== '1' || entry.lifecycleRevision !== '0')) {
+        throw new Error(`Initiative create revisions are invalid at ${entry.sequence}.`);
+    }
+    if ((entry.mutationKind === 'archive' || entry.mutationKind === 'unarchive') && BigInt(entry.lifecycleRevision) < 1n) {
+        throw new Error(`Initiative lifecycle revision is invalid at ${entry.sequence}.`);
+    }
+    const canonical = canonicalInitiativePayload(entry.payload, entry.entityId, entry.mutationKind, entry.sequence);
+    if (fingerprintWorkspaceSyncPayload(canonical) !== entry.payloadFingerprint)
+        throw new Error(`Initiative feed fingerprint is invalid at ${entry.sequence}.`);
+    if (entry.contentSha256 !== undefined || entry.sizeBytes !== undefined)
+        throw new Error(`Initiative feed entry carries content coordinates at ${entry.sequence}.`);
+}
+export function projectWorkspaceSyncV3InitiativeJournalRow(row) {
+    const projection = resolveWorkspaceSyncV3Projection(row.domain);
+    if (!projection)
+        return null;
+    if (row.contractVersion !== WORKSPACE_SYNC_CONTRACT_VERSION)
+        throw new Error(`Unsupported journal contract at ${row.sequence}.`);
+    let payload;
+    try {
+        payload = JSON.parse(row.payloadJson);
+    }
+    catch {
+        throw new Error(`Malformed journal payload at ${row.sequence}.`);
+    }
+    const canonical = canonicalInitiativePayload(payload, row.entityId, row.mutationKind, row.sequence);
+    if (BigInt(row.entityRevision) < 1n || BigInt(row.lifecycleRevision) > BigInt(row.entityRevision)) {
+        throw new Error(`Initiative journal revisions are invalid at ${row.sequence}.`);
+    }
+    if (row.mutationKind === 'create' && (row.entityRevision !== '1' || row.lifecycleRevision !== '0')) {
+        throw new Error(`Initiative create revisions are invalid at ${row.sequence}.`);
+    }
+    if ((row.mutationKind === 'archive' || row.mutationKind === 'unarchive') && BigInt(row.lifecycleRevision) < 1n) {
+        throw new Error(`Initiative lifecycle revision is invalid at ${row.sequence}.`);
+    }
+    if (row.contentSha256 !== null || row.sizeBytes !== null)
+        throw new Error(`Initiative journal row carries content coordinates at ${row.sequence}.`);
+    payload = canonical;
+    return { sequence: row.sequence, projection, domain: row.domain, entityId: row.entityId, mutationKind: row.mutationKind,
+        entityRevision: row.entityRevision, lifecycleRevision: row.lifecycleRevision,
+        payloadFingerprint: fingerprintWorkspaceSyncPayload(payload), payload, occurredAt: row.occurredAt,
+        ...(row.contentSha256 ? { contentSha256: row.contentSha256 } : {}), ...(row.sizeBytes ? { sizeBytes: row.sizeBytes } : {}) };
+}
+function matches(cursor, profile) {
+    return cursor.protocolVersion === 3 && cursor.coverageProfileId === profile.coverageProfileId
+        && cursor.coverageVersion === profile.coverageVersion && cursor.coverageDigest === profile.coverageDigest;
+}
+function reset(code, tenantId, workspaceId, snapshotSequence, keyring, profile) {
+    return { success: false, protocolVersion: 3, workspaceId, code,
+        error: code === 'COVERAGE_CHANGED' ? 'Coverage changed; authoritative repair is required.' : 'Journal history expired; authoritative repair is required.',
+        coverage: profile, repair: { mode: 'authoritative-covered-projection-snapshot', snapshotSequence,
+            resumeCursor: encodeWorkspaceSyncV3FeedCursor(makeCursor(tenantId, workspaceId, snapshotSequence, snapshotSequence, profile), keyring) } };
+}
+function finalizePage(base, scannedCount) {
+    let responseBytes = 0;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const page = { ...base, diagnostics: { scannedCount, coveredCount: base.entries.length, responseBytes } };
+        const measured = Buffer.byteLength(JSON.stringify(page), 'utf8');
+        if (measured === responseBytes)
+            return page;
+        responseBytes = measured;
+    }
+    return { ...base, diagnostics: { scannedCount, coveredCount: base.entries.length, responseBytes } };
+}
+export function buildWorkspaceSyncV3Feed(input) {
+    const coveragePolicy = input.coveragePolicy || {
+        profile: WORKSPACE_SYNC_V3_COVERAGE_PROFILE,
+        projectOperation: (operation) => operation.rows
+            .map(projectWorkspaceSyncV3InitiativeJournalRow).filter((entry) => entry !== null),
+    };
+    const { profile, projectOperation } = coveragePolicy;
+    const bounds = input.reader.readBounds(input);
+    const currentHigh = BigInt(bounds.highWatermark);
+    if (!input.cursor)
+        return reset('CURSOR_EXPIRED', input.tenantId, input.workspaceId, bounds.highWatermark, input.cursorKeyring, profile);
+    if (input.cursor && !matches(input.cursor, profile))
+        return reset('COVERAGE_CHANGED', input.tenantId, input.workspaceId, bounds.highWatermark, input.cursorKeyring, profile);
+    if (input.cursor && (input.cursor.tenantId !== input.tenantId || input.cursor.workspaceId !== input.workspaceId))
+        throw new Error('Feed cursor scope mismatch.');
+    let last = BigInt(input.cursor?.lastScannedSequence || 0);
+    let high = BigInt(input.cursor?.cycleHighWatermark || bounds.highWatermark);
+    if (input.cursor && last === high)
+        high = currentHigh;
+    if (high > currentHigh || last > high)
+        throw new Error('Feed cursor coordinates are invalid.');
+    const min = bounds.minRetainedSequence == null ? null : BigInt(bounds.minRetainedSequence);
+    if (currentHigh > 0n && (min === null || (last + 1n < min && last < high))) {
+        return reset('CURSOR_EXPIRED', input.tenantId, input.workspaceId, bounds.highWatermark, input.cursorKeyring, profile);
+    }
+    const pageSize = Math.max(1, Math.min(500, Math.floor(input.pageSize || 200)));
+    const byteLimit = Math.max(1024, Math.min(8 * 1024 * 1024, Math.floor(input.maxResponseBytes || 1024 * 1024)));
+    const scanLimit = Math.max(1, Math.min(10_000, Math.floor(input.scanLimit || 2000)));
+    const rows = input.reader.scan({ ...input, afterSequence: String(last), throughSequence: String(high), limit: scanLimit + MAX_OPERATION_ROWS + 1 });
+    const entries = [];
+    let scannedCount = 0;
+    let stoppedAtPageBoundary = false;
+    for (let offset = 0; offset < Math.min(rows.length, scanLimit);) {
+        const operationId = rows[offset].operationId;
+        const clientId = rows[offset].clientId;
+        let end = offset + 1;
+        while (end < rows.length && rows[end].operationId === operationId && rows[end].clientId === clientId)
+            end += 1;
+        if (end - offset > MAX_OPERATION_ROWS || (end === rows.length && rows.length === scanLimit + MAX_OPERATION_ROWS + 1)) {
+            throw new WorkspaceSyncV3FeedOperationTooLargeError(`Workspace sync operation ${clientId}/${operationId} exceeds ${MAX_OPERATION_ROWS} journal rows.`);
+        }
+        const groupRows = rows.slice(offset, end);
+        const groupEntries = projectOperation({ rows: groupRows, cycleHighWatermark: String(high), followingRow: rows[end] || null });
+        if (entries.length + groupEntries.length > pageSize) {
+            if (!entries.length)
+                throw new WorkspaceSyncV3FeedOperationTooLargeError(`Covered operation ${clientId}/${operationId} exceeds the feed entry limit.`);
+            stoppedAtPageBoundary = true;
+            break;
+        }
+        const tentativeEntries = [...entries, ...groupEntries];
+        const tentativeLast = groupRows.at(-1).sequence;
+        const tentativeCursor = encodeWorkspaceSyncV3FeedCursor(makeCursor(input.tenantId, input.workspaceId, String(high), tentativeLast, profile), input.cursorKeyring);
+        const candidate = finalizePage({
+            success: true, protocolVersion: 3, workspaceId: input.workspaceId, coverage: profile,
+            cycleHighWatermark: String(high), lastScannedSequence: tentativeLast, entries: tentativeEntries,
+            nextCursor: tentativeCursor, hasMore: BigInt(tentativeLast) < high,
+        }, scannedCount + groupRows.length);
+        if (candidate.diagnostics.responseBytes > byteLimit) {
+            if (!entries.length)
+                throw new WorkspaceSyncV3FeedOperationTooLargeError(`Covered operation ${clientId}/${operationId} exceeds the feed byte limit.`);
+            stoppedAtPageBoundary = true;
+            break;
+        }
+        entries.push(...groupEntries);
+        last = BigInt(tentativeLast);
+        scannedCount += groupRows.length;
+        offset = end;
+    }
+    if (last < high && rows.length <= scanLimit && !stoppedAtPageBoundary)
+        throw new Error('Workspace sync journal contains a sequence gap.');
+    const nextCursor = encodeWorkspaceSyncV3FeedCursor(makeCursor(input.tenantId, input.workspaceId, String(high), String(last), profile), input.cursorKeyring);
+    const responseBase = { success: true, protocolVersion: 3, workspaceId: input.workspaceId,
+        coverage: profile,
+        cycleHighWatermark: String(high), lastScannedSequence: String(last), entries, nextCursor, hasMore: last < high };
+    return finalizePage(responseBase, scannedCount);
+}

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

@@ -0,0 +1,13 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+import { type WorkspaceSyncV3FeedCursor, type WorkspaceSyncV3FeedEntry, type WorkspaceSyncV3FeedPage } from './workspaceSyncV3Feed.js';
+export declare function commitWorkspaceSyncV3FeedPageAtomically(input: {
+    db: DatabaseAdapter;
+    page: WorkspaceSyncV3FeedPage;
+    previousCursor: string;
+    decodeCursor: (raw: string) => WorkspaceSyncV3FeedCursor | null;
+    tenantId: string;
+    workspaceId: string;
+    readCursor: () => string | null;
+    applyEntry: (entry: WorkspaceSyncV3FeedEntry) => unknown;
+    persistCursor: (cursor: string) => unknown;
+}): 'applied' | 'duplicate';

package/dist/sync/v3/workspaceSyncV3FeedApply.js

@@ -0,0 +1,67 @@
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { WORKSPACE_SYNC_V3_COVERAGE_PROFILE } from './workspaceSyncV3FeedProfile.js';
+import { validateWorkspaceSyncV3FeedEntry } from './workspaceSyncV3Feed.js';
+function synchronous(result, label) {
+    if (result && typeof result.then === 'function')
+        throw new Error(`${label} must be synchronous.`);
+}
+export function commitWorkspaceSyncV3FeedPageAtomically(input) {
+    const previous = input.decodeCursor(input.previousCursor);
+    const next = input.decodeCursor(input.page.nextCursor);
+    if (!previous || !next)
+        throw new Error('Workspace sync feed page cursor is invalid.');
+    const profile = WORKSPACE_SYNC_V3_COVERAGE_PROFILE;
+    if (input.page.protocolVersion !== 3 || input.page.workspaceId !== input.workspaceId
+        || previous.protocolVersion !== 3 || next.protocolVersion !== 3
+        || canonicalWorkspaceSyncJson(input.page.coverage) !== canonicalWorkspaceSyncJson(profile)
+        || previous.coverageProfileId !== profile.coverageProfileId || next.coverageProfileId !== profile.coverageProfileId
+        || previous.coverageVersion !== profile.coverageVersion || next.coverageVersion !== profile.coverageVersion
+        || previous.coverageDigest !== profile.coverageDigest || next.coverageDigest !== profile.coverageDigest) {
+        throw new Error('Workspace sync feed page contract is invalid.');
+    }
+    if (previous.tenantId !== input.tenantId || next.tenantId !== input.tenantId
+        || previous.workspaceId !== input.workspaceId || next.workspaceId !== input.workspaceId
+        || next.cycleHighWatermark !== input.page.cycleHighWatermark
+        || next.lastScannedSequence !== input.page.lastScannedSequence
+        || BigInt(next.lastScannedSequence) < BigInt(previous.lastScannedSequence)
+        || input.page.hasMore !== (BigInt(input.page.lastScannedSequence) < BigInt(input.page.cycleHighWatermark))) {
+        throw new Error('Workspace sync feed page coordinates are invalid.');
+    }
+    if (BigInt(previous.lastScannedSequence) < BigInt(previous.cycleHighWatermark)
+        && previous.cycleHighWatermark !== next.cycleHighWatermark) {
+        throw new Error('Workspace sync feed cycle high watermark changed mid-cycle.');
+    }
+    if (input.page.diagnostics.coveredCount !== input.page.entries.length
+        || input.page.diagnostics.scannedCount < input.page.entries.length
+        || input.page.diagnostics.responseBytes !== Buffer.byteLength(JSON.stringify(input.page), 'utf8')) {
+        throw new Error('Workspace sync feed page diagnostics are invalid.');
+    }
+    let prior = BigInt(previous.lastScannedSequence);
+    const revisions = new Map();
+    for (const entry of input.page.entries) {
+        validateWorkspaceSyncV3FeedEntry(entry);
+        const current = BigInt(entry.sequence);
+        if (current <= prior || current > BigInt(input.page.lastScannedSequence))
+            throw new Error('Workspace sync feed entries are outside page coordinates.');
+        prior = current;
+        const priorRevision = revisions.get(`${entry.domain}\0${entry.entityId}`);
+        const entity = BigInt(entry.entityRevision);
+        const lifecycle = BigInt(entry.lifecycleRevision);
+        if (priorRevision && (entity < priorRevision.entity || lifecycle < priorRevision.lifecycle
+            || (entity === priorRevision.entity && lifecycle === priorRevision.lifecycle))) {
+            throw new Error('Workspace sync feed entity revisions are not monotonic within the page.');
+        }
+        revisions.set(`${entry.domain}\0${entry.entityId}`, { entity, lifecycle });
+    }
+    return input.db.transaction(() => {
+        const persisted = input.readCursor();
+        if (persisted === input.page.nextCursor)
+            return 'duplicate';
+        if (persisted !== input.previousCursor)
+            throw new Error('Workspace sync feed persisted cursor changed before page commit.');
+        for (const entry of input.page.entries)
+            synchronous(input.applyEntry(entry), 'Workspace sync feed apply callback');
+        synchronous(input.persistCursor(input.page.nextCursor), 'Workspace sync feed cursor callback');
+        return 'applied';
+    })();
+}

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

@@ -0,0 +1,3 @@
+import type { WorkspaceSyncV3FeedEntry } from './workspaceSyncV3Feed.js';
+export declare function isWorkspaceSyncV3ClientCoverage(value: unknown): boolean;
+export declare function validateWorkspaceSyncV3ClientEntry(entry: WorkspaceSyncV3FeedEntry): void;

package/dist/sync/v3/workspaceSyncV3FeedClientContract.js

@@ -0,0 +1,46 @@
+import { serializeInitiativeForSync } from '../planningSyncPayload.js';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+const MUTATION_KINDS = ['create', 'metadata-update', 'append-comment', 'archive', 'unarchive'];
+const EXPECTED_COVERAGE_IDENTITY = {
+    coverageProfileId: 'covered-metadata',
+    coverageVersion: 1,
+    projections: [{
+            projectionId: 'initiative/full-v1', domain: 'initiative', schemaVersion: 1,
+            mutationKinds: MUTATION_KINDS,
+            fields: ['id', 'referenceNumber', 'referenceLabel', 'title', 'description', 'ownerId', 'comments',
+                'attachments', 'order', 'createdAt', 'updatedAt', 'isArchived'],
+            dependencies: [], operationAtomic: true,
+        }],
+};
+function metadataOnly(value) {
+    if (Array.isArray(value))
+        return value.every(metadataOnly);
+    if (!value || typeof value !== 'object')
+        return true;
+    return Object.entries(value)
+        .every(([key, child]) => key !== 'content' && key !== 'contentBase64' && metadataOnly(child));
+}
+export function isWorkspaceSyncV3ClientCoverage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const coverage = value;
+    return typeof coverage.coverageDigest === 'string' && /^[a-f0-9]{64}$/.test(coverage.coverageDigest)
+        && canonicalWorkspaceSyncJson({ coverageProfileId: coverage.coverageProfileId,
+            coverageVersion: coverage.coverageVersion, projections: coverage.projections })
+            === canonicalWorkspaceSyncJson(EXPECTED_COVERAGE_IDENTITY);
+}
+export function validateWorkspaceSyncV3ClientEntry(entry) {
+    const sequence = (value) => /^\d+$/.test(String(value ?? ''));
+    if (entry.projection !== 'initiative/full-v1' || entry.domain !== 'initiative' || !entry.entityId
+        || !MUTATION_KINDS.includes(entry.mutationKind)
+        || !sequence(entry.sequence) || !sequence(entry.entityRevision) || !sequence(entry.lifecycleRevision)
+        || !/^[a-f0-9]{64}$/.test(entry.payloadFingerprint) || !metadataOnly(entry.payload)
+        || entry.contentSha256 !== undefined || entry.sizeBytes !== undefined) {
+        throw new Error('Workspace sync v3 initiative entry is invalid.');
+    }
+    const canonical = serializeInitiativeForSync(entry.payload);
+    if (canonical.id !== entry.entityId
+        || canonicalWorkspaceSyncJson(canonical) !== canonicalWorkspaceSyncJson(entry.payload)) {
+        throw new Error('Workspace sync v3 initiative payload is not canonical.');
+    }
+}

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

@@ -0,0 +1,10 @@
+export interface WorkspaceSyncV3FeedCursorKey {
+    id: string;
+    secret: string;
+}
+export interface WorkspaceSyncV3FeedCursorKeyring {
+    active: WorkspaceSyncV3FeedCursorKey;
+    previous: readonly WorkspaceSyncV3FeedCursorKey[];
+}
+export declare function parseWorkspaceSyncV3FeedCursorKeyring(raw: string | null | undefined): WorkspaceSyncV3FeedCursorKeyring;
+export declare function findWorkspaceSyncV3FeedCursorVerificationKey(keyring: WorkspaceSyncV3FeedCursorKeyring, keyId: string): WorkspaceSyncV3FeedCursorKey | null;

package/dist/sync/v3/workspaceSyncV3FeedCursorKeys.js

@@ -0,0 +1,58 @@
+const KEY_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MINIMUM_SECRET_BYTES = 32;
+function requireExactKeys(record, expected, label) {
+    const actual = Object.keys(record).sort();
+    const required = [...expected].sort();
+    if (actual.length !== required.length || actual.some((key, index) => key !== required[index])) {
+        throw new Error(`${label} must contain exactly: ${expected.join(', ')}.`);
+    }
+}
+function parseKey(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object.`);
+    const record = value;
+    requireExactKeys(record, ['id', 'secret'], label);
+    if (typeof record.id !== 'string')
+        throw new Error(`${label}.id must be a string.`);
+    if (typeof record.secret !== 'string')
+        throw new Error(`${label}.secret must be a string.`);
+    const id = record.id.trim();
+    const secret = record.secret;
+    if (!KEY_ID_PATTERN.test(id))
+        throw new Error(`${label}.id must contain 1-64 letters, numbers, underscores, or hyphens.`);
+    if (Buffer.byteLength(secret, 'utf8') < MINIMUM_SECRET_BYTES) {
+        throw new Error(`${label}.secret must contain at least ${MINIMUM_SECRET_BYTES} UTF-8 bytes.`);
+    }
+    return Object.freeze({ id, secret });
+}
+export function parseWorkspaceSyncV3FeedCursorKeyring(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(String(raw || ''));
+    }
+    catch {
+        throw new Error('TASKFORCE_SYNC_V3_FEED_CURSOR_KEYS_JSON must be valid JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('TASKFORCE_SYNC_V3_FEED_CURSOR_KEYS_JSON must be an object.');
+    }
+    const record = parsed;
+    requireExactKeys(record, ['active', 'previous'], 'TASKFORCE_SYNC_V3_FEED_CURSOR_KEYS_JSON');
+    const active = parseKey(record.active, 'active');
+    const previousRaw = record.previous;
+    if (!Array.isArray(previousRaw))
+        throw new Error('previous must be an array.');
+    const previous = previousRaw.map((value, index) => parseKey(value, `previous[${index}]`));
+    const ids = new Set();
+    for (const key of [active, ...previous]) {
+        if (ids.has(key.id))
+            throw new Error(`Duplicate workspace sync v3 feed cursor key id: ${key.id}.`);
+        ids.add(key.id);
+    }
+    return Object.freeze({ active, previous: Object.freeze(previous) });
+}
+export function findWorkspaceSyncV3FeedCursorVerificationKey(keyring, keyId) {
+    if (keyring.active.id === keyId)
+        return keyring.active;
+    return keyring.previous.find((key) => key.id === keyId) || null;
+}

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

@@ -0,0 +1,31 @@
+import { applyLocalWorkspaceSyncV3Projection, getLocalWorkspaceSyncV3Projection, pullWorkspaceInitiativeRepair, pullWorkspaceSyncV3Feed } from '../cloudSyncApi.js';
+export type WorkspaceSyncV3ProjectionCycleResult = {
+    kind: 'v3-active';
+    excludeInitiativesFromV2: true;
+} | {
+    kind: 'v2-fallback';
+    excludeInitiativesFromV2: false;
+} | {
+    kind: 'auth-failure';
+    status: 401;
+    excludeInitiativesFromV2: boolean;
+} | {
+    kind: 'transient-failure';
+    status: number;
+    retryAfterMs?: number;
+    error: string;
+    excludeInitiativesFromV2: boolean;
+};
+export interface WorkspaceSyncV3FeedOrchestratorDependencies {
+    getLocalProjection: typeof getLocalWorkspaceSyncV3Projection;
+    applyLocalProjection: typeof applyLocalWorkspaceSyncV3Projection;
+    pullFeed: typeof pullWorkspaceSyncV3Feed;
+    pullInitiativeRepair: typeof pullWorkspaceInitiativeRepair;
+}
+export declare function runWorkspaceSyncV3InitiativeProjectionCycle(input: {
+    activationEnabled: boolean;
+    resolveCloudAuthUrl: (path: string) => string;
+    workspaceId: string;
+    onChangesApplied?: (changeCount: number) => void;
+    dependencies?: Partial<WorkspaceSyncV3FeedOrchestratorDependencies>;
+}): Promise<WorkspaceSyncV3ProjectionCycleResult>;