@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/sync/engine/workspaceSyncEngineTransfers.d.ts

@@ -3,7 +3,7 @@ import type { WorkspaceSyncPayload } from '../workspaceSyncModel.js';
 import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
 import type { WorkspaceSyncV3CombinedCoverageSelector } from '../v3/workspaceSyncV3CombinedWireContract.js';
 import type { WorkspaceSyncEngineRuntime } from './workspaceSyncEngineRuntime.js';
-import type { WorkspaceSyncEngineLocalServices } from './workspaceSyncEngineLocalServices.js';
+import { type WorkspaceSyncEngineLocalServices } from './workspaceSyncEngineLocalServices.js';
 import type { WorkspaceSyncEngineRemoteServices, WorkspaceSyncEngineRemoteTransferReceipt } from './workspaceSyncEngineRemoteServices.js';
 export type { PendingWorkspacePushReplay } from './workspaceSyncEngineTransferTypes.js';
 type StateSetter<T> = (value: T | ((current: T) => T)) => void;

package/dist/sync/engine/workspaceSyncEngineTransfers.js

@@ -4,6 +4,7 @@ import { resolveWorkspacePullRequestPlan, resolveWorkspacePullSuccessPlan } from
 import { runWorkspaceSyncV3InitiativeProjectionCycle } from '../v3/workspaceSyncV3FeedOrchestrator.js';
 import { runWorkspaceSyncV3CombinedProjectionCycle } from '../v3/workspaceSyncV3CombinedFeedOrchestrator.js';
 import { hydrateWorkspaceSyncV3AttachmentAsset } from '../v3/workspaceSyncV3AttachmentAssetHydration.js';
+import { authoritativeV2ApplyFailureMessage, } from './workspaceSyncEngineLocalServices.js';
 import { WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED } from './workspaceSyncEngineRemoteServices.js';
 export function combinedAttachmentAssetHydrationId(input) {
     if (input.causeCode === 'TASK_ATTACHMENT_ASSET_NOT_READY' && input.causeAssetId) {
@@ -391,6 +392,10 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                 }
                 let applyResult;
                 try {
+                    const applyOptions = {
+                        repairMode: replayPayload?.repairMode ?? repairMode,
+                        excludedProjections: pushResult.effectiveV2ExcludedProjections,
+                    };
                     const authoritativeChanges = appliedTaskUpserts.map((entry) => ({
                         op: 'upsert',
                         archived: entry.archived === true,
@@ -398,8 +403,8 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                         ...(entry.durableRevision ? { durableRevision: entry.durableRevision } : {}),
                     }));
                     applyResult = completionGroup
-                        ? await localServices.applyV2Batch(currentWorkspaceId, authoritativeChanges, { completionGroup })
-                        : await localServices.applyV2Batch(currentWorkspaceId, authoritativeChanges);
+                        ? await localServices.applyV2Batch(currentWorkspaceId, authoritativeChanges, { ...applyOptions, completionGroup })
+                        : await localServices.applyV2Batch(currentWorkspaceId, authoritativeChanges, applyOptions);
                 }
                 catch (error) {
                     if (pushTransferReceipts.length > 0) {
@@ -419,7 +424,7 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                             errorCode: 'WORKSPACE_SYNC_V2_PUSH_AUTHORITATIVE_APPLY_FAILED',
                         });
                     }
