@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/sync/v3/durableWorkstreamTaskOrderMutationRouter.js

@@ -5,6 +5,7 @@ import { enqueueLocalWorkstreamTaskOrderReplacement } from './localWorkstreamTas
 import { DurableWorkstreamTaskOrderError, runDurableWorkstreamTaskOrderReplace, } from './workstreamTaskOrderMutationService.js';
 import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
 import { serializeWorkstreamTaskOrderForSync } from './workstreamTaskOrderSync.js';
+import { readDurableOperationReplay } from './durableOperationReplay.js';
 const OPERATION_LEASE_MS = 30_000;
 function enabled(value) {
     return /^(1|true|on|yes)$/i.test(String(value || '').trim());
@@ -68,6 +69,9 @@ export function createDurableWorkstreamTaskOrderMutationRouter(input) {
                         || canonicalWorkspaceSyncJson(prior.taskIds || []) !== canonicalWorkspaceSyncJson(payload.taskIds)) {
                         throw new DurableWorkstreamTaskOrderError('Operation identity is assigned to a different workstream task order.', 'WORKSTREAM_TASK_ORDER_IDENTITY_CONFLICT', 409);
                     }
+                    store.assertOutboxOperationIdentity(existing, {
+                        domain: 'workstream-task-order', entityId: payload.workstreamId, mutationKind: 'replace',
+                    });
                     return { state: 'pending', route: 'local-outbox', operationId,
                         taskIds: input.core.getWorkstreamTaskOrderForSync(payload.workstreamId, input.workspaceId) };
                 }
