@taskforcehq/taskforce 0.3.168

package/dist/sync/cloudSyncApi.js

@@ -0,0 +1,138 @@
+function toStatus(error) {
+    const status = Number(error?.status);
+    if (Number.isFinite(status) && status > 0)
+        return Math.floor(status);
+    return 0;
+}
+async function requestJson(request) {
+    try {
+        const res = await request;
+        const rawText = await res.text().catch(() => '');
+        let data = {};
+        if (rawText) {
+            try {
+                data = JSON.parse(rawText);
+            }
+            catch {
+                const fallbackError = (!res.ok && res.statusText)
+                    ? `${res.status} ${res.statusText}`
+                    : rawText.slice(0, 400);
+                data = { error: fallbackError };
+            }
+        }
+        else if (!res.ok && res.statusText) {
+            data = { error: `${res.status} ${res.statusText}` };
+        }
+        const retryAfterRaw = res.headers.get('retry-after');
+        let retryAfterMs;
+        if (retryAfterRaw) {
+            const seconds = Number.parseInt(retryAfterRaw, 10);
+            if (Number.isFinite(seconds) && seconds > 0) {
+                retryAfterMs = seconds * 1000;
+            }
+            else {
+                const retryAt = Date.parse(retryAfterRaw);
+                if (Number.isFinite(retryAt)) {
+                    const delta = retryAt - Date.now();
+                    if (delta > 0)
+                        retryAfterMs = delta;
+                }
+            }
+        }
+        return { ok: res.ok, status: res.status, data, retryAfterMs };
+    }
+    catch (error) {
+        return { ok: false, status: toStatus(error), data: {} };
+    }
+}
+export async function pullUserSettings(resolveCloudAuthUrl) {
+    return requestJson(fetch(resolveCloudAuthUrl('/api/taskforce/sync/user-settings'), {
+        method: 'GET',
+        credentials: 'include'
+    }));
+}
+export async function pushUserSettings(resolveCloudAuthUrl, payload) {
+    return requestJson(fetch(resolveCloudAuthUrl('/api/taskforce/sync/user-settings'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(payload)
+    }));
+}
+export async function handshakeWorkspace(resolveCloudAuthUrl, workspaceId) {
+    return requestJson(fetch(resolveCloudAuthUrl('/api/taskforce/sync/workspace/handshake'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify({ workspaceId })
+    }));
+}
+export async function provisionWorkspace(resolveCloudAuthUrl, input) {
+    return requestJson(fetch(resolveCloudAuthUrl('/api/taskforce/sync/workspace/provision'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(input)
+    }));
+}
+export async function pullWorkspaceChanges(resolveCloudAuthUrl, input) {
+    const params = new URLSearchParams({ limit: String(input.limit), workspaceId: input.workspaceId });
+    if (input.cursor)
+        params.set('cursor', input.cursor);
+    const baseUrl = resolveCloudAuthUrl('/api/taskforce/sync/workspace/pull');
+    const separator = baseUrl.includes('?') ? '&' : '?';
+    return requestJson(fetch(`${baseUrl}${separator}${params.toString()}`, {
+        method: 'GET',
+        credentials: 'include'
+    }));
+}
+export async function pushWorkspaceChanges(resolveCloudAuthUrl, input) {
+    return requestJson(fetch(resolveCloudAuthUrl('/api/taskforce/sync/workspace/push'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(input)
+    }));
+}
+export async function bootstrapPushWorkspaceSnapshot(resolveCloudAuthUrl, input) {
+    return requestJson(fetch(resolveCloudAuthUrl('/api/taskforce/sync/workspace/bootstrap-push'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(input)
+    }));
+}
+export async function applyLocalWorkspaceChanges(workspaceId, changes) {
+    const applyPayload = JSON.stringify({ workspaceId, changes });
+    const resolveApplyLocalEndpoint = () => {
+        if (typeof window === 'undefined')
+            return '/api/taskforce/sync/workspace/apply-local';
+        const pathname = String(window.location?.pathname || '/');
+        if (pathname === '/taskforce' || pathname.startsWith('/taskforce/')) {
+            return '/taskforce/api/taskforce/sync/workspace/apply-local';
+        }
+        return '/api/taskforce/sync/workspace/apply-local';
+    };
+    const applyEndpoint = resolveApplyLocalEndpoint();
+    const failures = [];
+    try {
+        const response = await fetch(applyEndpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-taskforce-workspace-id': workspaceId
+            },
+            credentials: 'include',
+            body: applyPayload
+        });
+        if (response.ok) {
+            const data = await response.json().catch(() => ({}));
+            return { ok: true, data, failures };
+        }
+        failures.push(`${applyEndpoint}:${response.status}`);
+    }
+    catch {
+        failures.push(`${applyEndpoint}:network`);
+    }
+    return { ok: false, data: {}, failures };
+}

