@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/sync/syncApplyHandlers.test.js

@@ -1,9 +1,16 @@
-import { describe, expect, it, vi } from 'vitest';
-import { applyCollaborationSyncChanges, applyContentSyncChanges, applyPreparedTaskSyncSnapshot, applyTaskSyncDeletes, classifyWorkspaceSyncChanges, prepareTaskSyncSnapshotApply, } from './syncApplyHandlers.js';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { applyCollaborationSyncChanges, applyContentSyncChanges, applyPlanningSyncChanges, applyPreparedTaskSyncSnapshot, applyTaskActivitySyncChanges, applyTaskSyncDeletes, classifyWorkspaceSyncChanges, prepareTaskSyncSnapshotApply, } from './syncApplyHandlers.js';
 function createCoreFixture(overrides = {}) {
     return {
         resolveTaskIdentifier: vi.fn().mockReturnValue(null),
         getTask: vi.fn().mockReturnValue(null),
+        taskExistsForSync: vi.fn().mockReturnValue(true),
+        initiativeExistsForSync: vi.fn().mockReturnValue(true),
+        workstreamExistsForSync: vi.fn().mockReturnValue(true),
+        getTaskEventForSync: vi.fn().mockReturnValue(null),
+        getEntityEventForSync: vi.fn().mockReturnValue(null),
         deleteTaskForSync: vi.fn(),
         applyWorkspaceSyncSnapshot: vi.fn().mockReturnValue({
             total: 1,
@@ -29,6 +36,9 @@ function createCoreFixture(overrides = {}) {
     };
 }
 describe('syncApplyHandlers', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
     it('classifies task and workstream changes, then prepares and applies the task snapshot pipeline', () => {
         const diagnostics = [];
         const workspaceId = 'workspace-1';
@@ -87,6 +97,7 @@ describe('syncApplyHandlers', () => {
             normalizeWorkspaceSyncDocumentPath: (rawPath) => typeof rawPath === 'string' ? rawPath : null,
             normalizeTaskAssetPath: (rawPath) => typeof rawPath === 'string' ? rawPath : null,
             normalizeIncomingAiProfileSurfaceType: () => null,
+            normalizeIncomingAiProfileSeatScope: () => null,
             normalizeTaskEventSyncPayload: () => null,
             recordSyncDiagnostic: (targetWorkspaceId, eventType, message, details) => {
                 diagnostics.push({ workspaceId: targetWorkspaceId, eventType, message, details });
@@ -179,6 +190,84 @@ describe('syncApplyHandlers', () => {
         }, workspaceId);
         expect(result).toEqual(expect.objectContaining({ total: 1 }));
     });
+    it('preserves planning attachments when applying initiative and workstream sync changes', () => {
+        const core = createCoreFixture({
+            upsertInitiativeForSync: vi.fn(),
+            upsertWorkstreamForSync: vi.fn(),
+            updateTaxonomies: vi.fn(),
+        });
+        applyPlanningSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingInitiatives: new Map([
+                ['initiative-1', {
+                        id: 'initiative-1',
+                        referenceNumber: 12,
+                        referenceLabel: 'I-12',
+                        title: 'Initiative',
+                        description: 'Initiative description',
+                        ownerId: null,
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T10:00:00.000Z',
+                        order: 1,
+                        attachments: [{
+                                path: '/api/taskforce/documents/asset-init-doc/content',
+                                fsPath: 'workspaces/workspace-1/assets/documents/initiative.md',
+                                assetId: 'asset-init-doc',
+                                caption: 'Initiative context',
+                                timestamp: '2026-04-10T10:00:00.000Z'
+                            }],
+                        isArchived: false,
+                    }],
+            ]),
+            incomingWorkstreams: new Map([
+                ['workstream-1', {
+                        id: 'workstream-1',
+                        referenceNumber: 689,
+                        referenceLabel: 'WS-689',
+                        initiativeId: 'initiative-1',
+                        title: 'Security Audit Remediation',
+                        description: 'Workstream description',
+                        ownerId: null,
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T10:00:00.000Z',
+                        order: 2,
+                        attachments: [{
+                                path: '/api/taskforce/documents/asset-workstream-doc/content',
+                                fsPath: 'workspaces/workspace-1/assets/documents/security-findings-register.md',
+                                assetId: 'asset-workstream-doc',
+                                caption: 'Living security findings register for WS-689',
+                                timestamp: '2026-04-10T10:00:00.000Z'
+                            }],
+                        isArchived: false,
+                    }],
+            ]),
+            incomingTaxonomies: null,
+            incomingTaxonomyState: null,
+            incomingTaxonomiesUpdatedAt: '',
+            workspaceTaxonomySyncMeta: new Map(),
+            recordSyncDiagnostic: vi.fn(),
+        });
+        expect(core.upsertInitiativeForSync).toHaveBeenCalledWith(expect.objectContaining({
+            id: 'initiative-1',
+            attachments: [
+                expect.objectContaining({
+                    assetId: 'asset-init-doc',
+                    caption: 'Initiative context'
+                })
+            ]
+        }), 'workspace-1');
+        expect(core.upsertWorkstreamForSync).toHaveBeenCalledWith(expect.objectContaining({
+            id: 'workstream-1',
+            referenceLabel: 'WS-689',
+            attachments: [
+                expect.objectContaining({
+                    assetId: 'asset-workstream-doc',
+                    caption: 'Living security findings register for WS-689'
+                })
+            ]
+        }), 'workspace-1');
+    });
     it('applies document and asset changes through the content handler helpers', async () => {
         const core = createCoreFixture();
         const writeWorkspaceSyncDocument = vi.fn().mockResolvedValue(undefined);
@@ -231,7 +320,7 @@ describe('syncApplyHandlers', () => {
         expect(core.notifyDocumentMetadataMutation).toHaveBeenNthCalledWith(1, 'workspace-1', ['docs/spec.md', 'assets/proof.png'], 'upsert');
         expect(core.notifyDocumentMetadataMutation).toHaveBeenNthCalledWith(2, 'workspace-1', ['docs/stale.md', 'assets/stale.png'], 'delete');
     });
-    it('only allows reference reassignment for content writes when the content changed or repair is explicit', async () => {
+    it('allows reference reassignment when metadata drift requires normal sync convergence', async () => {
         const core = createCoreFixture({
             getDocumentWatermark: vi.fn().mockReturnValue(null),
         });
@@ -280,9 +369,112 @@ describe('syncApplyHandlers', () => {
             }),
             recordSyncDiagnostic: vi.fn(),
         });
-        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md' }), 'workspace-1', { allowReferenceNumberReassignment: false });
+        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md' }), 'workspace-1', { allowReferenceNumberReassignment: true });
         expect(writeWorkspaceSyncBinaryAsset).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'assets/proof.png' }), 'workspace-1', { allowReferenceNumberReassignment: true });
     });
+    it('reuses persisted content hashes instead of re-reading unchanged local files while reasserting object storage payloads', async () => {
+        const existingDocContent = '# Spec';
+        const existingAssetBytes = Buffer.from('png-bytes');
+        const core = createCoreFixture({
+            getDocumentWatermark: vi.fn().mockReturnValue({
+                updatedAt: '2026-04-10T10:00:00.000Z',
+                contentHash: createHash('sha256').update(existingDocContent).digest('hex'),
+            }),
+        });
+        const writeWorkspaceSyncDocument = vi.fn().mockResolvedValue(undefined);
+        const writeWorkspaceSyncBinaryAsset = vi.fn().mockResolvedValue(undefined);
+        const readSpy = vi.spyOn(fs, 'readFileSync').mockImplementation(((targetPath) => {
+            const value = String(targetPath);
+            if (value.endsWith('spec.md'))
+                return existingDocContent;
+            return existingAssetBytes;
+        }));
+        await applyContentSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingDocuments: [
+                {
+                    path: 'docs/spec.md',
+                    updatedAt: '2026-04-10T10:00:00.000Z',
+                    content: existingDocContent,
+                    assetId: 'asset-doc-1',
+                },
+            ],
+            incomingDocumentDeletes: new Map(),
+            incomingAssets: [
+                {
+                    path: 'assets/proof.png',
+                    updatedAt: '2026-04-10T10:05:00.000Z',
+                    contentBase64: existingAssetBytes.toString('base64'),
+                    assetId: 'asset-image-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                },
+            ],
+            incomingAssetDeletes: new Map(),
+            basePath: '/tmp/taskforce-sync-content',
+            hasObjectStorageClient: () => true,
+            hasDocumentSyncMetadataDrift: () => false,
+            hasBinaryAssetSyncMetadataDrift: () => false,
+            getExistingDocument: () => {
+                throw new Error('document fallback should not be used when persisted metadata exists');
+            },
+            writeWorkspaceSyncDocument,
+            deleteWorkspaceSyncDocument: vi.fn(),
+            writeWorkspaceSyncBinaryAsset,
+            deleteWorkspaceSyncBinaryAsset: vi.fn(),
+            getExistingBinaryAsset: () => ({
+                updatedAt: '2026-04-10T10:05:00.000Z',
+                contentSha256: createHash('sha256').update(existingAssetBytes).digest('hex'),
+            }),
+            recordSyncDiagnostic: vi.fn(),
+        });
+        expect(readSpy).not.toHaveBeenCalled();
+        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md', assetId: 'asset-doc-1' }), 'workspace-1', { allowReferenceNumberReassignment: false });
+        expect(writeWorkspaceSyncBinaryAsset).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'assets/proof.png', assetId: 'asset-image-1' }), 'workspace-1', { allowReferenceNumberReassignment: false });
+    });
+    it('rejects synced content applies when a binary asset write fails', async () => {
+        const core = createCoreFixture();
+        const recordSyncDiagnostic = vi.fn();
+        await expect(applyContentSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingDocuments: [],
+            incomingDocumentDeletes: new Map(),
+            incomingAssets: [
+                {
+                    path: 'assets/proof.png',
+                    updatedAt: '2026-04-10T10:05:00.000Z',
+                    contentBase64: Buffer.from('png-bytes').toString('base64'),
+                    assetId: 'asset-image-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                },
+            ],
+            incomingAssetDeletes: new Map(),
+            basePath: '/tmp/taskforce-sync-content',
+            hasObjectStorageClient: () => true,
+            hasDocumentSyncMetadataDrift: () => false,
+            hasBinaryAssetSyncMetadataDrift: () => false,
+            getExistingDocument: () => null,
+            writeWorkspaceSyncDocument: vi.fn(),
+            deleteWorkspaceSyncDocument: vi.fn(),
+            writeWorkspaceSyncBinaryAsset: vi.fn().mockRejectedValue(new Error('R2 write failed')),
+            deleteWorkspaceSyncBinaryAsset: vi.fn(),
+            getExistingBinaryAsset: () => null,
+            recordSyncDiagnostic,
+        })).rejects.toMatchObject({
+            code: 'SYNC_CONTENT_APPLY_FAILED',
+            statusCode: 500,
+        });
+        expect(recordSyncDiagnostic).toHaveBeenCalledWith('workspace-1', 'apply', 'Failed to apply synced asset change.', expect.objectContaining({
+            source: 'assets.apply.write',
+            path: 'assets/proof.png',
+            assetId: 'asset-image-1',
+            kind: 'image',
+            error: 'R2 write failed'
+        }));
+    });
     it('applies collaboration upserts and deletes through the collaboration handlers', () => {
         const core = createCoreFixture();
         applyCollaborationSyncChanges({
@@ -376,4 +568,59 @@ describe('syncApplyHandlers', () => {
             deletedAt: '2026-04-10T11:10:00.000Z',
         });
     });
+    it('applies entity events through lean sync lookups instead of hydrated entity activity reads', () => {
+        const core = createCoreFixture({
+            taskExistsForSync: vi.fn().mockReturnValue(true),
+            getEntityEventForSync: vi.fn().mockReturnValue(null),
+            listTaskEvents: vi.fn(() => {
+                throw new Error('hydrated task activity lookup should not run during sync apply');
+            }),
+            getTask: vi.fn(() => {
+                throw new Error('hydrated task lookup should not run during sync apply');
+            }),
+            getInitiative: vi.fn(() => {
+                throw new Error('hydrated initiative lookup should not run during sync apply');
+            }),
+            getWorkstream: vi.fn(() => {
+                throw new Error('hydrated workstream lookup should not run during sync apply');
+            }),
+            listEntityEventsForSync: vi.fn(() => {
+                throw new Error('hydrated entity event listing should not run during sync apply');
+            }),
+            upsertEntityEventForSync: vi.fn(),
+        });
+        applyTaskActivitySyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingTaskEvents: new Map([
+                ['task-event-1', {
+                        id: 'task-event-1',
+                        taskId: 'task-1',
+                        entityType: 'task',
+                        entityId: 'task-1',
+                        workspaceId: 'workspace-1',
+                        action: 'task-updated',
+                        actor: 'user-1',
+                        actorType: 'human',
+                        details: { changes: { status: { from: 'task', to: 'review' } } },
+                        createdAt: '2026-04-10T10:00:00.000Z',
+                    }],
+            ]),
+            recordSyncDiagnostic: vi.fn(),
+            createSyncRouteError: (message, details) => Object.assign(new Error(message), { details }),
+        });
+        expect(core.taskExistsForSync).toHaveBeenCalledWith('task-1', 'workspace-1');
+        expect(core.getEntityEventForSync).toHaveBeenCalledWith({
+            workspaceId: 'workspace-1',
+            eventId: 'task-event-1',
+        });
+        expect(core.upsertEntityEventForSync).toHaveBeenCalledWith(expect.objectContaining({
+            id: 'task-event-1',
+            taskId: 'task-1',
+            entityType: 'task',
+            entityId: 'task-1',
+            workspaceId: 'workspace-1',
+            action: 'task-updated',
+        }));
+    });
 });