-                    throw new Error(`Authoritative V2 push echo apply failed (${applyResult.status || 0}).`);
+                    throw new Error(authoritativeV2ApplyFailureMessage(applyResult));
                 }
                 for (const entry of appliedTaskUpserts) {
                     const taskId = String(entry.task.id || '').trim();

package/dist/sync/engine/workspaceSyncV2ChangeDispatcher.js

@@ -279,6 +279,7 @@ export function createWorkspaceSyncV2ChangeDispatcher(dependencies) {
                 workspaceId,
                 incomingInitiatives: applyModel.planning.incomingInitiatives,
                 incomingWorkstreams: applyModel.planning.incomingWorkstreams,
+                incomingIdentities: applyModel.planning.incomingIdentities,
                 recordSyncDiagnostic,
                 ...(options.coexistenceDirection ? {
                     coexistenceDirection: options.coexistenceDirection,
@@ -722,6 +723,7 @@ export function createWorkspaceSyncV2ChangeDispatcher(dependencies) {
                     workspaceId,
                     incomingInitiatives: applyModel.planning.incomingInitiatives,
                     incomingWorkstreams: applyModel.planning.incomingWorkstreams,
+                    incomingIdentities: applyModel.planning.incomingIdentities,
                     recordSyncDiagnostic,
                     ...(options.coexistenceDirection ? {
                         coexistenceDirection: options.coexistenceDirection,

package/dist/sync/syncApplyHandlers.d.ts

@@ -1,6 +1,6 @@
 import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
 import type { DeletedTaskDetails, DeletedTaskSource, TaskRelationshipRecord } from '../core/Taskforce.js';
-import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncAgentConversationSnapshot, WorkspaceSyncAgentRoleSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncChange, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncDurableTaskRevision, WorkspaceSyncDurableTaxonomyRevision, WorkspaceSyncEntityEventSnapshot, WorkspaceSyncInitiativeSnapshot, WorkspaceSyncTaskforceAgentSnapshot, WorkspaceSyncTaskforceAgentSkillSnapshot, WorkspaceSyncTaskSnapshot, WorkspaceSyncWorkspaceMemberSnapshot, WorkspaceSyncWorkstreamSnapshot } from './workspaceSyncModel.js';
+import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncAgentConversationSnapshot, WorkspaceSyncAgentRoleSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncChange, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncDurableTaskRevision, WorkspaceSyncDurableTaxonomyRevision, WorkspaceSyncEntityEventSnapshot, WorkspaceSyncInitiativeSnapshot, WorkspaceSyncPlanningIdentitySnapshot, WorkspaceSyncTaskforceAgentSnapshot, WorkspaceSyncTaskforceAgentSkillSnapshot, WorkspaceSyncTaskSnapshot, WorkspaceSyncWorkspaceMemberSnapshot, WorkspaceSyncWorkstreamSnapshot } from './workspaceSyncModel.js';
 import type { BinaryAssetSyncPayload, DocumentSyncPayload } from './contentSyncPayload.js';
 import type { WorkspaceTaxonomyState } from '../shared/taxonomyState.js';
 import { WorkspaceSyncDurabilityStore } from './v3/syncDurabilityStore.js';
@@ -55,6 +55,7 @@ export interface WorkspaceSyncIncomingApplyModel {
         incomingTaxonomyDurableRevision: WorkspaceSyncDurableTaxonomyRevision | null;
         incomingInitiatives: Map<string, WorkspaceSyncInitiativeSnapshot>;
         incomingWorkstreams: Map<string, WorkspaceSyncWorkstreamSnapshot>;
+        incomingIdentities: Map<string, WorkspaceSyncPlanningIdentitySnapshot>;
     };
     profiles: {
         incomingAiProfiles: Map<string, WorkspaceSyncAiProfileSnapshot>;
@@ -163,6 +164,7 @@ export declare function applyPlanningSyncChanges(input: {
     workspaceId: string;
     incomingInitiatives: Map<string, WorkspaceSyncInitiativeSnapshot>;
     incomingWorkstreams: Map<string, WorkspaceSyncWorkstreamSnapshot>;
+    incomingIdentities?: Map<string, WorkspaceSyncPlanningIdentitySnapshot>;
     recordSyncDiagnostic: RecordSyncDiagnostic;
     coexistenceDirection?: TaskMetadataCoexistenceDirection;
     assertedActiveV3InitiativeIds?: ReadonlySet<string>;

package/dist/sync/syncApplyHandlers.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
+import { assertPlanningIdentityColor, assertPlanningIdentityIcon } from '../shared/planningIdentity.js';
 import { parseAiProfileColorSource } from '../shared/aiProfileColors.js';
 import { normalizeBinaryAssetDeleteSyncPayload, normalizeBinaryAssetSyncPayload, normalizeDocumentDeleteSyncPayload, normalizeDocumentSyncPayload, } from './contentSyncPayload.js';
 import { normalizeAiProfileSyncPayload, normalizeAgentConversationSyncPayload, normalizeAgentRoleSyncPayload, normalizeAnnotatedAttachmentSessionSyncPayload, normalizeDeleteSyncPayload, normalizeDocumentReviewCommentSyncPayload, normalizeDocumentReviewSessionSyncPayload, normalizeTaskforceAgentSkillSyncPayload, normalizeTaskforceAgentSyncPayload, } from './collaborationSyncPayload.js';
@@ -32,6 +33,7 @@ function createIncomingApplyModel() {
             incomingTaxonomyDurableRevision: null,
             incomingInitiatives: new Map(),
             incomingWorkstreams: new Map(),
+            incomingIdentities: new Map(),
         },
         profiles: {
             incomingAiProfiles: new Map(),
@@ -68,6 +70,7 @@ function shouldSkipTaskClassification(op) {
         || op === 'task-relationship-delete'
         || op === 'initiative-upsert'
         || op === 'workstream-upsert'
+        || op === 'planning-identity-upsert'
         || op === 'document-upsert'
         || op === 'document-delete'
         || op === 'asset-upsert'
@@ -185,6 +188,26 @@ export function classifyWorkspaceSyncChanges(input) {
                 model.planning.incomingWorkstreams.set(workstream.id, workstream);
             continue;
         }
+        if (op === 'planning-identity-upsert') {
+            const value = raw.identity;
+            const entityType = value?.entityType === 'initiative' || value?.entityType === 'workstream'
+                ? value.entityType
+                : null;
+            const entityId = String(value?.entityId || '').trim();
+            const updatedAt = String(value?.updatedAt || raw.updatedAt || raw.watermark || '').trim();
+            if (!entityType || !entityId || !Number.isFinite(Date.parse(updatedAt))) {
+                throw new Error('Planning identity sync payload is invalid.');
+            }
+            const identity = {
+                entityType,
+                entityId,
+                icon: assertPlanningIdentityIcon(value?.icon),
+                color: assertPlanningIdentityColor(value?.color),
+                updatedAt,
+            };
+            model.planning.incomingIdentities.set(`${entityType}:${entityId}`, identity);
+            continue;
+        }
         if (op === 'ai-profile-upsert') {
             const profile = normalizeAiProfileSyncPayload(raw.profile, workspaceId, normalizeIncomingAiProfileSurfaceType, normalizeIncomingAiProfileSeatScope, 'apply.aiProfileUpsert');
             const profileId = String(profile?.id || '').trim();
@@ -690,6 +713,12 @@ export function applyPlanningSyncChanges(input) {
             }
         }
     }
+    for (const identity of input.incomingIdentities?.values() || []) {
+        const applied = core.applyPlanningEntityIdentityForSync(identity, workspaceId);
+        if (!applied) {
+            throw new Error(`Planning identity parent is missing: ${identity.entityType}:${identity.entityId}`);
+        }
+    }
 }
 export function applyTaxonomySyncChanges(input) {
     const hasTaxonomy = Boolean(input.incomingTaxonomyState) || Array.isArray(input.incomingTaxonomies);

package/dist/sync/syncService.d.ts

@@ -77,6 +77,8 @@ export interface WorkspacePushSyncResult {
     effectiveDeltaDiagnostics?: WorkspaceSyncDeltaDiagnostics & {
         combinedV3SuppressedChangeCount?: number;
     };
+    /** Exact V3-owned projections excluded while preparing this V2 attempt. */
+    effectiveV2ExcludedProjections?: readonly WorkspaceSyncV2ProjectionExclusion[];
     deleteCount: number;
     currentTaskIds: Set<string>;
     currentTaskWatermarks?: Map<string, string>;

package/dist/sync/syncService.js

@@ -5,7 +5,7 @@ import { createWorkspaceSyncEngineV2PushBoundary, parseWorkspaceSyncEngineApplie
 import { encryptDocument } from './encryptionService.js';
 import { decryptWorkspaceSyncContentChangeInPlace } from './workspaceSyncContentDecryption.js';
 import { decideWorkspaceContentFetch, fingerprintWorkspaceContentBody, } from './workspaceContentManifest.js';
-import { workspaceSyncV2ProjectionExclusionsEqual, } from './v3/workspaceSyncV2ProjectionExclusions.js';
+import { normalizeWorkspaceSyncV2ProjectionExclusions, workspaceSyncV2ProjectionExclusionsEqual, } from './v3/workspaceSyncV2ProjectionExclusions.js';
 import { WORKSPACE_PUSH_PREPARED_PLAN_VERSION, } from './workspacePushPreparedPlan.js';
 import { canonicalWorkspaceSyncJson } from './v3/canonicalWorkspaceSyncJson.js';
 function asObjectRecord(value) {
@@ -217,6 +217,7 @@ function workspacePushChangeStableIdentity(change) {
         case 'task-relationship-delete': return `${change.op}:${change.relationship.id}`;
         case 'initiative-upsert': return `${change.op}:${change.initiative.id}`;
         case 'workstream-upsert': return `${change.op}:${change.workstream.id}`;
+        case 'planning-identity-upsert': return `${change.op}:${change.identity.entityType}:${change.identity.entityId}`;
         case 'taxonomy-upsert': return change.op;
         case 'ai-profile-upsert': return `${change.op}:${change.profile.id}`;
         case 'document-upsert':
@@ -284,6 +285,8 @@ function resolveWorkspacePushPhase(change) {
             return 0;
         case 'workstream-upsert':
             return 1;
+        case 'planning-identity-upsert':
+            return 2;
         case 'upsert':
             return 2;
         case 'document-upsert':
@@ -461,6 +464,7 @@ export async function runWorkspacePushSyncService(input) {
     }
     const changeCount = preparedChanges.length;
     const effectiveDeltaDiagnostics = buildEffectiveWorkspacePushDiagnostics(input.payload.deltaDiagnostics, preparedChanges, preparedOwnership);
+    const effectiveV2ExcludedProjections = normalizeWorkspaceSyncV2ProjectionExclusions(preparedOwnership.combinedExcludedProjections || []);
     const deleteCount = input.payload.deleteTaskIds.size;
     let requestMs = 0;
     const canElideSteadyStateRequest = changeCount === 0
@@ -475,6 +479,7 @@ export async function runWorkspacePushSyncService(input) {
             requestMs: 0,
             changeCount: 0,
             effectiveDeltaDiagnostics,
+            effectiveV2ExcludedProjections,
             deleteCount,
             currentTaskIds: input.payload.currentTaskIds,
             currentTaskWatermarks: input.payload.currentTaskWatermarks ?? new Map(),
@@ -689,6 +694,12 @@ export async function runWorkspacePushSyncService(input) {
                 completedChangeCount += plainBatchChanges.length;
                 continue;
             }
+            if (pushTransferReceipts.length > 0) {
+                await remoteServices.retainTransferReceipts?.({
+                    workspaceId: input.workspaceId,
+                    receipts: pushTransferReceipts,
+                });
+            }
             const sendPush = async () => {
                 const requestStartedAtMs = Date.now();
                 const result = await remoteServices.pushWorkspaceChanges({
@@ -832,6 +843,7 @@ export async function runWorkspacePushSyncService(input) {
             failureDomain: null,
         },
         effectiveDeltaDiagnostics,
+        effectiveV2ExcludedProjections,
         deleteCount,
         currentTaskIds: input.payload.currentTaskIds,
         currentTaskWatermarks: input.payload.currentTaskWatermarks ?? new Map(),

package/dist/sync/taskSyncPayload.d.ts

@@ -25,6 +25,7 @@ export interface TaskSyncPayload {
     referenceNumber?: number | null;
     comments?: Comment[];
     attachments?: Array<string | AttachmentItem>;
+    cardCoverAssetId?: string | null;
     checklistItems?: ChecklistItem[];
 }
 export declare function serializeTaskForSync(task: Partial<TaskItem> | null | undefined): TaskSyncPayload;

package/dist/sync/taskSyncPayload.js

@@ -64,6 +64,7 @@ function cloneChecklistItems(value) {
 }
 export function serializeTaskForSync(task) {
     const source = task && typeof task === 'object' ? task : {};
+    const hasCardCoverAssetId = Object.prototype.hasOwnProperty.call(source, 'cardCoverAssetId');
     return {
         id: String(source.id || '').trim(),
         title: String(source.title || '').trim(),
@@ -89,6 +90,9 @@ export function serializeTaskForSync(task) {
         referenceNumber: toOptionalInteger(source.referenceNumber, { min: 1, nullable: true }),
         comments: cloneComments(source.comments),
         attachments: cloneAttachments(source.attachments),
+        ...(hasCardCoverAssetId
+            ? { cardCoverAssetId: toNullableString(source.cardCoverAssetId) }
+            : {}),
         checklistItems: cloneChecklistItems(source.checklistItems),
     };
 }
@@ -102,6 +106,7 @@ export function normalizeTaskSyncPayload(raw) {
     return serializeTaskForSync(source);
 }
 export function taskSyncPayloadToCoreTask(task) {
+    const hasCardCoverAssetId = Object.prototype.hasOwnProperty.call(task, 'cardCoverAssetId');
     return {
         id: task.id,
         title: task.title,
@@ -127,6 +132,7 @@ export function taskSyncPayloadToCoreTask(task) {
         referenceNumber: task.referenceNumber ?? undefined,
         comments: task.comments,
         attachments: task.attachments,
+        ...(hasCardCoverAssetId ? { cardCoverAssetId: task.cardCoverAssetId } : {}),
         checklistItems: task.checklistItems
     };
 }

package/dist/sync/v3/combinedFeedCapability.js

@@ -3,6 +3,7 @@ import { WORKSPACE_SYNC_V3_COMBINED_CAPABILITY_VERSION, WORKSPACE_SYNC_V3_COMBIN
 import { WORKSPACE_SYNC_V3_NESTED_COVERAGE_SELECTOR } from './workspaceSyncV3NestedWireContract.js';
 import { WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_SELECTOR } from './workspaceSyncV3WorkflowWireContract.js';
 import { WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_SELECTOR } from './workspaceSyncV3PlanningOrderWireContract.js';
+import { WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR } from './workspaceSyncV3TaskCoverWireContract.js';
 export { WORKSPACE_SYNC_V3_COMBINED_CAPABILITY_VERSION } from './workspaceSyncV3CombinedWireContract.js';
 export function resolveRequestedCombinedFeedCoverage(env = process.env) {
     const requestedVersion = String(env.TASKFORCE_SYNC_V3_COMBINED_FEED_COVERAGE_VERSION || '').trim();
@@ -18,6 +19,9 @@ export function resolveRequestedCombinedFeedCoverage(env = process.env) {
     if (requestedVersion === String(WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_SELECTOR.coverageVersion)) {
         return WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_SELECTOR;
     }
+    if (requestedVersion === String(WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR.coverageVersion)) {
+        return WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR;
+    }
     throw new Error(`Unsupported TASKFORCE_SYNC_V3_COMBINED_FEED_COVERAGE_VERSION: ${requestedVersion}.`);
 }
 export function resolveCombinedFeedCapability(input) {

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

@@ -12,6 +12,7 @@ export declare function resolveTaskAttachmentLinksMutationCapability(input: {
 export type DurableTaskAttachmentLinksMutationRouterCore = DurableTaskAttachmentLinksServiceCore & LocalTaskAttachmentLinksOutboxCore & {
     getDatabaseAdapter(): DatabaseAdapter;
     getTask(id: string, workspaceId?: string): TaskItem | null;
+    assertTaskDetailRevisionForUpdate(id: string, expected: string, workspaceId?: string): void;
 };
 export declare class DurableTaskAttachmentLinksRouterDisabledError extends Error {
     readonly code = "WORKSPACE_SYNC_V3_TASK_ATTACHMENT_LINKS_ROUTER_DISABLED";
@@ -40,6 +41,8 @@ export declare function createDurableTaskAttachmentLinksMutationRouter(input: {
     replace(args: {
         taskId: string;
         links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+        cardCoverAssetId?: string | null;
+        expectedDetailRevision?: string;
     }): {
         state: "pending" | "committed";
         route: "local-outbox" | "cloud-acceptance";

package/dist/sync/v3/durableTaskAttachmentLinksMutationRouter.js

@@ -4,6 +4,7 @@ import { enqueueLocalTaskAttachmentLinksMutation, } from './localTaskAttachmentL
 import { DurableTaskAttachmentLinksMutationError, runDurableTaskAttachmentLinksReplace, } from './taskAttachmentLinksMutationService.js';
 import { WorkspaceSyncDurabilityStore, WorkspaceSyncEntityBusyError } from './syncDurabilityStore.js';
 import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { resolveTaskCardCoverAssetIdForLinks } from '../../core/TaskAttachmentLinksDurableMutationService.js';
 const OPERATION_LEASE_MS = 30_000;
 function enabled(value) {
     return /^(1|true|on|yes)$/i.test(String(value || '').trim());
@@ -93,6 +94,22 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
             catch (error) {
                 throw new DurableTaskAttachmentLinksMutationError(error instanceof Error ? error.message : 'Task attachment links are invalid.', 'TASK_ATTACHMENT_LINKS_INVALID', 400);
             }
+            const currentTask = input.core.getTask(taskId, workspaceId);
+            if (!currentTask)
+                throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+            let cardCoverAssetId;
+            try {
+                cardCoverAssetId = resolveTaskCardCoverAssetIdForLinks({
+                    currentCardCoverAssetId: currentTask.cardCoverAssetId,
+                    ...(Object.prototype.hasOwnProperty.call(args, 'cardCoverAssetId')
+                        ? { requestedCardCoverAssetId: args.cardCoverAssetId }
+                        : {}),
+                    links,
+                });
+            }
+            catch (error) {
+                throw new DurableTaskAttachmentLinksMutationError(error instanceof Error ? error.message : 'Task card cover is invalid.', 'TASK_ATTACHMENT_LINKS_INVALID', Number(error?.statusCode) || 400);
+            }
             const acceptedAt = now();
             const acceptedAtIso = acceptedAt.toISOString();
             const operationId = operationIdRequired(input.operationId);
@@ -123,7 +140,14 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
                     catch {
                         throw new DurableTaskAttachmentLinksMutationError('Captured task attachment-link payload is invalid.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
                     }
-                    if (canonicalWorkspaceSyncJson(frozen) !== canonicalWorkspaceSyncJson(links)) {
+                    const relationshipIntent = (entries) => entries.map((link) => ({
+                        assetId: link.assetId,
+                        role: link.role,
+                        order: link.order,
+                    }));
+                    if (canonicalWorkspaceSyncJson(relationshipIntent(frozen))
+                        !== canonicalWorkspaceSyncJson(relationshipIntent(links))
+                        || String(payload.cardCoverAssetId || '') !== String(cardCoverAssetId || '')) {
                         throw new DurableTaskAttachmentLinksMutationError('Operation identity is assigned to different task attachment links.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
                     }
                     const task = input.core.getTask(taskId, workspaceId);
@@ -138,7 +162,7 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
                 let result;
                 try {
                     result = enqueueLocalTaskAttachmentLinksMutation({
-                        store, core: serviceCore, identity, taskId, links, now: acceptedAtIso,
+                        store, core: serviceCore, identity, taskId, links, cardCoverAssetId, now: acceptedAtIso,
                         actorRef, onPostCommitError: input.onPostCommitError,
                         requireV3CombinedOwnership: persistedOwnershipChecked,
                     });
@@ -182,10 +206,14 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
                 });
             }
             const result = runDurableTaskAttachmentLinksReplace({
-                store, core: serviceCore, tenantId, workspaceId, clientId, operationId, taskId, links,
+                store, core: serviceCore, tenantId, workspaceId, clientId, operationId, taskId, links, cardCoverAssetId,
                 baseEntityRevision: coordinates.entityRevision, baseLifecycleRevision: coordinates.lifecycleRevision,
                 now: acceptedAtIso, leaseExpiresAt: new Date(acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
                 actorRef, onPostCommitError: input.onPostCommitError,
+                expectedDetailRevision: args.expectedDetailRevision,
+                assertPrecondition: args.expectedDetailRevision
+                    ? () => input.core.assertTaskDetailRevisionForUpdate(taskId, args.expectedDetailRevision, workspaceId)
+                    : undefined,
             });
             if (result.state === 'in_progress')
                 throw new DurableTaskAttachmentLinksRouterInProgressError(result.retryAt);

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

@@ -11,6 +11,7 @@ export declare function resolveTaskChecklistMutationCapability(input: {
 export type DurableTaskChecklistMutationRouterCore = DurableTaskChecklistServiceCore & LocalTaskChecklistOutboxCore & {
     getDatabaseAdapter(): DatabaseAdapter;
     getTask(id: string, workspaceId?: string): TaskItem | null;
+    assertTaskDetailRevisionForUpdate(id: string, expected: string, workspaceId?: string): void;
 };
 export declare class DurableTaskChecklistRouterDisabledError extends Error {
     readonly code = "WORKSPACE_SYNC_V3_TASK_CHECKLIST_ROUTER_DISABLED";
@@ -38,6 +39,7 @@ export declare function createDurableTaskChecklistMutationRouter(input: {
     replace(args: {
         taskId: string;
         items: readonly Partial<ChecklistItem>[];
+        expectedDetailRevision?: string;
     }): {
         state: "pending" | "committed";
         route: "local-outbox" | "cloud-acceptance";

package/dist/sync/v3/durableTaskChecklistMutationRouter.js

@@ -170,6 +170,10 @@ export function createDurableTaskChecklistMutationRouter(input) {
                 baseEntityRevision: coordinates.entityRevision, baseLifecycleRevision: coordinates.lifecycleRevision,
                 now: acceptedAtIso, leaseExpiresAt: new Date(acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
                 actorRef, onPostCommitError: input.onPostCommitError,
+                expectedDetailRevision: args.expectedDetailRevision,
+                assertPrecondition: args.expectedDetailRevision
+                    ? () => input.core.assertTaskDetailRevisionForUpdate(taskId, args.expectedDetailRevision, workspaceId)
+                    : undefined,
             });
             if (result.state === 'in_progress')
                 throw new DurableTaskChecklistRouterInProgressError(result.retryAt);

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

@@ -51,6 +51,7 @@ export declare function createDurableTaskHttpBulkMutationRouter(input: {
     }>, options?: {
         saveSource?: "manual" | "autosave";
         atomicItemFailures?: boolean;
+        expectedDetailRevision?: string;
     }): {
         preview: import("../../core/Taskforce.js").BulkUpdateFieldsPreview;
         results: TaskItem[];

package/dist/sync/v3/durableTaskHttpBulkMutationRouter.js

@@ -222,7 +222,12 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
             }, { atomicRecovery: true });
         },
         updateFields(updates, options = {}) {
-            return input.rootRouter.runBatch('bulk-update-fields', { updates }, (batch) => {
+            return input.rootRouter.runBatch('bulk-update-fields', {
+                updates,
+                ...(options.expectedDetailRevision
+                    ? { expectedDetailRevision: options.expectedDetailRevision }
+                    : {}),
+            }, (batch) => {
                 const preview = input.core.bulkUpdateFieldsPreview(updates, input.workspaceId);
                 const results = [];
                 const errors = preview.skipped
@@ -245,15 +250,22 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                         if (hasAttachments && !Array.isArray(item.fields.attachments)) {
                             throw new TaskforceRuleError('attachments must be an array.', 400, 'TASK_ATTACHMENT_LINKS_INVALID');
                         }
-                        const attachmentOperationId = hasAttachments
+                        const hasCardCover = Object.prototype.hasOwnProperty.call(item.fields, 'cardCoverAssetId');
+                        if (hasCardCover && item.fields.cardCoverAssetId !== null
+                            && (typeof item.fields.cardCoverAssetId !== 'string' || !item.fields.cardCoverAssetId.trim())) {
+                            throw new TaskforceRuleError('cardCoverAssetId must be a non-empty string or null.', 400, 'TASK_CARD_COVER_INVALID');
+                        }
+                        const attachmentOperationId = hasAttachments || hasCardCover
                             ? input.deriveChildOperationId('bulk-update-fields-attachments', item.index, item.id)
                             : '';
-                        const attachmentLinks = hasAttachments
+                        const attachmentLinks = hasAttachments || hasCardCover
                             ? input.createAttachmentLinksRouter(attachmentOperationId)
                             : null;
                         const durableAttachmentLinks = attachmentLinks?.enabled === true;
                         const normalizedAttachmentLinks = durableAttachmentLinks
-                            ? normalizeAttachmentLinks(item.fields.attachments)
+                            ? normalizeAttachmentLinks(hasAttachments
+                                ? item.fields.attachments
+                                : input.core.getTask(item.id, input.workspaceId)?.attachments || [])
                             : [];
                         const checklistOperationId = hasChecklist
                             ? input.deriveChildOperationId('bulk-update-fields-checklist', item.index, item.id)
@@ -262,17 +274,25 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                         const durableChecklist = checklist?.enabled === true;
                         const rootFields = durableChecklist || durableAttachmentLinks
                             ? Object.fromEntries(Object.entries(item.fields).filter(([key]) => (!(durableChecklist && key === 'checklistItems')
-                                && !(durableAttachmentLinks && key === 'attachments'))))
+                                && !(durableAttachmentLinks && key === 'attachments')
+                                && !(durableAttachmentLinks && key === 'cardCoverAssetId'))))
                             : item.fields;
                         let updated = input.core.getTask(item.id, input.workspaceId);
+                        let expectedDetailRevision = options.expectedDetailRevision;
                         if (Object.keys(rootFields).length > 0) {
                             const child = input.createChildRouter(input.deriveChildOperationId('bulk-update-fields-root', item.index, item.id), () => { });
                             updated = child.enabled
-                                ? batch.runChild(() => child.update(item.id, rootFields, options.saveSource || 'manual'))
-                                : input.core.updateTask(item.id, rootFields, input.workspaceId, {
-                                    actorRef: 'user',
-                                    saveSource: options.saveSource || 'manual',
-                                });
+                                ? batch.runChild(() => child.update(item.id, rootFields, options.saveSource || 'manual', undefined, expectedDetailRevision))
+                                : (() => {
+                                    if (expectedDetailRevision) {
+                                        input.core.assertTaskDetailRevisionForUpdate(item.id, expectedDetailRevision, input.workspaceId);
+                                    }
+                                    return input.core.updateTask(item.id, rootFields, input.workspaceId, {
+                                        actorRef: 'user',
+                                        saveSource: options.saveSource || 'manual',
+                                    });
+                                })();
+                            expectedDetailRevision = undefined;
                         }
                         if (durableChecklist && checklist) {
                             const currentTask = input.core.getTask(item.id, input.workspaceId) || updated;
@@ -293,13 +313,25 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                                     updatedAt: String(unchanged ? existing.updatedAt : existing ? now : source.updatedAt || createdAt),
                                 };
                             });
-                            updated = batch.runChild(() => checklist.replace({ taskId: item.id, items: normalizedChecklist }).task);
+                            updated = batch.runChild(() => checklist.replace({
+                                taskId: item.id,
+                                items: normalizedChecklist,
+                                expectedDetailRevision,
+                            }).task);
+                            expectedDetailRevision = undefined;
                         }
                         if (durableAttachmentLinks && attachmentLinks) {
                             updated = batch.runChild(() => attachmentLinks.replace({
                                 taskId: item.id,
                                 links: normalizedAttachmentLinks,
+                                ...(hasCardCover ? {
+                                    cardCoverAssetId: item.fields.cardCoverAssetId === null
+                                        ? null
+                                        : String(item.fields.cardCoverAssetId).trim(),
+                                } : {}),
+                                expectedDetailRevision,
                             }).task);
+                            expectedDetailRevision = undefined;
                         }
                         if (updated)
                             results.push(updated);
@@ -314,7 +346,10 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                 }
                 batch.deferPostCommitNotification(() => input.core.notifyDurableTaskBatchCommitted(input.workspaceId, results.map((task) => task.id)));
                 return { preview, results, errors };
-            }, { atomicRecovery: true, allowIndependentNestedOwnership: true });
+            }, {
+                atomicRecovery: true,
+                allowIndependentNestedOwnership: true,
+            });
         },
     };
 }

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

@@ -3,7 +3,8 @@ import type { TaskRestoreDestination } from '../../shared/taskRestoreDestination
 export declare class DurableTaskHttpRootMutationError extends Error {
     readonly code: string;
     readonly statusCode: number;
-    constructor(message: string, code: string, statusCode: number);
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, statusCode: number, details?: Record<string, unknown> | undefined);
 }
 export declare function resolveTaskHttpRootMutationCapability(input: {
     runtimeMode: 'local' | 'cloud';
@@ -22,8 +23,9 @@ export declare function createDurableTaskHttpRootMutationRouter(input: {
     deferPostCommitNotification?: (notify: () => void) => void;
 }): {
     enabled: boolean;
+    hasCommittedOperation(): boolean;
     create(candidate: unknown): TaskItem;
-    update(taskIdInput: string, candidate: unknown, saveSource: "manual" | "autosave", activityAction?: "task-updated" | "task-schedule-changed"): TaskItem;
+    update(taskIdInput: string, candidate: unknown, saveSource: "manual" | "autosave", activityAction?: "task-updated" | "task-schedule-changed", expectedDetailRevision?: string): TaskItem;
     runBatch<T>(routeInput: string, request: unknown, apply: (context: {
         runChild<R>(mutation: () => R): R;
         deferPostCommitNotification(notify: () => void): void;
@@ -36,5 +38,5 @@ export declare function createDurableTaskHttpRootMutationRouter(input: {
     restore(deletedRecordIdInput: string, restoreDestination?: TaskRestoreDestination): TaskItem;
     delete(taskIdInput: string): DeletedTaskRecord;
 };
-type TaskforceCoreForHttpRootMutation = Pick<import('../../core/Taskforce.js').TaskforceCore, 'getDatabaseAdapter' | 'getTask' | 'listAssignableActors' | 'getDeletedTask' | 'updateTask' | 'hasTaskDeletionMarkerForSync' | 'createTask' | 'listTaskAttachmentLinksForDurableSync' | 'resolveTaskAttachmentLinksForDurableSync' | 'normalizeTaskAttachmentDescriptorsForDurableSync' | 'notifyDurableTaskCreateCommitted' | 'notifyDurableTaskBatchCommitted' | 'notifyDurableTaskMetadataCommitted' | 'notifyDurableTaskLifecycleCommitted' | 'notifyDurableTaskDeleteCommitted' | 'getTaskEventForSync' | 'getEntityEventForSync' | 'lockTaskLifecycleMutationDomain' | 'archiveTask' | 'unarchiveTask' | 'restoreDeletedTask' | 'addTaskStatusEventsForDurableSync' | 'lockTaskRelationshipMutationDomain' | 'listTaskRelationships' | 'getTaskRelationshipForSync' | 'deleteTaskForSync'>;
+type TaskforceCoreForHttpRootMutation = Pick<import('../../core/Taskforce.js').TaskforceCore, 'getDatabaseAdapter' | 'getTask' | 'getTaskDetailRevision' | 'assertTaskDetailRevisionForUpdate' | 'listAssignableActors' | 'getDeletedTask' | 'updateTask' | 'hasTaskDeletionMarkerForSync' | 'createTask' | 'listTaskAttachmentLinksForDurableSync' | 'resolveTaskAttachmentLinksForDurableSync' | 'normalizeTaskAttachmentDescriptorsForDurableSync' | 'notifyDurableTaskCreateCommitted' | 'notifyDurableTaskBatchCommitted' | 'notifyDurableTaskMetadataCommitted' | 'notifyDurableTaskLifecycleCommitted' | 'notifyDurableTaskDeleteCommitted' | 'getTaskEventForSync' | 'getEntityEventForSync' | 'lockTaskLifecycleMutationDomain' | 'archiveTask' | 'unarchiveTask' | 'restoreDeletedTask' | 'addTaskStatusEventsForDurableSync' | 'lockTaskRelationshipMutationDomain' | 'listTaskRelationships' | 'getTaskRelationshipForSync' | 'deleteTaskForSync'>;
 export {};