package/dist/sync/cloudSyncApi.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/cloudSyncApi.test.js

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { applyLocalWorkspaceChanges } from './cloudSyncApi';
+describe('cloudSyncApi.applyLocalWorkspaceChanges', () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+        window.history.replaceState({}, '', '/');
+    });
+    it('uses canonical local apply endpoint by default', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ success: true })
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const result = await applyLocalWorkspaceChanges('ws-1', [{ op: 'upsert', archived: false, task: { id: 't-1' } }]);
+        expect(result.ok).toBe(true);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(fetchMock).toHaveBeenCalledWith('/api/taskforce/sync/workspace/apply-local', expect.any(Object));
+    });
+    it('uses canonical /taskforce apply endpoint when running under /taskforce path', async () => {
+        window.history.replaceState({}, '', '/taskforce');
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ success: true })
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const result = await applyLocalWorkspaceChanges('ws-2', [{ op: 'delete', taskId: 't-2' }]);
+        expect(result.ok).toBe(true);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(fetchMock).toHaveBeenCalledWith('/taskforce/api/taskforce/sync/workspace/apply-local', expect.any(Object));
+    });
+    it('returns single-endpoint status diagnostics on non-ok response', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 503,
+            json: () => Promise.resolve({ error: 'unavailable' })
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const result = await applyLocalWorkspaceChanges('ws-3', [{ op: 'upsert', archived: false, task: { id: 't-3' } }]);
+        expect(result.ok).toBe(false);
+        expect(result.failures).toEqual(['/api/taskforce/sync/workspace/apply-local:503']);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it('returns single-endpoint network diagnostics on fetch error', async () => {
+        const fetchMock = vi.fn().mockRejectedValue(new Error('network down'));
+        vi.stubGlobal('fetch', fetchMock);
+        const result = await applyLocalWorkspaceChanges('ws-4', [{ op: 'upsert', archived: false, task: { id: 't-4' } }]);
+        expect(result.ok).toBe(false);
+        expect(result.failures).toEqual(['/api/taskforce/sync/workspace/apply-local:network']);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/sync/encryptionService.d.ts

@@ -0,0 +1,11 @@
+export declare const ENCRYPTION_PREFIX = "V1:AESGCM:";
+/**
+ * Encrypts a plaintext string into a base64 encoded payload with the V1 format.
+ * Format: `V1:AESGCM:<base64(iv)>:<base64(ciphertext)>`
+ */
+export declare function encryptDocument(plaintext: string, base64Key: string): Promise<string>;
+/**
+ * Decrypts a V1 format payload back into plaintext.
+ * Throws an error if the payload cannot be decrypted or format is invalid.
+ */
+export declare function decryptDocument(payload: string, base64Key: string): Promise<string>;

package/dist/sync/encryptionService.js

@@ -0,0 +1,61 @@
+export const ENCRYPTION_PREFIX = 'V1:AESGCM:';
+const ALGORITHM = 'AES-GCM';
+const IV_LENGTH_BYTES = 12;
+/**
+ * Derives a CryptoKey from a given 256-bit base64 string.
+ */
+async function importKey(base64Key) {
+    const keyBytes = Buffer.from(base64Key, 'base64');
+    if (keyBytes.length !== 32) {
+        throw new Error('Encryption key must be exactly 32 bytes (256-bit).');
+    }
+    return crypto.subtle.importKey('raw', keyBytes, { name: ALGORITHM }, false, ['encrypt', 'decrypt']);
+}
+/**
+ * Encrypts a plaintext string into a base64 encoded payload with the V1 format.
+ * Format: `V1:AESGCM:<base64(iv)>:<base64(ciphertext)>`
+ */
+export async function encryptDocument(plaintext, base64Key) {
+    if (!plaintext)
+        return plaintext;
+    // Generate an initialization vector
+    const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH_BYTES));
+    const key = await importKey(base64Key);
+    const encoder = new TextEncoder();
+    const encodedPlaintext = encoder.encode(plaintext);
+    const ciphertextBuffer = await crypto.subtle.encrypt({
+        name: ALGORITHM,
+        iv
+    }, key, encodedPlaintext);
+    const ciphertextBase64 = Buffer.from(ciphertextBuffer).toString('base64');
+    const ivBase64 = Buffer.from(iv).toString('base64');
+    return `${ENCRYPTION_PREFIX}${ivBase64}:${ciphertextBase64}`;
+}
+/**
+ * Decrypts a V1 format payload back into plaintext.
+ * Throws an error if the payload cannot be decrypted or format is invalid.
+ */
+export async function decryptDocument(payload, base64Key) {
+    if (!payload || !payload.startsWith(ENCRYPTION_PREFIX)) {
+        return payload; // Return as-is if not encrypted
+    }
+    const unmappedPayload = payload.slice(ENCRYPTION_PREFIX.length);
+    const [ivBase64, ciphertextBase64] = unmappedPayload.split(':');
+    if (!ivBase64 || !ciphertextBase64) {
+        throw new Error('Malformed encrypted document payload.');
+    }
+    const iv = Buffer.from(ivBase64, 'base64');
+    const ciphertext = Buffer.from(ciphertextBase64, 'base64');
+    const key = await importKey(base64Key);
+    try {
+        const decryptedBuffer = await crypto.subtle.decrypt({
+            name: ALGORITHM,
+            iv
+        }, key, ciphertext);
+        const decoder = new TextDecoder('utf-8');
+        return decoder.decode(decryptedBuffer);
+    }
+    catch (e) {
+        throw new Error(`Failed to decrypt document: ${e.message}`);
+    }
+}

package/dist/sync/encryptionService.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/encryptionService.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { encryptDocument, decryptDocument, ENCRYPTION_PREFIX } from './encryptionService';
+import crypto from 'crypto';
+// Polyfill node crypto to webcrypto for testing
+if (!globalThis.crypto) {
+    globalThis.crypto = crypto.webcrypto;
+}
+describe('AES-256-GCM Document Encryption', () => {
+    // 32-byte key in Base64
+    const TEST_SYNC_KEY = 'NmhazvMJ8D0kG5btEJtW0uh9rM4l+xOCray0cWFZyBE=';
+    // A distinct 32-byte key
+    const DIFFERENT_TEST_KEY = 'h/ONWavchmshsOGoNWOePgNdQAtbCMmVGqCLL5dzej4=';
+    it('should correctly encrypt and decrypt a markdown document', async () => {
+        const plaintext = '# Hello World\n\nThis is a secret task document.';
+        const ciphertext = await encryptDocument(plaintext, TEST_SYNC_KEY);
+        expect(ciphertext).toBeDefined();
+        expect(ciphertext.startsWith(ENCRYPTION_PREFIX)).toBe(true);
+        expect(ciphertext).not.toContain('Hello World');
+        const decrypted = await decryptDocument(ciphertext, TEST_SYNC_KEY);
+        expect(decrypted).toBe(plaintext);
+    });
+    it('should generate different ciphertexts for the exact same plaintext (random IV)', async () => {
+        const plaintext = 'Repeat after me: randomness is secure.';
+        const cipher1 = await encryptDocument(plaintext, TEST_SYNC_KEY);
+        const cipher2 = await encryptDocument(plaintext, TEST_SYNC_KEY);
+        expect(cipher1).not.toBe(cipher2);
+        expect(cipher1.startsWith(ENCRYPTION_PREFIX)).toBe(true);
+        expect(cipher2.startsWith(ENCRYPTION_PREFIX)).toBe(true);
+    });
+    it('should fail to decrypt with the wrong key (Auth Tag mismatch / Bad Mac)', async () => {
+        const plaintext = 'Secret Document';
+        const ciphertext = await encryptDocument(plaintext, TEST_SYNC_KEY);
+        await expect(decryptDocument(ciphertext, DIFFERENT_TEST_KEY)).rejects.toThrow('Failed to decrypt document');
+    });
+    it('should ignore and pass through unencrypted plaintexts during decryption', async () => {
+        const plaintext = 'I am just a normal document.';
+        const result = await decryptDocument(plaintext, TEST_SYNC_KEY);
+        expect(result).toBe(plaintext);
+    });
+    it('should return empty string if asked to encrypt empty input', async () => {
+        const ciphertext = await encryptDocument('', TEST_SYNC_KEY);
+        expect(ciphertext).toBe('');
+    });
+    it('should gracefully handle empty or invalid decryption payloads', async () => {
+        await expect(decryptDocument(`${ENCRYPTION_PREFIX}invalid`, TEST_SYNC_KEY)).rejects.toThrow('Malformed encrypted document payload.');
+        await expect(decryptDocument(`${ENCRYPTION_PREFIX}validBase64=`, TEST_SYNC_KEY)).rejects.toThrow('Malformed encrypted document payload.');
+    });
+    it('should throw immediately if the provided encryption key is not 256-bit (32 bytes)', async () => {
+        const tooShortKey = Buffer.from('too short key').toString('base64');
+        await expect(encryptDocument('test', tooShortKey)).rejects.toThrow('Encryption key must be exactly 32 bytes (256-bit).');
+    });
+});

package/dist/sync/realtimeFeature.d.ts

@@ -0,0 +1,6 @@
+export type RealtimeSyncFlagSource = 'env' | 'global' | 'default';
+export interface RealtimeSyncFlagResolution {
+    enabled: boolean;
+    source: RealtimeSyncFlagSource;
+}
+export declare function resolveRealtimeSyncFlag(env: NodeJS.ProcessEnv, globalSetting?: boolean): RealtimeSyncFlagResolution;

package/dist/sync/realtimeFeature.js

@@ -0,0 +1,20 @@
+function parseBoolean(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized)
+        return null;
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    return null;
+}
+export function resolveRealtimeSyncFlag(env, globalSetting) {
+    const envValue = parseBoolean(env.TASKFORCE_REALTIME_SYNC);
+    if (envValue !== null) {
+        return { enabled: envValue, source: 'env' };
+    }
+    if (typeof globalSetting === 'boolean') {
+        return { enabled: globalSetting, source: 'global' };
+    }
+    return { enabled: false, source: 'default' };
+}

