@taskforcehq/taskforce 0.3.300 → 0.3.302

package/dist/sync/syncApplyHandlers.js

@@ -0,0 +1,445 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { compareWorkspaceMutationOrdering } from './workspaceSyncSurface.js';
+export function resolveSyncConflictOrdering(incomingWatermark, existingWatermark, incomingTieBreak, existingTieBreak) {
+    return compareWorkspaceMutationOrdering(String(incomingWatermark || '').trim(), String(existingWatermark || '').trim(), String(incomingTieBreak || '').trim(), String(existingTieBreak || '').trim());
+}
+export function applyPlanningSyncChanges(input) {
+    const { core, workspaceId, incomingInitiatives, incomingWorkstreams, incomingTaxonomies, incomingTaxonomyState, incomingTaxonomiesUpdatedAt, workspaceTaxonomySyncMeta, recordSyncDiagnostic, } = input;
+    if (incomingInitiatives.size > 0) {
+        for (const initiative of incomingInitiatives.values()) {
+            try {
+                core.upsertInitiativeForSync({
+                    id: initiative.id,
+                    referenceNumber: initiative.referenceNumber,
+                    referenceLabel: initiative.referenceLabel,
+                    title: initiative.title,
+                    description: initiative.description,
+                    ownerId: initiative.ownerId,
+                    createdAt: initiative.createdAt,
+                    updatedAt: initiative.updatedAt,
+                    order: initiative.order,
+                    isArchived: initiative.isArchived
+                }, workspaceId);
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert initiative during sync apply.', {
+                    source: 'apply.initiativeUpsert',
+                    initiativeId: initiative.id,
+                    error: String(error?.message || error || '')
+                });
+                throw error;
+            }
+        }
+    }
+    if (incomingWorkstreams.size > 0) {
+        for (const workstream of incomingWorkstreams.values()) {
+            try {
+                core.upsertWorkstreamForSync({
+                    id: workstream.id,
+                    referenceNumber: workstream.referenceNumber,
+                    referenceLabel: workstream.referenceLabel,
+                    initiativeId: workstream.initiativeId,
+                    title: workstream.title,
+                    description: workstream.description,
+                    ownerId: workstream.ownerId,
+                    createdAt: workstream.createdAt,
+                    updatedAt: workstream.updatedAt,
+                    order: workstream.order,
+                    isArchived: workstream.isArchived
+                }, workspaceId);
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert workstream during sync apply.', {
+                    source: 'apply.workstreamUpsert',
+                    workstreamId: workstream.id,
+                    error: String(error?.message || error || '')
+                });
+                throw error;
+            }
+        }
+    }
+    if (incomingTaxonomyState || Array.isArray(incomingTaxonomies)) {
+        const nextTaxonomyState = incomingTaxonomyState || { taxonomies: incomingTaxonomies || [] };
+        if (!incomingTaxonomiesUpdatedAt) {
+            if (typeof core.updateTaxonomyState === 'function') {
+                core.updateTaxonomyState(nextTaxonomyState, workspaceId);
+            }
+            else {
+                core.updateTaxonomies(Array.isArray(incomingTaxonomies) ? incomingTaxonomies : []);
+            }
+            const fallbackHash = createHash('sha256').update(JSON.stringify(nextTaxonomyState)).digest('hex');
+            workspaceTaxonomySyncMeta.set(workspaceId, {
+                updatedAt: new Date().toISOString(),
+                hash: fallbackHash
+            });
+        }
+        else {
+            const incomingTaxonomyHash = createHash('sha256').update(JSON.stringify(nextTaxonomyState)).digest('hex');
+            const currentMeta = workspaceTaxonomySyncMeta.get(workspaceId) || { updatedAt: '', hash: '' };
+            const compare = resolveSyncConflictOrdering(incomingTaxonomiesUpdatedAt, currentMeta.updatedAt, incomingTaxonomyHash, currentMeta.hash);
+            if (compare >= 0) {
+                if (typeof core.updateTaxonomyState === 'function') {
+                    core.updateTaxonomyState(nextTaxonomyState, workspaceId);
+                }
+                else {
+                    core.updateTaxonomies(Array.isArray(incomingTaxonomies) ? incomingTaxonomies : []);
+                }
+                workspaceTaxonomySyncMeta.set(workspaceId, {
+                    updatedAt: incomingTaxonomiesUpdatedAt,
+                    hash: incomingTaxonomyHash
+                });
+            }
+        }
+    }
+}
+export function applyAiProfileAndMemberSyncChanges(input) {
+    const { core, workspaceId, incomingAiProfiles, workspaceMembers, recordSyncDiagnostic, assertSyncedAiProfilesPersisted, createSyncRouteError, } = input;
+    if (incomingAiProfiles.size > 0) {
+        for (const profile of incomingAiProfiles.values()) {
+            try {
+                core.upsertAiProfileForSync({
+                    id: profile.id,
+                    workspaceId,
+                    profileToken: profile.profileToken,
+                    name: profile.name,
+                    username: profile.username,
+                    icon: profile.icon,
+                    color: profile.color,
+                    surfaceType: profile.surfaceType,
+                    providerMetadata: profile.providerMetadata,
+                    createdAt: profile.createdAt,
+                    updatedAt: profile.updatedAt,
+                    lastActiveAt: profile.lastActiveAt
+                });
+            }
+            catch (error) {
+                const details = {
+                    source: 'apply.aiProfileUpsert',
+                    workspaceId,
+                    profileId: profile.id,
+                    error: String(error?.message || error || ''),
+                    errorCode: String(error?.code || '').trim() || null
+                };
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert AI profile during sync apply.', details);
+                throw createSyncRouteError(`Failed to persist AI profile ${profile.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'AI_PROFILE_SYNC_APPLY_FAILED', statusCode: 500 });
+            }
+        }
+        assertSyncedAiProfilesPersisted(workspaceId, incomingAiProfiles);
+    }
+    if (Array.isArray(workspaceMembers)) {
+        core.replaceWorkspaceUsersForSync({
+            workspaceId,
+            users: workspaceMembers
+                .filter((member) => String(member?.workspaceId || workspaceId).trim() === workspaceId)
+                .map((member) => ({
+                userId: member.userId,
+                email: member.email,
+                displayName: member.displayName,
+                role: member.role,
+                permissionMode: member.permissionMode,
+                betaAccess: member.betaAccess,
+                status: member.status,
+                disabled: member.disabled,
+                createdAt: member.createdAt,
+                updatedAt: member.updatedAt,
+                emailVerifiedAt: member.emailVerifiedAt
+            }))
+        });
+    }
+}
+export async function applyContentSyncChanges(input) {
+    const { core, workspaceId, incomingDocuments, incomingDocumentDeletes, incomingAssets, incomingAssetDeletes, basePath, hasObjectStorageClient, hasDocumentSyncMetadataDrift, hasBinaryAssetSyncMetadataDrift, writeWorkspaceSyncDocument, deleteWorkspaceSyncDocument, writeWorkspaceSyncBinaryAsset, deleteWorkspaceSyncBinaryAsset, getExistingBinaryAsset, recordSyncDiagnostic, options, } = input;
+    if (incomingDocuments.length > 0) {
+        for (const doc of incomingDocuments) {
+            try {
+                const existingDoc = core.getDocumentWatermark(workspaceId, doc.path);
+                const incomingHash = createHash('sha256').update(String(doc.content || '')).digest('hex');
+                const existingUpdatedAt = String(existingDoc?.updatedAt || '').trim();
+                const existingHash = String(existingDoc?.contentHash || '').trim();
+                const compare = resolveSyncConflictOrdering(doc.updatedAt, existingUpdatedAt, incomingHash, existingHash);
+                const metadataDrift = hasDocumentSyncMetadataDrift(workspaceId, doc, options);
+                if (compare < 0)
+                    continue;
+                if (compare === 0 && existingHash === incomingHash && !metadataDrift)
+                    continue;
+                await writeWorkspaceSyncDocument(basePath, doc, workspaceId, options);
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to apply synced document change.', {
+                    source: 'documents.apply.write',
+                    path: doc.path,
+                    assetId: typeof doc.assetId === 'string' ? doc.assetId : null,
+                    error: String(error?.message || error || '')
+                });
+            }
+        }
+    }
+    if (incomingDocumentDeletes.size > 0) {
+        for (const [docPath, deletedAt] of incomingDocumentDeletes.entries()) {
+            const existingDoc = core.getDocumentWatermark(workspaceId, docPath);
+            const existingUpdatedAt = String(existingDoc?.updatedAt || '').trim();
+            const existingHash = String(existingDoc?.contentHash || '').trim();
+            const compare = resolveSyncConflictOrdering(deletedAt, existingUpdatedAt, `delete:${docPath}`, existingHash);
+            if (existingDoc && compare < 0)
+                continue;
+            deleteWorkspaceSyncDocument(basePath, docPath, workspaceId);
+        }
+    }
+    if (incomingAssets.length > 0) {
+        for (const asset of incomingAssets) {
+            try {
+                const existing = getExistingBinaryAsset(asset.path, workspaceId);
+                const incomingHash = createHash('sha256').update(Buffer.from(String(asset.contentBase64 || ''), 'base64')).digest('hex');
+                const existingUpdatedAt = String(existing?.updatedAt || '').trim();
+                const existingHash = String(existing?.contentSha256 || '').trim();
+                const localFileMissing = !hasObjectStorageClient() && !fs.existsSync(path.resolve(basePath, asset.path));
+                const compare = resolveSyncConflictOrdering(asset.updatedAt, existingUpdatedAt, incomingHash, existingHash);
+                const metadataDrift = hasBinaryAssetSyncMetadataDrift(workspaceId, asset, options);
+                if (compare < 0)
+                    continue;
+                if (compare === 0 && existingHash === incomingHash && !localFileMissing && !metadataDrift)
+                    continue;
+                await writeWorkspaceSyncBinaryAsset(basePath, asset, workspaceId, options);
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to apply synced asset change.', {
+                    source: 'assets.apply.write',
+                    path: asset.path,
+                    assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
+                    kind: asset.kind,
+                    error: String(error?.message || error || '')
+                });
+            }
+        }
+    }
+    if (incomingAssetDeletes.size > 0) {
+        for (const [assetPath, deletedAt] of incomingAssetDeletes.entries()) {
+            const existing = getExistingBinaryAsset(assetPath, workspaceId);
+            const existingUpdatedAt = String(existing?.updatedAt || '').trim();
+            const existingHash = String(existing?.contentSha256 || '').trim();
+            const compare = resolveSyncConflictOrdering(deletedAt, existingUpdatedAt, `delete:${assetPath}`, existingHash);
+            if (existing && compare < 0)
+                continue;
+            deleteWorkspaceSyncBinaryAsset(basePath, assetPath, workspaceId);
+        }
+    }
+    if (incomingDocuments.length > 0 || incomingAssets.length > 0) {
+        core.notifyDocumentMetadataMutation(workspaceId, [
+            ...incomingDocuments.map((entry) => entry.path),
+            ...incomingAssets.map((entry) => entry.path)
+        ], 'upsert');
+    }
+    if (incomingDocumentDeletes.size > 0 || incomingAssetDeletes.size > 0) {
+        core.notifyDocumentMetadataMutation(workspaceId, [
+            ...Array.from(incomingDocumentDeletes.keys()),
+            ...Array.from(incomingAssetDeletes.keys())
+        ], 'delete');
+    }
+}
+export function applyCollaborationSyncChanges(input) {
+    const { core, workspaceId, incomingDocumentReviewSessions, incomingDocumentReviewSessionDeletes, incomingDocumentReviewComments, incomingDocumentReviewCommentDeletes, incomingAnnotatedAttachmentSessions, incomingAnnotatedAttachmentSessionDeletes, recordSyncDiagnostic, createSyncRouteError, } = input;
+    if (incomingDocumentReviewSessions.size > 0) {
+        for (const session of incomingDocumentReviewSessions.values()) {
+            try {
+                const existing = core.getDocumentReviewSession({
+                    workspaceId,
+                    sessionId: session.id,
+                    includeDeleted: true
+                });
+                const incomingTieBreak = createHash('sha256').update(JSON.stringify(session.comments || [])).digest('hex');
+                const existingTieBreak = existing
+                    ? createHash('sha256').update(JSON.stringify(existing.comments || [])).digest('hex')
+                    : '';
+                const compare = resolveSyncConflictOrdering(session.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                if (compare < 0)
+                    continue;
+                core.upsertDocumentReviewSessionForSync({
+                    id: session.id,
+                    tenantId: core.getTenantId(),
+                    workspaceId,
+                    assetId: session.assetId,
+                    documentId: session.documentId,
+                    documentVersion: session.documentVersion,
+                    title: session.title,
+                    status: session.status,
+                    comments: [],
+                    createdByActorId: session.createdByActorId,
+                    updatedByActorId: session.updatedByActorId,
+                    createdAt: session.createdAt,
+                    updatedAt: session.updatedAt,
+                    deletedAt: session.deletedAt,
+                });
+            }
+            catch (error) {
+                const details = {
+                    source: 'apply.documentReviewUpsert',
+                    sessionId: session.id,
+                    error: String(error?.message || error || ''),
+                    errorCode: String(error?.code || '').trim() || null
+                };
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert document review session during sync apply.', details);
+                throw createSyncRouteError(`Failed to persist document review session ${session.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'DOCUMENT_REVIEW_SESSION_SYNC_APPLY_FAILED', statusCode: 500 });
+            }
+        }
+    }
+    if (incomingDocumentReviewComments.size > 0) {
+        for (const comment of incomingDocumentReviewComments.values()) {
+            try {
+                const existingComments = core.listDocumentReviewCommentsForSync({
+                    workspaceId,
+                    includeDeleted: true
+                });
+                const existing = existingComments.find((entry) => entry.id === comment.id) || null;
+                const incomingTieBreak = createHash('sha256')
+                    .update(JSON.stringify({ body: comment.body, anchor: comment.anchor, deletedAt: comment.deletedAt }))
+                    .digest('hex');
+                const existingTieBreak = existing
+                    ? createHash('sha256')
+                        .update(JSON.stringify({ body: existing.body, anchor: existing.anchor, deletedAt: existing.deletedAt }))
+                        .digest('hex')
+                    : '';
+                const compare = resolveSyncConflictOrdering(comment.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                if (compare < 0)
+                    continue;
+                core.upsertDocumentReviewCommentForSync({
+                    id: comment.id,
+                    tenantId: core.getTenantId(),
+                    workspaceId,
+                    sessionId: comment.sessionId,
+                    body: comment.body,
+                    anchor: comment.anchor,
+                    order: comment.order,
+                    authorActorId: comment.authorActorId,
+                    createdAt: comment.createdAt,
+                    updatedAt: comment.updatedAt,
+                    deletedAt: comment.deletedAt,
+                });
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert document review comment during sync apply.', {
+                    source: 'apply.documentReviewCommentUpsert',
+                    commentId: comment.id,
+                    error: String(error?.message || error || '')
+                });
+                throw error;
+            }
+        }
+    }
+    if (incomingDocumentReviewSessionDeletes.size > 0) {
+        for (const [sessionId, deletedAt] of incomingDocumentReviewSessionDeletes.entries()) {
+            try {
+                const existing = core.getDocumentReviewSession({
+                    workspaceId,
+                    sessionId,
+                    includeDeleted: true
+                });
+                const compare = resolveSyncConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${sessionId}`, String(existing?.id || '').trim());
+                if (existing && compare < 0)
+                    continue;
+                core.deleteDocumentReviewSessionForSync({ workspaceId, sessionId, deletedAt });
+            }
+            catch (error) {
+                const details = {
+                    source: 'apply.documentReviewDelete',
+                    sessionId,
+                    error: String(error?.message || error || ''),
+                    errorCode: String(error?.code || '').trim() || null
+                };
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document review session during sync apply.', details);
+                throw createSyncRouteError(`Failed to delete document review session ${sessionId} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'DOCUMENT_REVIEW_SESSION_SYNC_DELETE_FAILED', statusCode: 500 });
+            }
+        }
+    }
+    if (incomingDocumentReviewCommentDeletes.size > 0) {
+        for (const [commentId, deletedAt] of incomingDocumentReviewCommentDeletes.entries()) {
+            try {
+                const existing = core.listDocumentReviewCommentsForSync({
+                    workspaceId,
+                    includeDeleted: true
+                }).find((entry) => entry.id === commentId) || null;
+                const compare = resolveSyncConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${commentId}`, String(existing?.id || '').trim());
+                if (existing && compare < 0)
+                    continue;
+                core.deleteDocumentReviewCommentForSync({ workspaceId, commentId, deletedAt });
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document review comment during sync apply.', {
+                    source: 'apply.documentReviewCommentDelete',
+                    commentId,
+                    error: String(error?.message || error || '')
+                });
+                throw error;
+            }
+        }
+    }
+    if (incomingAnnotatedAttachmentSessions.size > 0) {
+        for (const session of incomingAnnotatedAttachmentSessions.values()) {
+            try {
+                const existing = core.getAnnotatedAttachmentSession({
+                    workspaceId,
+                    sessionId: session.id,
+                    includeDeleted: true
+                });
+                const incomingTieBreak = createHash('sha256').update(JSON.stringify(session.annotations || [])).digest('hex');
+                const existingTieBreak = existing
+                    ? createHash('sha256').update(JSON.stringify(existing.annotations || [])).digest('hex')
+                    : '';
+                const compare = resolveSyncConflictOrdering(session.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                if (compare < 0)
+                    continue;
+                core.upsertAnnotatedAttachmentSessionForSync({
+                    id: session.id,
+                    tenantId: core.getTenantId(),
+                    workspaceId,
+                    taskId: session.taskId,
+                    baseImageAssetId: session.baseImageAssetId,
+                    title: session.title,
+                    globalInstruction: session.globalInstruction,
+                    annotations: session.annotations,
+                    createdByActorId: session.createdByActorId,
+                    updatedByActorId: session.updatedByActorId,
+                    createdAt: session.createdAt,
+                    updatedAt: session.updatedAt,
+                    deletedAt: session.deletedAt,
+                });
+            }
+            catch (error) {
+                const details = {
+                    source: 'apply.annotatedAttachmentUpsert',
+                    sessionId: session.id,
+                    error: String(error?.message || error || ''),
+                    errorCode: String(error?.code || '').trim() || null
+                };
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert annotated attachment session during sync apply.', details);
+                throw createSyncRouteError(`Failed to persist annotated attachment session ${session.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'ANNOTATED_ATTACHMENT_SESSION_SYNC_APPLY_FAILED', statusCode: 500 });
+            }
+        }
+    }
+    if (incomingAnnotatedAttachmentSessionDeletes.size > 0) {
+        for (const [sessionId, deletedAt] of incomingAnnotatedAttachmentSessionDeletes.entries()) {
+            try {
+                const existing = core.getAnnotatedAttachmentSession({
+                    workspaceId,
+                    sessionId,
+                    includeDeleted: true
+                });
+                const compare = resolveSyncConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${sessionId}`, String(existing?.id || '').trim());
+                if (existing && compare < 0)
+                    continue;
+                core.deleteAnnotatedAttachmentSessionForSync({ workspaceId, sessionId, deletedAt });
+            }
+            catch (error) {
+                const details = {
+                    source: 'apply.annotatedAttachmentDelete',
+                    sessionId,
+                    error: String(error?.message || error || ''),
+                    errorCode: String(error?.code || '').trim() || null
+                };
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete annotated attachment session during sync apply.', details);
+                throw createSyncRouteError(`Failed to delete annotated attachment session ${sessionId} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'ANNOTATED_ATTACHMENT_SESSION_SYNC_DELETE_FAILED', statusCode: 500 });
+            }
+        }
+    }
+}

