@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/sync/v3/durableTaskHttpRootMutationRouter.js

@@ -28,10 +28,12 @@ function requiredText(value, label) {
 export class DurableTaskHttpRootMutationError extends Error {
     code;
     statusCode;
-    constructor(message, code, statusCode) {
+    details;
+    constructor(message, code, statusCode, details) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
+        this.details = details;
         this.name = 'DurableTaskHttpRootMutationError';
     }
 }
@@ -120,6 +122,11 @@ export function createDurableTaskHttpRootMutationRouter(input) {
             rethrowDurableReplayError(error, 'Committed durable task HTTP response is invalid.');
         }
     };
+    const detailRevisionPrecondition = (taskId, expectedDetailRevision) => {
+        if (!expectedDetailRevision)
+            return undefined;
+        return () => input.core.assertTaskDetailRevisionForUpdate(taskId, expectedDetailRevision, input.workspaceId);
+    };
     const lifecycle = (taskIdInput, mutationKind, payload) => {
         const taskId = requiredText(taskIdInput, 'Task id');
         const operation = context();
@@ -144,6 +151,12 @@ export function createDurableTaskHttpRootMutationRouter(input) {
     };
     return {
         enabled,
+        hasCommittedOperation() {
+            const operationId = String(input.operationId || '').trim();
+            if (!operationId)
+                return false;
+            return Boolean(store.readCommittedOperationResponse(operationIdentity(operationId)));
+        },
         create(candidate) {
             const source = candidate && typeof candidate === 'object' && !Array.isArray(candidate)
                 ? candidate
@@ -183,7 +196,7 @@ export function createDurableTaskHttpRootMutationRouter(input) {
                 throw new DurableTaskHttpRootMutationError('The durable task mutation is already in progress.', 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS', 409);
             return result.response.authoritative.payload;
         },
-        update(taskIdInput, candidate, saveSource, activityAction) {
+        update(taskIdInput, candidate, saveSource, activityAction, expectedDetailRevision) {
             const taskId = requiredText(taskIdInput, 'Task id');
             if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
                 throw new DurableTaskHttpRootMutationError('Task patch must be an object.', 'DURABLE_TASK_PATCH_INVALID', 400);
@@ -224,6 +237,8 @@ export function createDurableTaskHttpRootMutationRouter(input) {
                     now: operation.acceptedAtIso,
                     leaseExpiresAt: new Date(operation.acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
                     actorRef: input.actorRef,
+                    expectedDetailRevision,
+                    assertPrecondition: detailRevisionPrecondition(taskId, expectedDetailRevision),
                     onPostCommitError: input.onPostCommitError,
                 });
                 if (result.state === 'in_progress')
@@ -283,6 +298,8 @@ export function createDurableTaskHttpRootMutationRouter(input) {
                     actorRef: input.actorRef,
                     saveSource,
                     activityAction,
+                    expectedDetailRevision,
+                    assertPrecondition: detailRevisionPrecondition(taskId, expectedDetailRevision),
                     onPostCommitError: input.onPostCommitError,
                 });
                 if (result.state === 'in_progress')
@@ -341,6 +358,14 @@ export function createDurableTaskHttpRootMutationRouter(input) {
             if (options?.atomicRecovery) {
                 const notifications = [];
                 const result = input.core.getDatabaseAdapter().transaction(() => {
+                    // Child durable mutations lock the workspace sequence before
+                    // touching task rows. Take the same lock first when a batch
+                    // may combine a legacy root write with durable child owners.
+                    store.lockWorkspaceSequenceForMutation({
+                        tenantId: input.tenantId,
+                        workspaceId: input.workspaceId,
+                        now: operation.acceptedAtIso,
+                    });
                     const value = apply({
                         runChild: (mutation) => input.core.getDatabaseAdapter().transaction(mutation)(),
                         deferPostCommitNotification: (notify) => notifications.push(notify),

package/dist/sync/v3/localInitiativeOutboxService.js

@@ -294,8 +294,9 @@ function validateActivitySemantics(input) {
     const authoritativeAttachmentLinks = validateCanonicalPlanningAttachmentLinks(input.authoritative.attachments);
     const comparableExpectedDetails = normalizePlanningActivityDetailsForComparison(expectedDetails, input.record.mutationKind, authoritativeAttachmentLinks);
     const comparableAuthoritativeDetails = normalizePlanningActivityDetailsForComparison((input.activity.details || {}), input.record.mutationKind, authoritativeAttachmentLinks);
-    if (fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
-        !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
+    if (!input.boundedAttachmentRebase
+        && fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
+            !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
         throw new LocalAuthoritativeInitiativeError('Authoritative initiative activity details differ from the captured mutation.');
     }
 }
@@ -437,6 +438,7 @@ export function applyAuthoritativeInitiativeAndAck(input) {
         payload: payload,
         authoritative: initiative,
         activity,
+        boundedAttachmentRebase,
     });
     const revision = validateInitiativeActivityAuthoritativeRevision({
         response: response,

package/dist/sync/v3/localOutboxDispatcher.js

@@ -279,7 +279,11 @@ export async function dispatchLocalOutboxBatch(input) {
             const details = errorDetails(result.data, `WORKSPACE_SYNC_TRANSPORT_${result.status || 'NETWORK'}`, 'Workspace sync delivery failed.');
             const stableErrorCode = result.status === 401 ? 'WORKSPACE_SYNC_TRANSPORT_401' : details.code;
             const contentPushRequired = result.status === 425
-                && stableErrorCode === 'TASK_ATTACHMENT_ASSET_NOT_READY';
+                && [
+                    'TASK_ATTACHMENT_ASSET_NOT_READY',
+                    'WORKSTREAM_ATTACHMENT_NOT_READY',
+                    'INITIATIVE_ATTACHMENT_NOT_READY',
+                ].includes(stableErrorCode);
             const inProgressDelay = operationRetryAt(result.data, now().getTime());
             const cloudV3Disabled = result.status === 404 && isCloudV3Disabled(record, result.data);
             // A first metadata edit may dispatch before legacy reconciliation has

package/dist/sync/v3/localTaskAttachmentLinksOutboxHandler.js

@@ -17,8 +17,13 @@ export function buildTaskAttachmentLinksEnvelope(record) {
     }
     const source = payload;
     if (!Object.prototype.hasOwnProperty.call(source, 'links')
-        || Object.keys(source).some((key) => key !== 'links' && key !== 'originActor')) {
-        throw new Error('Local task attachment-link outbox payload must contain links and optional originActor.');
+        || Object.keys(source).some((key) => !['links', 'cardCoverAssetId', 'originActor'].includes(key))) {
+        throw new Error('Local task attachment-link outbox payload must contain links and optional card cover metadata.');
+    }
+    const hasCardCoverAssetId = Object.prototype.hasOwnProperty.call(source, 'cardCoverAssetId');
+    if (hasCardCoverAssetId && source.cardCoverAssetId !== null
+        && (typeof source.cardCoverAssetId !== 'string' || !source.cardCoverAssetId.trim())) {
+        throw new Error('Local task attachment-link card cover must be a non-empty string or null.');
     }
     const aggregate = validateWorkspaceSyncV3TaskAttachmentLinksPayload({ taskId: record.entityId, links: source.links });
     return {
@@ -31,6 +36,11 @@ export function buildTaskAttachmentLinksEnvelope(record) {
             baseEntityRevision: record.baseEntityRevision, baseLifecycleRevision: '0',
             payload: {
                 links: aggregate.links,
+                ...(hasCardCoverAssetId ? {
+                    cardCoverAssetId: source.cardCoverAssetId === null
+                        ? null
+                        : String(source.cardCoverAssetId).trim(),
+                } : {}),
                 ...(source.originActor !== undefined
                     ? { originActor: parseWorkspaceSyncV3OriginActor(source.originActor) }
                     : {}),

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;
@@ -26,6 +28,7 @@ export declare function enqueueLocalTaskAttachmentLinksMutation(input: {
     identity: WorkspaceSyncOperationIdentity;
     taskId: string;
     links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+    cardCoverAssetId?: string | null;
     now: string;
     actorRef: string;
     requireV3CombinedOwnership?: boolean;

package/dist/sync/v3/localTaskAttachmentLinksOutboxService.js

@@ -1,11 +1,13 @@
-import { projectResolvedTaskAttachmentLinksForDurableSync } from '../../core/TaskAttachmentLinksDurableMutationService.js';
+import { projectResolvedTaskAttachmentLinksForDurableSync, resolveTaskCardCoverAssetIdForLinks, } from '../../core/TaskAttachmentLinksDurableMutationService.js';
 import { selectDurableTaskMetadataPatch } from '../../core/TaskDurableSyncMutationService.js';
 import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
 import { buildTaskAttachmentLinksActivityEventId } from './taskAttachmentLinksActivityIdentity.js';
 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;
@@ -111,7 +131,12 @@ export function enqueueLocalTaskAttachmentLinksMutation(input) {
     const result = input.store.enqueueLocalOperation({
         identity: input.identity,
         domain: 'task-attachment-links', entityId: input.taskId, mutationKind: 'replace',
-        revisionSource: 'current', payload: withOriginActorPayload({ links }, input.actorRef),
+        revisionSource: 'current', payload: withOriginActorPayload({
+            links,
+            ...(Object.prototype.hasOwnProperty.call(input, 'cardCoverAssetId')
+                ? { cardCoverAssetId: input.cardCoverAssetId ?? null }
+                : {}),
+        }, input.actorRef),
         additionalTargets: [{
                 domain: 'task', entityId: input.taskId, mutationKind: 'metadata-update',
                 baseEntityRevision: rootRevision.entityRevision, baseLifecycleRevision: rootRevision.lifecycleRevision,
@@ -127,11 +152,18 @@ export function enqueueLocalTaskAttachmentLinksMutation(input) {
             if (existing.isArchived)
                 throw new LocalAuthoritativeTaskAttachmentLinksError('Archived tasks are read-only.');
             const previousLinks = input.core.listTaskAttachmentLinksForDurableSync(input.taskId, input.identity.workspaceId);
+            const cardCoverAssetId = resolveTaskCardCoverAssetIdForLinks({
+                currentCardCoverAssetId: existing.cardCoverAssetId,
+                ...(Object.prototype.hasOwnProperty.call(input, 'cardCoverAssetId')
+                    ? { requestedCardCoverAssetId: input.cardCoverAssetId }
+                    : {}),
+                links,
+            });
             const currentMs = Date.parse(String(existing.updatedAt || existing.createdAt));
             const requestedMs = Date.parse(input.now);
             const updatedAt = Number.isFinite(currentMs) && currentMs >= requestedMs
                 ? new Date(currentMs + 1).toISOString() : input.now;
-            const task = input.core.updateTask(input.taskId, { attachments }, input.identity.workspaceId, {
+            const task = input.core.updateTask(input.taskId, { attachments, cardCoverAssetId }, input.identity.workspaceId, {
                 persistBackup: false, emitRealtime: false, syncUpdatedAt: updatedAt,
                 actorRef: input.actorRef, taskEventId: activityEventId, taskEventAction: 'task-attachments-changed',
                 taskEventDetails: canonicalizeEntityActivityDetailsForSync({
@@ -194,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,
@@ -256,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,
@@ -270,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/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;
@@ -33,6 +34,7 @@ export declare function enqueueLocalTaskStatusMutation(input: {
     identity: WorkspaceSyncOperationIdentity;
     taskId: string;
     payload: unknown;
+    expectedDetailRevision?: string;
     now: string;
     actorRef: string;
     requireV3CombinedOwnership?: boolean;

package/dist/sync/v3/localTaskStatusOutboxService.js

@@ -74,23 +74,42 @@ export function enqueueLocalTaskStatusMutation(input) {
             taskLifecycle: true,
             taskAssignee: payload.assigneeIntent.kind !== 'preserve',
         },
-        payload: withOriginActorPayload({ ...payload }, input.actorRef),
+        payload: withOriginActorPayload({
+            ...payload,
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
+        }, input.actorRef),
         ...(payload.workflowAssignment ? {
             coalesceWorkflowAssignmentExecutionId: payload.workflowAssignment.execution.id,
         } : {}),
         ...(input.requireV3CombinedOwnership ? { requireV3PlanningOwnership: 'combined' } : {}),
         now: input.now,
-        applyLocalMutation: () => applyTaskStatusMutationForDurableSync({
-            core: input.core,
-            workspaceId: input.identity.workspaceId,
-            taskId,
-            targetStatus: statusPayload.status,
-            metadataPatch: statusPayload.metadataPatch,
-            assigneeIntent: statusPayload.assigneeIntent,
-            canceledReason: statusPayload.canceledReason,
-            updatedAt: input.now,
-            actorRef: input.actorRef,
-            taskEventId: activityEventId,
+        applyLocalMutation: () => {
+            if (input.expectedDetailRevision) {
+                if (!input.core.assertTaskDetailRevisionForUpdate) {
+                    throw new Error('Task detail revision checks are unavailable.');
+                }
+                input.core.assertTaskDetailRevisionForUpdate(taskId, input.expectedDetailRevision, input.identity.workspaceId);
+            }
+            return applyTaskStatusMutationForDurableSync({
+                core: input.core,
+                workspaceId: input.identity.workspaceId,
+                taskId,
+                targetStatus: statusPayload.status,
+                metadataPatch: statusPayload.metadataPatch,
+                assigneeIntent: statusPayload.assigneeIntent,
+                canceledReason: statusPayload.canceledReason,
+                updatedAt: input.now,
+                actorRef: input.actorRef,
+                taskEventId: activityEventId,
+            });
+        },
+        buildCanonicalIntent: (result) => ({
+            metadataPatch: Object.fromEntries(Object.keys(payload.metadataPatch).map((key) => [
+                key,
+                result.task[key] ?? null,
+            ])),
         }),
     });
     if (!result.enqueued)
@@ -189,9 +208,31 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
     const localCanonical = input.core.getTask(task.id, input.identity.workspaceId);
     if (!localCanonical)
         throw new LocalAuthoritativeTaskStatusError('Local task status projection is missing.');
+    let canonicalMetadataIntent = null;
+    if (input.record.canonicalIntentJson) {
+        try {
+            const parsed = JSON.parse(input.record.canonicalIntentJson);
+            canonicalMetadataIntent = parsed.metadataPatch
+                && typeof parsed.metadataPatch === 'object'
+                && !Array.isArray(parsed.metadataPatch)
+                ? parsed.metadataPatch
+                : null;
+        }
+        catch {
+            canonicalMetadataIntent = null;
+        }
+        if (!canonicalMetadataIntent) {
+            throw new LocalAuthoritativeTaskStatusError('Persisted canonical task status intent is invalid.');
+        }
+    }
     for (const key of Object.keys(payload.metadataPatch)) {
+        if (canonicalMetadataIntent && !Object.prototype.hasOwnProperty.call(canonicalMetadataIntent, key)) {
+            throw new LocalAuthoritativeTaskStatusError('Persisted canonical task status intent is incomplete.');
+        }
         const actual = task[key];
-        const expected = localCanonical[key];
+        const expected = canonicalMetadataIntent
+            ? canonicalMetadataIntent[key]
+            : localCanonical[key];
         if (fingerprintWorkspaceSyncPayload(actual ?? null) !== fingerprintWorkspaceSyncPayload(expected ?? null)) {
             throw new LocalAuthoritativeTaskStatusError('Authoritative task metadata does not match the persisted request.');
         }

package/dist/sync/v3/localWorkstreamOutboxService.js

@@ -300,8 +300,9 @@ function validateActivitySemantics(input) {
     const authoritativeAttachmentLinks = validateCanonicalPlanningAttachmentLinks(input.authoritative.attachments);
     const comparableExpectedDetails = normalizePlanningActivityDetailsForComparison(expectedDetails, input.record.mutationKind, authoritativeAttachmentLinks);
     const comparableAuthoritativeDetails = normalizePlanningActivityDetailsForComparison((input.activity.details || {}), input.record.mutationKind, authoritativeAttachmentLinks);
-    if (fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
-        !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
+    if (!input.boundedAttachmentRebase
+        && fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
+            !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
         throw new LocalAuthoritativeWorkstreamError('Authoritative workstream activity details differ from the captured mutation.');
     }
 }
@@ -500,6 +501,7 @@ export function applyAuthoritativeWorkstreamAndAck(input) {
         payload: payload,
         authoritative: workstream,
         activity,
+        boundedAttachmentRebase,
     });
     const revision = validateWorkstreamActivityAuthoritativeRevision({
         response: response,