package/dist/sync/realtimeFeature.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/realtimeFeature.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { resolveRealtimeSyncFlag } from './realtimeFeature';
+describe('sync/realtimeFeature', () => {
+    it('defaults to disabled when neither env nor global setting is provided', () => {
+        expect(resolveRealtimeSyncFlag({})).toEqual({
+            enabled: false,
+            source: 'default'
+        });
+    });
+    it('uses global setting when env is unset', () => {
+        expect(resolveRealtimeSyncFlag({}, true)).toEqual({
+            enabled: true,
+            source: 'global'
+        });
+        expect(resolveRealtimeSyncFlag({}, false)).toEqual({
+            enabled: false,
+            source: 'global'
+        });
+    });
+    it('env override takes precedence over global setting', () => {
+        expect(resolveRealtimeSyncFlag({ TASKFORCE_REALTIME_SYNC: 'true' }, false)).toEqual({
+            enabled: true,
+            source: 'env'
+        });
+        expect(resolveRealtimeSyncFlag({ TASKFORCE_REALTIME_SYNC: '0' }, true)).toEqual({
+            enabled: false,
+            source: 'env'
+        });
+    });
+});

package/dist/sync/realtimeReconcile.d.ts

@@ -0,0 +1,30 @@
+export type RealtimeDiscardReason = 'duplicate' | 'out-of-order' | 'invalid';
+export interface RealtimeReconcileInput {
+    eventId?: unknown;
+    serverEpoch?: unknown;
+    seq?: unknown;
+}
+export interface RealtimeReconcileResult {
+    accepted: boolean;
+    reason?: RealtimeDiscardReason;
+    shouldRecover: boolean;
+}
+export interface RealtimeReconcileTelemetry {
+    accepted: number;
+    duplicateDiscarded: number;
+    outOfOrderDiscarded: number;
+    invalidDiscarded: number;
+    recoveryTriggered: number;
+}
+export declare class RealtimeReconcileTracker {
+    private readonly maxSeenEventIds;
+    private seenEventIds;
+    private seenEventIdQueue;
+    private activeEpoch;
+    private lastSeq;
+    private telemetry;
+    constructor(maxSeenEventIds?: number);
+    process(input: RealtimeReconcileInput): RealtimeReconcileResult;
+    getTelemetry(): RealtimeReconcileTelemetry;
+    private rememberEventId;
+}