@@ -85,14 +89,21 @@ export function createDurableWorkstreamTaskOrderMutationRouter(input) {
             }
             const committed = store.readCommittedOperationResponse(identity);
             if (committed) {
-                const response = JSON.parse(committed);
-                if (response.authoritative?.entityId !== payload.workstreamId
-                    || canonicalWorkspaceSyncJson(response.authoritative.payload.taskIds)
-                        !== canonicalWorkspaceSyncJson(payload.taskIds)) {
+                const replay = readDurableOperationReplay({
+                    responseJson: committed,
+                    operationId,
+                    domain: 'workstream-task-order',
+                    entityId: payload.workstreamId,
+                    mutationKind: 'replace',
+                    revisionMode: 'metadata',
+                    requirePayload: true,
+                });
+                if (canonicalWorkspaceSyncJson(replay.authoritative.payload?.taskIds)
+                    !== canonicalWorkspaceSyncJson(payload.taskIds)) {
                     throw new DurableWorkstreamTaskOrderError('Operation identity is assigned to a different workstream task order.', 'WORKSTREAM_TASK_ORDER_IDENTITY_CONFLICT', 409);
                 }
                 return { state: 'committed', route: 'cloud-acceptance', operationId,
-                    taskIds: response.authoritative.payload.taskIds };
+                    taskIds: replay.authoritative.payload.taskIds };
             }
             const coordinates = store.readEntityRevisionCoordinates({
                 tenantId: input.tenantId,

package/dist/sync/v3/localOutboxDispatchRuntime.js

@@ -20,7 +20,7 @@ import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js
 import { createLocalWorkflowRuntimeOutboxHandler } from './localWorkflowRuntimeOutboxHandler.js';
 import { createLocalWorkstreamOutboxHandler } from './localWorkstreamOutboxHandler.js';
 import { createLocalWorkstreamTaskOrderOutboxHandler } from './localWorkstreamTaskOrderOutboxHandler.js';
-import { resolveWorkflowRuntimeMutationCapability } from './durableWorkflowRuntimeMutationRouter.js';
+import { resolveWorkflowRuntimeDurableTransportCapability } from './durableWorkflowRuntimeMutationRouter.js';
 import { createLocalEntityEventLegacyAdoptionHandler, enqueueNextLegacyEntityEventAdoption, } from './localEntityEventLegacyAdoption.js';
 export function createLocalOutboxDispatchHandlers(input) {
     return [
@@ -40,7 +40,7 @@ export function createLocalOutboxDispatchHandlers(input) {
         createLocalInitiativeOutboxHandler(input),
         createLocalWorkstreamOutboxHandler(input),
         createLocalWorkstreamTaskOrderOutboxHandler(input),
-        ...(resolveWorkflowRuntimeMutationCapability({
+        ...(resolveWorkflowRuntimeDurableTransportCapability({
             runtimeMode: 'local',
             surface: 'http',
             env: input.env || process.env,

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

@@ -1,8 +1,10 @@
 import type { TaskEvent, TaskItem } from '../../core/Taskforce.js';
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
 import type { DurableTaskAttachmentLinksServiceCore } from './taskAttachmentLinksMutationService.js';
 import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity } from './syncDurabilityStore.js';
 import { type WorkspaceSyncV3TaskAttachmentLink } from './workspaceSyncV3NestedTaskCodecs.js';
 export interface LocalTaskAttachmentLinksOutboxCore extends DurableTaskAttachmentLinksServiceCore {
+    getDatabaseAdapter(): DatabaseAdapter;
     getWorkspaceAssetDispatchReadiness(assetId: string, workspaceId: string): {
         ready: boolean;
         retryable: boolean;

package/dist/sync/v3/localTaskAttachmentLinksOutboxService.js

@@ -5,7 +5,9 @@ import { buildTaskAttachmentLinksActivityEventId } from './taskAttachmentLinksAc
 import { canonicalizeEntityActivityDetailsForSync, serializeTaskActivityForSync, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
 import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { resolveWorkspaceSyncV3RegisteredCoverage } from './workspaceSyncV3CoverageRegistry.js';
+import { WorkspaceSyncV3CombinedProjectionStateStore } from './workspaceSyncV3CombinedProjectionState.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskAttachmentLinksV2Payload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { withOriginActorPayload } from './workspaceSyncV3OriginActor.js';
 export class LocalAuthoritativeTaskAttachmentLinksError extends Error {
     code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
@@ -90,6 +92,24 @@ function requireRevision(value, label) {
         throw new LocalAuthoritativeTaskAttachmentLinksError(`${label} is invalid.`);
     return text;
 }
+function resolveOwnedAttachmentProjection(input) {
+    const state = new WorkspaceSyncV3CombinedProjectionStateStore(input.core.getDatabaseAdapter()).read({
+        tenantId: input.identity.tenantId,
+        workspaceId: input.identity.workspaceId,
+    });
+    if (state.owner !== 'v3')
+        return null;
+    const coverage = resolveWorkspaceSyncV3RegisteredCoverage(state)?.profile;
+    if (!coverage)
+        throw new LocalAuthoritativeTaskAttachmentLinksError('Owned task attachment-link coverage is not registered.');
+    if (coverage.projections.some(({ projectionId }) => projectionId === 'task-attachment-links/full-v2')) {
+        return 'task-attachment-links/full-v2';
+    }
+    if (coverage.projections.some(({ projectionId }) => projectionId === 'task-attachment-links/full-v1')) {
+        return 'task-attachment-links/full-v1';
+    }
+    return null;
+}
 export function enqueueLocalTaskAttachmentLinksMutation(input) {
     const requestedLinks = canonicalLinks(input.taskId, input.links);
     let attachments;
@@ -206,9 +226,20 @@ export function applyAuthoritativeTaskAttachmentLinksAndAck(input) {
         throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task attachment-link operation ordering is invalid.');
     }
     const rootPayload = serializeTaskRootForSync(root.payload);
-    const attachmentLinksPayload = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-        taskId: attachmentLinks.entityId, links: attachmentLinks.payload.links,
-    });
+    const rawAttachmentPayload = attachmentLinks.payload;
+    const hasAuthoritativeCardCover = Object.prototype.hasOwnProperty.call(rawAttachmentPayload, 'cardCoverAssetId');
+    const validatedAttachmentLinksPayload = hasAuthoritativeCardCover
+        ? validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(rawAttachmentPayload)
+        : validateWorkspaceSyncV3TaskAttachmentLinksPayload(rawAttachmentPayload);
+    const ownedAttachmentProjection = resolveOwnedAttachmentProjection(input);
+    const attachmentLinksPayload = ownedAttachmentProjection === 'task-attachment-links/full-v1'
+        ? serializeWorkspaceSyncV3TaskAttachmentLinksPayload(validatedAttachmentLinksPayload)
+        : validatedAttachmentLinksPayload;
+    const authoritativeCardCoverAssetId = hasAuthoritativeCardCover
+        && ownedAttachmentProjection !== 'task-attachment-links/full-v1'
+        ? validatedAttachmentLinksPayload
+            .cardCoverAssetId
+        : undefined;
     const activityPayload = serializeTaskActivityForSync(activity);
     const expectedActivityId = buildTaskAttachmentLinksActivityEventId({
         workspaceId: input.identity.workspaceId, clientId: input.identity.clientId,
@@ -268,6 +299,9 @@ export function applyAuthoritativeTaskAttachmentLinksAndAck(input) {
                 completedAt: rootPayload.completedAt,
                 canceledReason: rootPayload.canceledReason,
                 attachments,
+                ...(authoritativeCardCoverAssetId !== undefined
+                    ? { cardCoverAssetId: authoritativeCardCoverAssetId }
+                    : {}),
             };
             const updated = input.core.updateTask(root.entityId, rootPatch, input.identity.workspaceId, {
                 persistBackup: false, emitRealtime: false, skipTaskEvents: true,
@@ -282,9 +316,15 @@ export function applyAuthoritativeTaskAttachmentLinksAndAck(input) {
             input.core.upsertEntityEventForSync(activity, { allowAuthoritativeReplacement: true });
             const installedLinks = input.core.listTaskAttachmentLinksForDurableSync(updated.id, input.identity.workspaceId);
             if (canonicalWorkspaceSyncJson(serializeTaskRootForSync(updated)) !== canonicalWorkspaceSyncJson(rootPayload)
-                || canonicalWorkspaceSyncJson(serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-                    taskId: updated.id, links: installedLinks,
-                })) !== canonicalWorkspaceSyncJson(attachmentLinksPayload)) {
+                || canonicalWorkspaceSyncJson(authoritativeCardCoverAssetId !== undefined
+                    ? serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+                        taskId: updated.id,
+                        links: installedLinks,
+                        cardCoverAssetId: updated.cardCoverAssetId ?? null,
+                    })
+                    : serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                        taskId: updated.id, links: installedLinks,
+                    })) !== canonicalWorkspaceSyncJson(attachmentLinksPayload)) {
                 throw new LocalAuthoritativeTaskAttachmentLinksError('Installed task attachment-link state does not match authority.');
             }
             return updated;

package/dist/sync/v3/localTaskChecklistOutboxHandler.js

@@ -2,6 +2,7 @@ import { EntityEventIdentityCollisionError } from '../../core/TaskActivityServic
 import { applyAuthoritativeTaskChecklistAndAck, LocalAuthoritativeTaskChecklistError, } from './localTaskChecklistOutboxService.js';
 import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
 import { validateWorkspaceSyncV3TaskChecklistPayload } from './workspaceSyncV3NestedTaskCodecs.js';
+import { validateTaskChecklistItemUpdateIntent } from './taskChecklistMutationService.js';
 import { parseWorkspaceSyncV3OriginActor } from './workspaceSyncV3OriginActor.js';
 export function buildTaskChecklistEnvelope(record) {
     let payload;
@@ -17,9 +18,20 @@ export function buildTaskChecklistEnvelope(record) {
     }
     const source = payload;
     if (!Object.prototype.hasOwnProperty.call(source, 'items')
-        || Object.keys(source).some((key) => key !== 'items' && key !== 'originActor')) {
-        throw new Error('Local task checklist outbox payload must contain items and optional originActor.');
+        || Object.keys(source).some((key) => ![
+            'items', 'expectedDetailRevision', 'itemUpdateIntent', 'originActor',
+        ].includes(key))) {
+        throw new Error('Local task checklist outbox payload must contain items and optional expectedDetailRevision/originActor.');
     }
+    const expectedDetailRevision = source.expectedDetailRevision === undefined
+        ? undefined
+        : String(source.expectedDetailRevision).trim();
+    if (source.expectedDetailRevision !== undefined && !expectedDetailRevision) {
+        throw new Error('Local task checklist expectedDetailRevision is invalid.');
+    }
+    const itemUpdateIntent = source.itemUpdateIntent === undefined
+        ? undefined
+        : validateTaskChecklistItemUpdateIntent(source.itemUpdateIntent);
     const checklist = validateWorkspaceSyncV3TaskChecklistPayload({ taskId: record.entityId, items: source.items });
     return {
         contractVersion: 3,
@@ -31,6 +43,8 @@ export function buildTaskChecklistEnvelope(record) {
             baseEntityRevision: record.baseEntityRevision, baseLifecycleRevision: '0',
             payload: {
                 items: checklist.items,
+                ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
+                ...(itemUpdateIntent ? { itemUpdateIntent } : {}),
                 ...(source.originActor !== undefined
                     ? { originActor: parseWorkspaceSyncV3OriginActor(source.originActor) }
                     : {}),

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

@@ -1,4 +1,5 @@
 import type { ChecklistItem, TaskEvent, TaskItem } from '../../core/Taskforce.js';
+import { type TaskChecklistItemUpdateIntent } from './taskChecklistMutationService.js';
 import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity } from './syncDurabilityStore.js';
 export interface LocalTaskChecklistOutboxCore {
     getTask(id: string, workspaceId?: string): TaskItem | null;
@@ -17,6 +18,7 @@ export interface LocalTaskChecklistOutboxCore {
         allowAuthoritativeReplacement?: boolean;
     }): unknown;
     notifyDurableTaskMetadataCommitted(workspaceId: string, taskId: string): void;
+    assertTaskDetailRevisionForUpdate?(id: string, expectedDetailRevision: string, workspaceId?: string): void;
 }
 export declare class LocalAuthoritativeTaskChecklistError extends Error {
     readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
@@ -30,6 +32,8 @@ export declare function enqueueLocalTaskChecklistMutation(input: {
     items: readonly Partial<ChecklistItem>[];
     now: string;
     actorRef: string;
+    expectedDetailRevision?: string;
+    itemUpdateIntent?: TaskChecklistItemUpdateIntent;
     requireV3CombinedOwnership?: boolean;
     onPostCommitError?: (error: unknown) => void;
 }): {

package/dist/sync/v3/localTaskChecklistOutboxService.js

@@ -1,5 +1,6 @@
 import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
 import { buildTaskChecklistActivityEventId } from './taskChecklistActivityIdentity.js';
+import { DurableTaskChecklistMutationError, } from './taskChecklistMutationService.js';
 import { selectDurableTaskMetadataPatch } from '../../core/TaskDurableSyncMutationService.js';
 import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js';
 import { serializeTaskActivityForSync } from './taskActivityJournal.js';
@@ -48,7 +49,13 @@ export function enqueueLocalTaskChecklistMutation(input) {
     const result = input.store.enqueueLocalOperation({
         identity: input.identity,
         domain: 'task-checklist', entityId: input.taskId, mutationKind: 'replace',
-        revisionSource: 'current', payload: withOriginActorPayload({ items }, input.actorRef),
+        revisionSource: 'current', payload: withOriginActorPayload({
+            items,
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
+            ...(input.itemUpdateIntent ? { itemUpdateIntent: input.itemUpdateIntent } : {}),
+        }, input.actorRef),
         additionalTargets: [{
                 domain: 'task', entityId: input.taskId, mutationKind: 'metadata-update',
                 baseEntityRevision: rootRevision.entityRevision, baseLifecycleRevision: rootRevision.lifecycleRevision,
@@ -58,6 +65,12 @@ export function enqueueLocalTaskChecklistMutation(input) {
         ...(input.requireV3CombinedOwnership ? { requireV3PlanningOwnership: 'combined' } : {}),
         now: input.now,
         applyLocalMutation: () => {
+            if (input.expectedDetailRevision) {
+                if (!input.core.assertTaskDetailRevisionForUpdate) {
+                    throw new DurableTaskChecklistMutationError('Task detail revision checks are unavailable.', 'TASK_CHECKLIST_INVALID', 500);
+                }
+                input.core.assertTaskDetailRevisionForUpdate(input.taskId, input.expectedDetailRevision, input.identity.workspaceId);
+            }
             const existing = input.core.getTask(input.taskId, input.identity.workspaceId);
             if (!existing)
                 throw new LocalAuthoritativeTaskChecklistError('Task not found.');

package/dist/sync/v3/localTaskCreateOutboxService.js

@@ -5,7 +5,7 @@ import { validateTaskActivityAuthoritativeRevision } from './taskActivityAuthori
 import { serializeEntityActivityForSync, serializeTaskActivityForSync, WORKSPACE_SYNC_ENTITY_EVENT_APPEND, WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
 import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskChecklistPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskAttachmentLinksV2Payload, validateWorkspaceSyncV3TaskChecklistPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 export class LocalAuthoritativeTaskCreateError extends Error {
     code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
     constructor(message) {
@@ -264,7 +264,9 @@ export function applyAuthoritativeTaskCreateAndAck(input) {
             throw new LocalAuthoritativeTaskCreateError('Authoritative task create attachment-link projection is invalid.');
         }
         try {
-            canonicalAttachmentProjection = validateWorkspaceSyncV3TaskAttachmentLinksPayload(attachmentProjection.payload);
+            canonicalAttachmentProjection = Object.prototype.hasOwnProperty.call(attachmentProjection.payload, 'cardCoverAssetId')
+                ? validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(attachmentProjection.payload)
+                : validateWorkspaceSyncV3TaskAttachmentLinksPayload(attachmentProjection.payload);
         }
         catch {
             throw new LocalAuthoritativeTaskCreateError('Authoritative task create attachment-link payload is invalid.');
@@ -272,10 +274,16 @@ export function applyAuthoritativeTaskCreateAndAck(input) {
         if (canonicalAttachmentProjection.taskId !== task.id) {
             throw new LocalAuthoritativeTaskCreateError('Authoritative task create attachment-link identity is invalid.');
         }
-        const capturedAttachmentProjection = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-            taskId: task.id,
-            links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.identity.workspaceId),
-        });
+        const capturedAttachmentProjection = 'cardCoverAssetId' in canonicalAttachmentProjection
+            ? serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+                taskId: task.id,
+                links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.identity.workspaceId),
+                cardCoverAssetId: task.cardCoverAssetId ?? null,
+            })
+            : serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                taskId: task.id,
+                links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.identity.workspaceId),
+            });
         const relationshipIntent = (projection) => ({
             taskId: projection.taskId,
             links: projection.links.map(({ assetId, role, order, displayName }) => ({
@@ -284,6 +292,7 @@ export function applyAuthoritativeTaskCreateAndAck(input) {
                 order,
                 ...(displayName ? { displayName } : {}),
             })),
+            ...('cardCoverAssetId' in projection ? { cardCoverAssetId: projection.cardCoverAssetId } : {}),
         });
         if (fingerprintWorkspaceSyncPayload(relationshipIntent(canonicalAttachmentProjection))
             !== fingerprintWorkspaceSyncPayload(relationshipIntent(capturedAttachmentProjection))) {

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

@@ -7,6 +7,7 @@ export declare function createLocalTaskMetadataClient(input?: LocalTaskOperation
         entityId: string;
         patch: Partial<TaskItem>;
         saveSource?: "manual" | "autosave";
+        expectedDetailRevision?: string;
         isAuthenticated: boolean;
         dispatchEnabled?: boolean;
     }): Promise<LocalTaskMetadataMutationResult>;

package/dist/sync/v3/localTaskMetadataClient.js

@@ -15,6 +15,7 @@ export function createLocalTaskMetadataClient(input = {}) {
                 payload: {
                     patch,
                     ...(inputValue.saveSource ? { saveSource: inputValue.saveSource } : {}),
+                    ...(inputValue.expectedDetailRevision ? { expectedDetailRevision: inputValue.expectedDetailRevision } : {}),
                 },
             };
             return client.execute({

package/dist/sync/v3/localTaskMetadataOutboxHandler.js

@@ -18,12 +18,15 @@ function buildTaskMetadataEnvelope(record) {
         throw new Error('Local outbox payload must be an object.');
     }
     const payloadRecord = payload;
-    const allowedKeys = new Set(['patch', 'saveSource', 'originActor']);
+    const allowedKeys = new Set(['patch', 'saveSource', 'expectedDetailRevision', 'originActor']);
     if (!Object.prototype.hasOwnProperty.call(payloadRecord, 'patch')
         || Object.keys(payloadRecord).some((key) => !allowedKeys.has(key))) {
         throw new Error('Local task metadata outbox payload must contain patch and optional saveSource/originActor.');
     }
     const saveSource = payloadRecord.saveSource;
+    const expectedDetailRevision = typeof payloadRecord.expectedDetailRevision === 'string'
+        ? payloadRecord.expectedDetailRevision
+        : undefined;
     if (saveSource !== undefined && saveSource !== 'manual' && saveSource !== 'autosave') {
         throw new Error('Local task metadata outbox saveSource must be manual or autosave.');
     }
@@ -41,6 +44,7 @@ function buildTaskMetadataEnvelope(record) {
             payload: {
                 patch: validateDurableTaskMetadataPatch(payloadRecord.patch),
                 ...(saveSource ? { saveSource } : {}),
+                ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
                 ...(payloadRecord.originActor !== undefined
                     ? { originActor: parseWorkspaceSyncV3OriginActor(payloadRecord.originActor) }
                     : {}),

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

@@ -17,6 +17,7 @@ export interface LocalTaskMetadataOutboxCore {
         allowAuthoritativeReplacement?: boolean;
     }): unknown;
     notifyDurableTaskMetadataCommitted(workspaceId: string, taskId: string): void;
+    assertTaskDetailRevisionForUpdate?(id: string, expectedDetailRevision: string, workspaceId?: string): void;
 }
 export declare class LocalAuthoritativeTaskMetadataError extends Error {
     readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
@@ -29,6 +30,7 @@ export declare function enqueueLocalTaskMetadataMutation(input: {
     taskId: string;
     patch: Partial<TaskItem>;
     saveSource?: 'manual' | 'autosave';
+    expectedDetailRevision?: string;
     now: string;
     actorRef: string;
     requireV3CombinedOwnership?: boolean;

package/dist/sync/v3/localTaskMetadataOutboxService.js

@@ -30,10 +30,17 @@ export function enqueueLocalTaskMetadataMutation(input) {
         payload: withOriginActorPayload({
             patch,
             ...(input.saveSource ? { saveSource: input.saveSource } : {}),
+            ...(input.expectedDetailRevision ? { expectedDetailRevision: input.expectedDetailRevision } : {}),
         }, input.actorRef),
         ...(input.requireV3CombinedOwnership ? { requireV3PlanningOwnership: 'combined' } : {}),
         now: input.now,
         applyLocalMutation: () => {
+            if (input.expectedDetailRevision) {
+                if (!input.core.assertTaskDetailRevisionForUpdate) {
+                    throw new DurableTaskMetadataMutationError('Task detail revision checks are unavailable.', 'DURABLE_TASK_PATCH_INVALID', 500);
+                }
+                input.core.assertTaskDetailRevisionForUpdate(input.taskId, input.expectedDetailRevision, input.identity.workspaceId);
+            }
             const task = input.core.updateTask(input.taskId, patch, input.identity.workspaceId, {
                 persistBackup: false,
                 emitRealtime: false,

package/dist/sync/v3/localTaskRestoreOutboxService.js

@@ -5,7 +5,7 @@ import { buildTaskLifecycleActivityEventId } from './taskLifecycleActivityIdenti
 import { validateTaskActivityAuthoritativeRevision } from './taskActivityAuthoritativeRevision.js';
 import { serializeTaskActivityForSync, WORKSPACE_SYNC_ENTITY_EVENT_APPEND, WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, } from './syncDurabilityStore.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskChecklistPayload, validateWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, validateWorkspaceSyncV3TaskAttachmentLinksV2Payload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskChecklistPayload, validateWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 export class LocalAuthoritativeTaskRestoreError extends Error {
     code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
     constructor(message) {
@@ -190,7 +190,9 @@ export function applyAuthoritativeTaskRestoreAndAck(input) {
     let canonicalAttachments;
     try {
         canonicalChecklist = validateWorkspaceSyncV3TaskChecklistPayload(checklist.payload);
-        canonicalAttachments = validateWorkspaceSyncV3TaskAttachmentLinksPayload(attachments.payload);
+        canonicalAttachments = Object.prototype.hasOwnProperty.call(attachments.payload, 'cardCoverAssetId')
+            ? validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(attachments.payload)
+            : validateWorkspaceSyncV3TaskAttachmentLinksPayload(attachments.payload);
     }
     catch {
         throw new LocalAuthoritativeTaskRestoreError('Authoritative task restore nested projection is invalid.');
@@ -214,10 +216,16 @@ export function applyAuthoritativeTaskRestoreAndAck(input) {
             !== fingerprintWorkspaceSyncPayload(serializeWorkspaceSyncV3TaskChecklistPayload({ taskId: task.id, items: task.checklistItems || [] }))) {
         throw new LocalAuthoritativeTaskRestoreError('Authoritative task restore projections do not match the task payload.');
     }
-    const capturedAttachments = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-        taskId: task.id,
-        links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.identity.workspaceId),
-    });
+    const capturedAttachments = 'cardCoverAssetId' in canonicalAttachments
+        ? serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+            taskId: task.id,
+            links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.identity.workspaceId),
+            cardCoverAssetId: task.cardCoverAssetId ?? null,
+        })
+        : serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+            taskId: task.id,
+            links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.identity.workspaceId),
+        });
     if (fingerprintWorkspaceSyncPayload(canonicalAttachments)
         !== fingerprintWorkspaceSyncPayload(capturedAttachments)) {
         throw new LocalAuthoritativeTaskRestoreError('Authoritative task restore attachment links do not match the captured projection.');

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

@@ -9,6 +9,7 @@ export type LocalTaskStatusMutationInput = {
     assigneeIntent: DurableTaskStatusAssigneeIntent;
     canceledReason: string | null;
     metadataPatch?: Partial<TaskItem>;
+    expectedDetailRevision?: string;
     isAuthenticated: boolean;
     dispatchEnabled?: boolean;
 };

package/dist/sync/v3/localTaskStatusClient.js

@@ -20,7 +20,12 @@ export function createLocalTaskStatusClient(input = {}) {
                 domain: 'task',
                 entityId,
                 mutationKind: 'set-status',
-                payload,
+                payload: {
+                    ...payload,
+                    ...(inputValue.expectedDetailRevision
+                        ? { expectedDetailRevision: inputValue.expectedDetailRevision }
+                        : {}),
+                },
             };
             return client.execute({
                 workspaceId,

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

@@ -3,6 +3,7 @@ import { type DurableTaskStatusMutationCore, type DurableTaskStatusMutationPaylo
 import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity, type WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
 import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
 export interface LocalTaskStatusOutboxCore extends DurableTaskStatusMutationCore {
+    assertTaskDetailRevisionForUpdate?(id: string, expectedDetailRevision: string, workspaceId?: string): void;
     getDatabaseAdapter(): DatabaseAdapter;
     getTenantId(): string;
     installDurableTaskStatusAuthoritativeForSync(task: TaskItem, payload: DurableTaskStatusMutationPayload, installAssignee: boolean, workspaceId: string): TaskItem;
@@ -22,6 +23,14 @@ export interface LocalTaskStatusOutboxCore extends DurableTaskStatusMutationCore
         activity: TaskEvent | null;
     }): boolean;
     notifyDurableTaskLifecycleCommitted(workspaceId: string, taskId: string): void;
+    addTaskCommentEventForDurableSync(event: {
+        taskId: string;
+        workspaceId: string;
+        actor: string;
+        eventId: string;
+        createdAt: string;
+        comment: NonNullable<TaskItem['comments']>[number];
+    }): void;
 }
 export declare class LocalAuthoritativeTaskStatusError extends Error {
     readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
@@ -33,6 +42,7 @@ export declare function enqueueLocalTaskStatusMutation(input: {
     identity: WorkspaceSyncOperationIdentity;
     taskId: string;
     payload: unknown;
+    expectedDetailRevision?: string;
     now: string;
     actorRef: string;
     requireV3CombinedOwnership?: boolean;