package/dist/sync/syncFieldSemantics.d.ts

@@ -0,0 +1,12 @@
+export declare function hasOwnSyncField(source: unknown, field: string): boolean;
+export declare function normalizeSyncOptionalString(value: unknown): string | undefined;
+export declare function normalizeSyncNullableString(value: unknown): string | null;
+export declare function normalizeSyncOptionalId(value: unknown): string | undefined;
+export declare function normalizeSyncNullableId(value: unknown): string | null;
+export declare function normalizeSyncNullableIsoString(value: unknown): string | null;
+export declare function normalizeSyncSameOriginAssetUrl(value: unknown): string | null;
+export declare function readSyncOptionalStringField(source: Record<string, unknown>, field: string): string | undefined;
+export declare function readSyncNullableStringField(source: Record<string, unknown>, field: string): string | null | undefined;
+export declare function readSyncNullableIdField(source: Record<string, unknown>, field: string): string | null | undefined;
+export declare function readSyncNullableIsoStringField(source: Record<string, unknown>, field: string): string | null | undefined;
+export declare function readSyncSameOriginAssetUrlField(source: Record<string, unknown>, field: string): string | null | undefined;

package/dist/sync/syncFieldSemantics.js

@@ -0,0 +1,55 @@
+export function hasOwnSyncField(source, field) {
+    return Boolean(source) && typeof source === 'object' && Object.prototype.hasOwnProperty.call(source, field);
+}
+export function normalizeSyncOptionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+export function normalizeSyncNullableString(value) {
+    if (value === undefined || value === null)
+        return null;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : null;
+}
+export function normalizeSyncOptionalId(value) {
+    return normalizeSyncOptionalString(value);
+}
+export function normalizeSyncNullableId(value) {
+    return normalizeSyncNullableString(value);
+}
+export function normalizeSyncNullableIsoString(value) {
+    return normalizeSyncNullableString(value);
+}
+export function normalizeSyncSameOriginAssetUrl(value) {
+    const normalized = normalizeSyncNullableString(value);
+    if (!normalized)
+        return null;
+    return normalized.startsWith('/api/taskforce/context/') ? normalized : null;
+}
+export function readSyncOptionalStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncOptionalString(source[field]);
+}
+export function readSyncNullableStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableString(source[field]);
+}
+export function readSyncNullableIdField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableId(source[field]);
+}
+export function readSyncNullableIsoStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableIsoString(source[field]);
+}
+export function readSyncSameOriginAssetUrlField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncSameOriginAssetUrl(source[field]);
+}