package/dist/sync/realtimeReconcile.js

@@ -0,0 +1,90 @@
+export class RealtimeReconcileTracker {
+    maxSeenEventIds;
+    seenEventIds = new Set();
+    seenEventIdQueue = [];
+    activeEpoch = '';
+    lastSeq = null;
+    telemetry = {
+        accepted: 0,
+        duplicateDiscarded: 0,
+        outOfOrderDiscarded: 0,
+        invalidDiscarded: 0,
+        recoveryTriggered: 0
+    };
+    constructor(maxSeenEventIds = 2048) {
+        this.maxSeenEventIds = maxSeenEventIds;
+    }
+    process(input) {
+        const eventId = typeof input.eventId === 'string' ? input.eventId.trim() : '';
+        if (eventId && this.seenEventIds.has(eventId)) {
+            this.telemetry.duplicateDiscarded += 1;
+            return { accepted: false, reason: 'duplicate', shouldRecover: false };
+        }
+        const serverEpoch = typeof input.serverEpoch === 'string' ? input.serverEpoch.trim() : '';
+        const seq = Number(input.seq);
+        const hasOrderedCursor = serverEpoch.length > 0 && Number.isFinite(seq) && seq >= 0;
+        if (!hasOrderedCursor) {
+            if (eventId) {
+                this.rememberEventId(eventId);
+                this.telemetry.accepted += 1;
+                return { accepted: true, shouldRecover: false };
+            }
+            this.telemetry.invalidDiscarded += 1;
+            return { accepted: false, reason: 'invalid', shouldRecover: false };
+        }
+        const normalizedSeq = Math.floor(seq);
+        if (this.activeEpoch && this.activeEpoch !== serverEpoch) {
+            this.activeEpoch = serverEpoch;
+            this.lastSeq = normalizedSeq;
+            if (eventId)
+                this.rememberEventId(eventId);
+            this.telemetry.accepted += 1;
+            return { accepted: true, shouldRecover: false };
+        }
+        if (!this.activeEpoch) {
+            this.activeEpoch = serverEpoch;
+            this.lastSeq = normalizedSeq;
+            if (eventId)
+                this.rememberEventId(eventId);
+            this.telemetry.accepted += 1;
+            return { accepted: true, shouldRecover: false };
+        }
+        const previous = this.lastSeq;
+        if (typeof previous === 'number') {
+            if (normalizedSeq <= previous) {
+                this.telemetry.outOfOrderDiscarded += (normalizedSeq === previous ? 0 : 1);
+                this.telemetry.duplicateDiscarded += (normalizedSeq === previous ? 1 : 0);
+                const shouldRecover = normalizedSeq < previous;
+                if (shouldRecover)
+                    this.telemetry.recoveryTriggered += 1;
+                return {
+                    accepted: false,
+                    reason: normalizedSeq === previous ? 'duplicate' : 'out-of-order',
+                    shouldRecover
+                };
+            }
+            if (normalizedSeq > previous + 1) {
+                this.telemetry.outOfOrderDiscarded += 1;
+                this.telemetry.recoveryTriggered += 1;
+                return { accepted: false, reason: 'out-of-order', shouldRecover: true };
+            }
+        }
+        this.lastSeq = normalizedSeq;
+        if (eventId)
+            this.rememberEventId(eventId);
+        this.telemetry.accepted += 1;
+        return { accepted: true, shouldRecover: false };
+    }
+    getTelemetry() {
+        return { ...this.telemetry };
+    }
+    rememberEventId(eventId) {
+        this.seenEventIds.add(eventId);
+        this.seenEventIdQueue.push(eventId);
+        while (this.seenEventIdQueue.length > this.maxSeenEventIds) {
+            const drop = this.seenEventIdQueue.shift();
+            if (drop)
+                this.seenEventIds.delete(drop);
+        }
+    }
+}