package/dist/sync/taskSyncPayload.d.ts

@@ -0,0 +1,33 @@
+import type { AttachmentItem, ChecklistItem, Comment, TaskItem, TaskStatus } from '../types.js';
+import type { TaskItem as CoreTaskItem } from '../core/Taskforce.js';
+export interface TaskSyncPayload {
+    id: string;
+    title: string;
+    description?: string | null;
+    status: TaskStatus;
+    priority?: number;
+    complexity?: number | null;
+    type: string;
+    category: string;
+    approach?: string;
+    canceledReason?: string | null;
+    createdAt: string;
+    updatedAt?: string;
+    completedAt?: string | null;
+    isArchived?: boolean;
+    taxonomies?: Record<string, string | string[]>;
+    createdBy?: string;
+    assignee?: string;
+    scheduledDate?: string | null;
+    dueDate?: string | null;
+    scheduledWeekKey?: string | null;
+    orderInDay?: number | null;
+    workstreamId?: string | null;
+    referenceNumber?: number | null;
+    comments?: Comment[];
+    attachments?: Array<string | AttachmentItem>;
+    checklistItems?: ChecklistItem[];
+}
+export declare function serializeTaskForSync(task: Partial<TaskItem> | null | undefined): TaskSyncPayload;
+export declare function normalizeTaskSyncPayload(raw: unknown): TaskSyncPayload | null;
+export declare function taskSyncPayloadToCoreTask(task: TaskSyncPayload): Partial<CoreTaskItem>;