package/dist/sync/syncResourceAdapters.d.ts

@@ -0,0 +1,46 @@
+import type { TaskItem } from '../types.js';
+export interface SyncAiProfileLike {
+    id?: string | null;
+    workspaceId?: string | null;
+    profileToken?: string | null;
+    name?: string | null;
+    username?: string | null;
+    icon?: string | null;
+    color?: string | null;
+    avatarUrl?: string | null;
+    avatarSourceUrl?: string | null;
+    avatarRevision?: number | null;
+    avatarUpdatedAt?: string | null;
+    description?: string | null;
+    role?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    surfaceType?: string | null;
+    seatScope?: string | null;
+    providerMetadata?: Record<string, unknown> | null;
+    archivedAt?: string | null;
+    archivedBy?: string | null;
+    archivedReason?: string | null;
+    mergedIntoProfileId?: string | null;
+    rosterStateUpdatedAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    lastActiveAt?: string | null;
+}
+export interface SyncResourceAdapter<T> {
+    kind: string;
+    getId: (resource: T) => string;
+    getWatermark: (resource: T) => string;
+    getChangeKey: (resource: T) => string;
+}
+export interface SyncResourceBaselineState {
+    watermarks?: Map<string, string> | null;
+    changeKeys?: Map<string, string> | null;
+}
+export declare function getAiProfileSyncWatermark(profile: Partial<SyncAiProfileLike> | null | undefined): string;
+export declare function getAiProfileSyncChangeKey(profile: Partial<SyncAiProfileLike> | null | undefined): string;
+export declare const taskSyncResourceAdapter: SyncResourceAdapter<Partial<TaskItem> & {
+    isArchived?: boolean | null;
+}>;
+export declare const aiProfileSyncResourceAdapter: SyncResourceAdapter<Partial<SyncAiProfileLike>>;
+export declare function shouldSyncResource<T>(adapter: SyncResourceAdapter<T>, resource: T, baseline?: SyncResourceBaselineState | null): boolean;