package/dist/sync/realtimeReconcile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/realtimeReconcile.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { RealtimeReconcileTracker } from './realtimeReconcile';
+describe('RealtimeReconcileTracker', () => {
+    it('accepts ordered events and discards duplicate eventId safely', () => {
+        const tracker = new RealtimeReconcileTracker();
+        const first = tracker.process({ eventId: 'epoch-1:1', serverEpoch: 'epoch-1', seq: 1 });
+        const duplicate = tracker.process({ eventId: 'epoch-1:1', serverEpoch: 'epoch-1', seq: 1 });
+        expect(first.accepted).toBe(true);
+        expect(duplicate.accepted).toBe(false);
+        expect(duplicate.reason).toBe('duplicate');
+        expect(duplicate.shouldRecover).toBe(false);
+        const telemetry = tracker.getTelemetry();
+        expect(telemetry.accepted).toBe(1);
+        expect(telemetry.duplicateDiscarded).toBe(1);
+    });
+    it('flags out-of-order gaps for recovery', () => {
+        const tracker = new RealtimeReconcileTracker();
+        tracker.process({ eventId: 'epoch-1:1', serverEpoch: 'epoch-1', seq: 1 });
+        const gap = tracker.process({ eventId: 'epoch-1:3', serverEpoch: 'epoch-1', seq: 3 });
+        expect(gap.accepted).toBe(false);
+        expect(gap.reason).toBe('out-of-order');
+        expect(gap.shouldRecover).toBe(true);
+        const telemetry = tracker.getTelemetry();
+        expect(telemetry.outOfOrderDiscarded).toBe(1);
+        expect(telemetry.recoveryTriggered).toBe(1);
+    });
+    it('accepts new epoch as ordered reset baseline', () => {
+        const tracker = new RealtimeReconcileTracker();
+        tracker.process({ eventId: 'epoch-1:5', serverEpoch: 'epoch-1', seq: 5 });
+        const nextEpoch = tracker.process({ eventId: 'epoch-2:1', serverEpoch: 'epoch-2', seq: 1 });
+        expect(nextEpoch.accepted).toBe(true);
+        expect(nextEpoch.shouldRecover).toBe(false);
+    });
+    it('treats same epoch/seq with different eventId as duplicate no-op', () => {
+        const tracker = new RealtimeReconcileTracker();
+        const first = tracker.process({ eventId: 'epoch-1:7', serverEpoch: 'epoch-1', seq: 7 });
+        const duplicateSeq = tracker.process({ eventId: 'epoch-1:7b', serverEpoch: 'epoch-1', seq: 7 });
+        expect(first.accepted).toBe(true);
+        expect(duplicateSeq.accepted).toBe(false);
+        expect(duplicateSeq.reason).toBe('duplicate');
+        expect(duplicateSeq.shouldRecover).toBe(false);
+    });
+});