package/dist/sync/taskSyncPayload.js

@@ -0,0 +1,126 @@
+function toOptionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function toNullableString(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function toOptionalBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function toOptionalInteger(value, options) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || value === '')
+        return options?.nullable ? null : undefined;
+    const normalized = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(normalized))
+        return options?.nullable ? null : undefined;
+    const rounded = Math.floor(normalized);
+    if (Number.isFinite(options?.min) && rounded < Number(options?.min)) {
+        return options?.nullable ? null : undefined;
+    }
+    return rounded;
+}
+function cloneTaxonomies(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value);
+    const normalized = entries.reduce((acc, [key, raw]) => {
+        if (Array.isArray(raw)) {
+            acc[key] = raw.map((entry) => String(entry ?? ''));
+            return acc;
+        }
+        if (raw === undefined || raw === null)
+            return acc;
+        acc[key] = String(raw);
+        return acc;
+    }, {});
+    return Object.keys(normalized).length > 0 ? normalized : {};
+}
+function cloneComments(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+function cloneAttachments(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+function cloneChecklistItems(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+export function serializeTaskForSync(task) {
+    const source = task && typeof task === 'object' ? task : {};
+    return {
+        id: String(source.id || '').trim(),
+        title: String(source.title || '').trim(),
+        description: source.description === undefined ? undefined : (source.description || null),
+        status: (String(source.status || 'task').trim() || 'task'),
+        priority: toOptionalInteger(source.priority, { min: 1 }) ?? undefined,
+        complexity: toOptionalInteger(source.complexity, { min: 1, nullable: true }),
+        type: String(source.type || '').trim(),
+        category: String(source.category || '').trim(),
+        approach: toOptionalString(source.approach),
+        canceledReason: source.canceledReason === undefined ? undefined : (source.canceledReason || null),
+        createdAt: String(source.createdAt || '').trim(),
+        updatedAt: toOptionalString(source.updatedAt),
+        completedAt: source.completedAt === undefined ? undefined : (source.completedAt || null),
+        isArchived: toOptionalBoolean(source.isArchived),
+        taxonomies: cloneTaxonomies(source.taxonomies),
+        createdBy: toOptionalString(source.createdBy),
+        assignee: toOptionalString(source.assignee),
+        scheduledDate: toNullableString(source.scheduledDate),
+        dueDate: toNullableString(source.dueDate),
+        scheduledWeekKey: toNullableString(source.scheduledWeekKey),
+        orderInDay: toOptionalInteger(source.orderInDay, { min: 0, nullable: true }),
+        workstreamId: toNullableString(source.workstreamId),
+        referenceNumber: toOptionalInteger(source.referenceNumber, { min: 1, nullable: true }),
+        comments: cloneComments(source.comments),
+        attachments: cloneAttachments(source.attachments),
+        checklistItems: cloneChecklistItems(source.checklistItems),
+    };
+}
+export function normalizeTaskSyncPayload(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const source = raw;
+    const id = String(source.id || '').trim();
+    if (!id)
+        return null;
+    return serializeTaskForSync(source);
+}
+export function taskSyncPayloadToCoreTask(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        description: task.description,
+        status: task.status,
+        priority: task.priority,
+        complexity: task.complexity ?? undefined,
+        type: task.type,
+        category: task.category,
+        approach: task.approach,
+        canceledReason: task.canceledReason ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+        completedAt: task.completedAt,
+        isArchived: task.isArchived,
+        taxonomies: task.taxonomies,
+        createdBy: task.createdBy,
+        assignee: task.assignee,
+        scheduledDate: task.scheduledDate,
+        dueDate: task.dueDate,
+        scheduledWeekKey: task.scheduledWeekKey,
+        orderInDay: task.orderInDay ?? undefined,
+        workstreamId: task.workstreamId,
+        referenceNumber: task.referenceNumber ?? undefined,
+        comments: task.comments,
+        attachments: task.attachments,
+        checklistItems: task.checklistItems
+    };
+}

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

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

package/dist/sync/taskSyncPayload.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeTaskSyncPayload, serializeTaskForSync, taskSyncPayloadToCoreTask, } from './taskSyncPayload';
+describe('taskSyncPayload', () => {
+    it('omits local-only task reference fields from serialized sync payloads', () => {
+        const payload = serializeTaskForSync({
+            id: 'task-1',
+            title: 'Serialized task',
+            status: 'task',
+            priority: 2,
+            category: 'general',
+            type: 'task',
+            referenceNumber: 7,
+            localReferenceNumber: 3,
+            referenceLabel: 'LT-3',
+        });
+        expect(payload).toEqual(expect.objectContaining({
+            id: 'task-1',
+            referenceNumber: 7,
+        }));
+        expect(payload).not.toHaveProperty('localReferenceNumber');
+        expect(payload).not.toHaveProperty('referenceLabel');
+    });
+    it('normalizes task sync payload numbers before converting back to core input', () => {
+        const payload = normalizeTaskSyncPayload({
+            id: 'task-2',
+            title: 'Incoming task',
+            status: 'review',
+            priority: '3',
+            complexity: '4',
+            category: 'general',
+            type: 'task',
+            referenceNumber: '9',
+            orderInDay: '2',
+            localReferenceNumber: 99,
+            referenceLabel: 'LT-99',
+        });
+        expect(payload).toEqual(expect.objectContaining({
+            id: 'task-2',
+            priority: 3,
+            complexity: 4,
+            referenceNumber: 9,
+            orderInDay: 2,
+        }));
+        expect(payload).not.toHaveProperty('localReferenceNumber');
+        expect(payload).not.toHaveProperty('referenceLabel');
+        expect(taskSyncPayloadToCoreTask(payload)).toEqual(expect.objectContaining({
+            id: 'task-2',
+            priority: 3,
+            complexity: 4,
+            referenceNumber: 9,
+            orderInDay: 2,
+        }));
+    });
+});