package/dist/sync/syncResourceAdapters.js

@@ -0,0 +1,79 @@
+import { buildTaskSyncChangeKey } from './taskSyncChangeKey.js';
+import { normalizeSyncNullableIsoString, normalizeSyncNullableString, normalizeSyncOptionalId, normalizeSyncSameOriginAssetUrl, } from './syncFieldSemantics.js';
+function normalizeSyncTimestampMax(...values) {
+    return values.reduce((latest, value) => {
+        const normalized = normalizeSyncNullableIsoString(value) || '';
+        if (!latest)
+            return normalized;
+        if (!normalized)
+            return latest;
+        return normalized > latest ? normalized : latest;
+    }, '');
+}
+export function getAiProfileSyncWatermark(profile) {
+    const source = profile || {};
+    return normalizeSyncTimestampMax(source.createdAt, source.updatedAt, source.lastActiveAt, source.archivedAt, source.rosterStateUpdatedAt);
+}
+export function getAiProfileSyncChangeKey(profile) {
+    const source = profile || {};
+    return JSON.stringify({
+        id: String(source.id || '').trim(),
+        workspaceId: String(source.workspaceId || '').trim(),
+        profileToken: String(source.profileToken || '').trim(),
+        name: String(source.name || '').trim(),
+        username: String(source.username || '').trim(),
+        icon: String(source.icon || 'Bot').trim() || 'Bot',
+        color: String(source.color || '#8b5cf6').trim() || '#8b5cf6',
+        avatarUrl: normalizeSyncSameOriginAssetUrl(source.avatarUrl) || '',
+        avatarSourceUrl: normalizeSyncSameOriginAssetUrl(source.avatarSourceUrl) || '',
+        avatarRevision: Number.isFinite(Number(source.avatarRevision)) ? Math.max(0, Math.floor(Number(source.avatarRevision))) : 0,
+        avatarUpdatedAt: normalizeSyncNullableIsoString(source.avatarUpdatedAt) || '',
+        description: normalizeSyncNullableString(source.description) || '',
+        role: normalizeSyncNullableString(source.role) || '',
+        provider: normalizeSyncNullableString(source.provider) || '',
+        model: normalizeSyncNullableString(source.model) || '',
+        surfaceType: normalizeSyncNullableString(source.surfaceType) || '',
+        seatScope: normalizeSyncNullableString(source.seatScope) || '',
+        providerMetadata: source.providerMetadata && typeof source.providerMetadata === 'object' && !Array.isArray(source.providerMetadata)
+            ? source.providerMetadata
+            : null,
+        archivedAt: normalizeSyncNullableIsoString(source.archivedAt) || '',
+        archivedBy: normalizeSyncOptionalId(source.archivedBy) || '',
+        archivedReason: normalizeSyncNullableString(source.archivedReason) || '',
+        mergedIntoProfileId: normalizeSyncOptionalId(source.mergedIntoProfileId) || '',
+        rosterStateUpdatedAt: normalizeSyncNullableIsoString(source.rosterStateUpdatedAt) || '',
+        createdAt: normalizeSyncNullableIsoString(source.createdAt) || '',
+        updatedAt: normalizeSyncNullableIsoString(source.updatedAt) || '',
+        lastActiveAt: normalizeSyncNullableIsoString(source.lastActiveAt) || '',
+    });
+}
+export const taskSyncResourceAdapter = {
+    kind: 'task',
+    getId: (task) => String(task?.id || '').trim(),
+    getWatermark: (task) => String(task?.updatedAt || task?.createdAt || '').trim(),
+    getChangeKey: (task) => buildTaskSyncChangeKey(task, Boolean(task?.isArchived))
+};
+export const aiProfileSyncResourceAdapter = {
+    kind: 'ai-profile',
+    getId: (profile) => String(profile?.id || '').trim(),
+    getWatermark: (profile) => getAiProfileSyncWatermark(profile),
+    getChangeKey: (profile) => getAiProfileSyncChangeKey(profile)
+};
+export function shouldSyncResource(adapter, resource, baseline) {
+    const id = adapter.getId(resource);
+    if (!id)
+        return false;
+    const currentChangeKey = adapter.getChangeKey(resource);
+    const previousWatermarks = baseline?.watermarks;
+    if (!previousWatermarks || previousWatermarks.size === 0)
+        return true;
+    if (!previousWatermarks.has(id))
+        return true;
+    const previousChangeKeys = baseline?.changeKeys;
+    const previousChangeKey = previousChangeKeys?.get(id);
+    if (typeof previousChangeKey === 'string') {
+        return previousChangeKey !== currentChangeKey;
+    }
+    const previousWatermark = previousWatermarks.get(id) || '';
+    return previousWatermark !== currentChangeKey;
+}