package/dist/sync/syncService.d.ts

@@ -0,0 +1,96 @@
+import type { WorkspaceSyncPayload } from './workspaceSyncModel';
+export interface EnsureWorkspaceReadyInput {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    isAuthenticated: boolean;
+    resolveCloudAuthUrl: (path: string) => string;
+    workspaceId: string;
+    workspaceName: string;
+}
+export interface EnsureWorkspaceReadyResult {
+    success: boolean;
+    provisioned?: boolean;
+    error?: string;
+    /** HTTP status code from the handshake/provision step, if it failed. */
+    statusCode?: number;
+    /** Milliseconds to wait before retrying, forwarded from a 429 Retry-After header. */
+    retryAfterMs?: number;
+}
+export declare function ensureCloudWorkspaceReadyForSyncService(input: EnsureWorkspaceReadyInput): Promise<EnsureWorkspaceReadyResult>;
+export interface UserSettingsSyncInput {
+    resolveCloudAuthUrl: (path: string) => string;
+    userId: string;
+    preferCloudOnFirstSync: boolean;
+    getLocalUpdatedAt: (userId: string) => string | null;
+    buildLocalSettings: () => Record<string, unknown>;
+    applyRemoteSettings: (settings: Record<string, unknown>) => Promise<void>;
+}
+export interface UserSettingsSyncResult {
+    success: boolean;
+    mode?: 'pulled' | 'pushed';
+    updatedAt?: string;
+    error?: string;
+    statusCode?: number;
+    retryAfterMs?: number;
+    transient?: boolean;
+}
+export interface WorkspacePushSyncInput {
+    resolveCloudAuthUrl: (path: string) => string;
+    workspaceId: string;
+    payload: WorkspaceSyncPayload;
+    ensureCloudWorkspaceReadyForSync: () => Promise<EnsureWorkspaceReadyResult>;
+}
+export interface WorkspacePushSyncResult {
+    success: boolean;
+    status?: number;
+    error?: string;
+    code?: string;
+    retryAfterMs?: number;
+    syncedAt?: string;
+    requestMs: number;
+    changeCount: number;
+    deleteCount: number;
+    currentTaskIds: Set<string>;
+    deleteTaskIds: Set<string>;
+    currentDocumentPaths: Set<string>;
+    deleteDocumentPaths: Set<string>;
+    currentDocumentWatermarks: Map<string, string>;
+    /** Watermarks for every task upsert that was successfully pushed. */
+    pushedWatermarks: Map<string, string>;
+    /** Server-emitted realtime mutation event ids for this push apply. */
+    emittedEventIds: string[];
+}
+export declare function runWorkspacePushSyncService(input: WorkspacePushSyncInput): Promise<WorkspacePushSyncResult>;
+export type WorkspacePullFailureKind = 'pull_http' | 'apply_auth' | 'apply_all_candidates' | 'apply_payload' | 'exception';
+export interface WorkspacePullSyncInput {
+    resolveCloudAuthUrl: (path: string) => string;
+    workspaceId: string;
+    cursor: string | null;
+    bootstrap: boolean;
+    ensureCloudWorkspaceReadyForSync?: () => Promise<EnsureWorkspaceReadyResult>;
+    maxPages?: number;
+    onPagePulled?: () => void;
+    onChangesApplied?: (count: number) => void;
+}
+export interface WorkspacePullSyncResult {
+    success: boolean;
+    kind?: WorkspacePullFailureKind;
+    status?: number;
+    retryAfterMs?: number;
+    failures?: string[];
+    hasTransientApplyFailure?: boolean;
+    error?: string;
+    syncedAt?: string;
+    cursor: string | null;
+    pages: number;
+    appliedChanges: number;
+    pullRequestMs: number;
+    applyMs: number;
+    pulledDeleteTaskIds: Set<string>;
+    pulledActiveUpserts: boolean;
+    pulledArchivedUpserts: boolean;
+    documentDecryptFailures?: string[];
+}
+export declare function runWorkspacePullSyncService(input: WorkspacePullSyncInput): Promise<WorkspacePullSyncResult>;
+export declare function syncUserGlobalSettingsService(input: UserSettingsSyncInput): Promise<UserSettingsSyncResult>;
+export declare function calculateWorkspaceRetryDelayMs(attempt: number): number;