package/dist/sync/syncService.d.ts

@@ -56,6 +56,8 @@ export interface WorkspacePushSyncResult {
     changeCount: number;
     deleteCount: number;
     currentTaskIds: Set<string>;
+    currentTaskWatermarks?: Map<string, string>;
+    currentTaskChangeKeys?: Map<string, string>;
     deleteTaskIds: Set<string>;
     currentInitiativeIds: Set<string>;
     currentInitiativeWatermarks: Map<string, string>;
@@ -63,6 +65,7 @@ export interface WorkspacePushSyncResult {
     currentWorkstreamWatermarks: Map<string, string>;
     currentAiProfileIds: Set<string>;
     currentAiProfileWatermarks: Map<string, string>;
+    currentAiProfileChangeKeys?: Map<string, string>;
     currentDocumentPaths: Set<string>;
     deleteDocumentPaths: Set<string>;
     currentDocumentWatermarks: Map<string, string>;
@@ -81,6 +84,7 @@ export interface WorkspacePushSyncResult {
     currentTaskEventWatermarks: Map<string, string>;
     /** Watermarks for every task upsert that was successfully pushed. */
     pushedWatermarks: Map<string, string>;
+    pushedTaskChangeKeys?: Map<string, string>;
     /** Server-emitted realtime mutation event ids for this push apply. */
     emittedEventIds: string[];
     /** Authoritative task snapshots returned immediately by the push route for incoming task upserts. */
@@ -106,6 +110,7 @@ export interface WorkspacePullSyncResult {
     success: boolean;
     kind?: WorkspacePullFailureKind;
     status?: number;
+    errorCode?: string;
     retryAfterMs?: number;
     transient?: boolean;
     failures?: string[];
@@ -121,6 +126,7 @@ export interface WorkspacePullSyncResult {
     pulledActiveUpserts: boolean;
     pulledArchivedUpserts: boolean;
     pulledTaskEventUpserts?: boolean;
+    pulledPlanningUpserts?: boolean;
     documentDecryptFailures?: string[];
     emittedEventIds?: string[];
     serverDiagnostics?: Record<string, unknown> | null;