@taskforcehq/taskforce 0.3.327 → 0.3.329

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

@@ -80,6 +80,7 @@ export type WorkspaceSyncOutboxRecord = WorkspaceSyncOperationIdentity & {
     baseLifecycleRevision: string;
     payloadJson: string;
     payloadFingerprint: string;
+    canonicalIntentJson: string | null;
     status: string;
     attemptCount: number;
     initialNotFoundAttemptCount: number;
@@ -152,6 +153,9 @@ export type WorkspaceSyncDomainCoexistenceTarget = {
     domain: string;
     entityId: string;
 };
+export type WorkspaceSyncRecoveryBaselineTarget = WorkspaceSyncDomainCoexistenceTarget & {
+    required: boolean;
+};
 export type WorkspaceSyncPlanningRevisionProjection = {
     entityId: string;
     coexistenceOwned: boolean;
@@ -374,6 +378,11 @@ export declare class WorkspaceSyncDurabilityStore {
         workspaceId: string;
         recoveryBatchId: string;
     }): WorkspaceSyncDomainCoexistenceTarget[];
+    listOutboxRecoveryBaselineTargets(input: {
+        tenantId: string;
+        workspaceId: string;
+        recoveryBatchId: string;
+    }): WorkspaceSyncRecoveryBaselineTarget[];
     prepareTaskRootOutboxRecoveryReplay(input: {
         tenantId: string;
         workspaceId: string;
@@ -534,6 +543,7 @@ export declare class WorkspaceSyncDurabilityStore {
         queuedTaskSuccessor?: boolean;
         queuedWorkflowRuntimeSuccessor?: boolean;
         coalesceWorkflowAssignmentExecutionId?: string;
+        buildCanonicalIntent?: (mutationResult: T) => unknown;
     }): {
         enqueued: boolean;
         mutationResult?: T;
@@ -752,6 +762,11 @@ export declare class WorkspaceSyncDurabilityStore {
     private assertTaskCommentAppendRecoveryEventOwned;
     private isTaskCommentAppendRecoveryIntentSatisfied;
     private prepareTaskRecoveryPayload;
+    lockWorkspaceSequenceForMutation(input: {
+        tenantId: string;
+        workspaceId: string;
+        now: string;
+    }): void;
     private allocateSequenceRange;
     private allocateOutboxEnqueueSequence;
     private readOperationRow;

package/dist/sync/v3/syncDurabilityStore.js

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from 'crypto';
 import { normalizePlanningComments, } from '../planningCanonicalFields.js';
 import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
-import { buildTaskCreateActivityEventId } from './taskCreateActivityIdentity.js';
+import { buildTaskAttachmentLinksActivityEventId } from './taskAttachmentLinksActivityIdentity.js';
 import { buildTaskCommentActivityEventId } from './taskCommentActivityIdentity.js';
+import { buildTaskCreateActivityEventId } from './taskCreateActivityIdentity.js';
 import { buildTaskLifecycleActivityEventId, } from './taskLifecycleActivityIdentity.js';
 import { buildTaskMetadataActivityEventId } from './taskMetadataActivityIdentity.js';
 import { parseWorkspaceSyncV3OriginActor } from './workspaceSyncV3OriginActor.js';
@@ -251,7 +252,8 @@ export function hasCompletedRecoveryForSupersededEntityEvent(db, input) {
     if (entityType !== 'task')
         return false;
     const sources = db.prepare(`
-        SELECT source.client_id, source.operation_id, source.mutation_kind
+        SELECT source.client_id, source.operation_id, source.domain, source.mutation_kind,
+               source.last_error_code
         FROM workspace_sync_outbox AS source
         INNER JOIN workspace_sync_outbox_recoveries AS recovery
           ON recovery.tenant_id = source.tenant_id
@@ -259,7 +261,7 @@ export function hasCompletedRecoveryForSupersededEntityEvent(db, input) {
          AND recovery.recovery_batch_id = source.recovery_batch_id
         WHERE source.tenant_id = ?
           AND source.workspace_id = ?
-          AND source.domain = 'task'
+          AND source.domain IN ('task', 'task-attachment-links')
           AND source.entity_id = ?
           AND source.status = 'superseded'
           AND recovery.state = 'completed'
@@ -268,9 +270,19 @@ export function hasCompletedRecoveryForSupersededEntityEvent(db, input) {
     return sources.some((source) => {
         const clientId = String(source.client_id || '').trim();
         const operationId = String(source.operation_id || '').trim();
+        const domain = String(source.domain || '').trim();
         const mutationKind = String(source.mutation_kind || '').trim();
         if (!clientId || !operationId)
             return false;
+        if (domain === 'task-attachment-links'
+            && mutationKind === 'replace'
+            && String(source.last_error_code || '') === 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID') {
+            return buildTaskAttachmentLinksActivityEventId({
+                workspaceId, clientId, operationId, taskId: entityId,
+            }) === eventId;
+        }
+        if (domain !== 'task')
+            return false;
         if (mutationKind === 'create') {
             return buildTaskCreateActivityEventId({
                 workspaceId, clientId, operationId, taskId: entityId,
@@ -779,7 +791,7 @@ export class WorkspaceSyncDurabilityStore {
                    mutation_kind, owns_task_metadata, owns_task_lifecycle, owns_task_assignee,
                    CAST(base_entity_revision AS TEXT) AS base_entity_revision,
                    CAST(base_lifecycle_revision AS TEXT) AS base_lifecycle_revision,
-                   payload_json, payload_fingerprint, status, attempt_count,
+                   payload_json, payload_fingerprint, canonical_intent_json, status, attempt_count,
                    initial_not_found_attempt_count,
                    CAST(enqueue_sequence AS TEXT) AS enqueue_sequence,
                    rebase_before_first_attempt, lease_owner, lease_expires_at
@@ -835,7 +847,7 @@ export class WorkspaceSyncDurabilityStore {
                    mutation_kind, owns_task_metadata, owns_task_lifecycle, owns_task_assignee,
                    CAST(base_entity_revision AS TEXT) AS base_entity_revision,
                    CAST(base_lifecycle_revision AS TEXT) AS base_lifecycle_revision,
-                   payload_json, payload_fingerprint, status, attempt_count,
+                   payload_json, payload_fingerprint, canonical_intent_json, status, attempt_count,
                    initial_not_found_attempt_count,
                    CAST(enqueue_sequence AS TEXT) AS enqueue_sequence,
                    rebase_before_first_attempt, lease_owner, lease_expires_at
@@ -1016,7 +1028,7 @@ export class WorkspaceSyncDurabilityStore {
                    mutation_kind, owns_task_metadata, owns_task_lifecycle, owns_task_assignee,
                    CAST(base_entity_revision AS TEXT) AS base_entity_revision,
                    CAST(base_lifecycle_revision AS TEXT) AS base_lifecycle_revision,
-                   payload_json, payload_fingerprint, status, attempt_count,
+                   payload_json, payload_fingerprint, canonical_intent_json, status, attempt_count,
                    initial_not_found_attempt_count,
                    CAST(enqueue_sequence AS TEXT) AS enqueue_sequence,
                    rebase_before_first_attempt, lease_owner, lease_expires_at
@@ -1283,11 +1295,16 @@ export class WorkspaceSyncDurabilityStore {
         })();
     }
     listOutboxRecoveryTargets(input) {
+        return this.listOutboxRecoveryBaselineTargets(input).map(({ domain, entityId }) => ({ domain, entityId }));
+    }
+    listOutboxRecoveryBaselineTargets(input) {
         const tenantId = requireText(input.tenantId, 'Tenant id');
         const workspaceId = requireText(input.workspaceId, 'Workspace id');
         const recoveryBatchId = requireText(input.recoveryBatchId, 'Recovery batch id');
         const rows = this.db.prepare(`
-            SELECT DISTINCT target.domain, target.entity_id
+            SELECT target.domain, target.entity_id,
+                   source.dispatch_class, source.domain AS source_domain,
+                   source.mutation_kind AS source_mutation_kind
             FROM workspace_sync_outbox AS source
             INNER JOIN workspace_sync_outbox_targets AS target
               ON target.tenant_id = source.tenant_id
@@ -1298,14 +1315,52 @@ export class WorkspaceSyncDurabilityStore {
               AND source.recovery_batch_id = ?
               AND source.status = 'superseded'
               AND source.replay_of_operation_id IS NULL
-            ORDER BY target.domain, target.entity_id
+            ORDER BY target.domain, target.entity_id, source.enqueue_sequence, source.operation_id
         `).all(tenantId, workspaceId, recoveryBatchId);
-        if (rows.length === 0)
+        const targets = new Map();
+        for (const row of rows) {
+            const domain = requireText(row.domain, 'Recovery target domain');
+            const entityId = requireText(row.entity_id, 'Recovery target entity id');
+            const key = `${domain}\0${entityId}`;
+            const legacyAdoptionEvent = domain === 'entity-event'
+                && row.dispatch_class === 'legacy-adoption'
+                && row.source_domain === 'entity-event'
+                && row.source_mutation_kind === 'adopt-legacy-batch';
+            const existing = targets.get(key);
+            targets.set(key, {
+                domain,
+                entityId,
+                required: Boolean(existing?.required || !legacyAdoptionEvent),
+            });
+        }
+        const attachmentSources = this.db.prepare(`
+            SELECT source.client_id, source.operation_id, source.entity_id
+            FROM workspace_sync_outbox AS source
+            WHERE source.tenant_id = ? AND source.workspace_id = ?
+              AND source.recovery_batch_id = ?
+              AND source.status = 'superseded'
+              AND source.replay_of_operation_id IS NULL
+              AND source.domain = 'task-attachment-links'
+              AND source.mutation_kind = 'replace'
+              AND source.last_error_code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID'
+        `).all(tenantId, workspaceId, recoveryBatchId);
+        for (const source of attachmentSources) {
+            const target = {
+                domain: 'entity-event',
+                entityId: buildTaskAttachmentLinksActivityEventId({
+                    workspaceId,
+                    clientId: requireText(source.client_id, 'Recovery client id'),
+                    operationId: requireText(source.operation_id, 'Recovery operation id'),
+                    taskId: requireText(source.entity_id, 'Recovery task id'),
+                }),
+                required: true,
+            };
+            targets.set(`${target.domain}\0${target.entityId}`, target);
+        }
+        const deduplicated = [...targets.values()].sort((left, right) => (compareCodeUnits(left.domain, right.domain) || compareCodeUnits(left.entityId, right.entityId)));
+        if (deduplicated.length === 0)
             throw new Error('Workspace sync recovery snapshot has no targets.');
-        return rows.map((row) => ({
-            domain: requireText(row.domain, 'Recovery target domain'),
-            entityId: requireText(row.entity_id, 'Recovery target entity id'),
-        }));
+        return deduplicated;
     }
     prepareTaskRootOutboxRecoveryReplay(input) {
         const tenantId = requireText(input.tenantId, 'Tenant id');
@@ -1341,7 +1396,8 @@ export class WorkspaceSyncDurabilityStore {
             const recoverySources = this.db.prepare(`
                 SELECT client_id, operation_id, dispatch_class, domain, entity_id, mutation_kind,
                        owns_task_metadata, owns_task_lifecycle, owns_task_assignee,
-                       payload_json, payload_fingerprint, last_error_code, last_error_message,
+                       payload_json, payload_fingerprint, canonical_intent_json,
+                       last_error_code, last_error_message,
                        EXISTS (
                            SELECT 1
                            FROM workspace_sync_outbox AS replay_candidate
@@ -1395,6 +1451,34 @@ export class WorkspaceSyncDurabilityStore {
                     this.readEntityEventLegacyAdoptionRecoveryIntent(workspaceId, source);
                 }
             }
+            const recoverySourceKey = (source) => (`${requireText(source.client_id, 'Source client id')}\0${requireText(source.operation_id, 'Source operation id')}`);
+            const legacyAdoptionEventsBySource = new Map();
+            const latestLegacyAdoptionSourceByEvent = new Map();
+            for (const source of recoverySources) {
+                if (source.dispatch_class !== 'legacy-adoption'
+                    || source.domain !== 'entity-event'
+                    || source.mutation_kind !== 'adopt-legacy-batch')
+                    continue;
+                const sourceKey = recoverySourceKey(source);
+                const events = this.readEntityEventLegacyAdoptionRecoveryIntent(workspaceId, source).events;
+                legacyAdoptionEventsBySource.set(sourceKey, events);
+                for (const event of events)
+                    latestLegacyAdoptionSourceByEvent.set(event.id, sourceKey);
+            }
+            const legacyAdoptionReplayEventsBySource = new Map();
+            for (const [sourceKey, events] of legacyAdoptionEventsBySource) {
+                legacyAdoptionReplayEventsBySource.set(sourceKey, events.filter((event) => {
+                    if (latestLegacyAdoptionSourceByEvent.get(event.id) !== sourceKey)
+                        return false;
+                    const revision = this.readEntityRevisionCoordinates({
+                        tenantId,
+                        workspaceId,
+                        domain: 'entity-event',
+                        entityId: event.id,
+                    });
+                    return revision.entityRevision === '0';
+                }));
+            }
             const latestAttachmentSourceByEntity = new Map();
             for (const source of recoverySources) {
                 if (source.domain === 'task-attachment-links' && source.mutation_kind === 'replace') {
@@ -1419,14 +1503,11 @@ export class WorkspaceSyncDurabilityStore {
                 if (source.dispatch_class === 'legacy-adoption'
                     && source.domain === 'entity-event'
                     && source.mutation_kind === 'adopt-legacy-batch') {
-                    // Legacy adoption migrates immutable historical activity; it is
-                    // not a user-authored mutation that can be rebased. A targeted
-                    // authoritative baseline proves that every event identity exists
-                    // in cloud and installs the canonical cloud body locally. Trying
-                    // to replay the older frozen body can only re-create the same
-                    // identity/revision conflict forever, so the baseline itself
-                    // satisfies this migration intent.
-                    return false;
+                    // The authoritative baseline satisfies events already present in
+                    // cloud. A mixed legacy batch may also contain new immutable
+                    // events; replay only those still lacking authoritative ownership,
+                    // and let the latest overlapping batch own each event once.
+                    return (legacyAdoptionReplayEventsBySource.get(recoverySourceKey(source)) || []).length > 0;
                 }
                 if (Number(source.baseline_satisfaction_candidate || 0) !== 1) {
                     return true;
@@ -1492,7 +1573,22 @@ export class WorkspaceSyncDurabilityStore {
                     throw new Error('Workspace sync recovery replay currently supports task-root, task-comment append, '
                         + 'task attachment-link, and legacy entity-event adoption intents only.');
                 }
-                replayPayloads.set(`${requireText(source.client_id, 'Source client id')}\0${requireText(source.operation_id, 'Source operation id')}`, this.prepareRecoveryPayload(tenantId, workspaceId, source));
+                const sourceKey = recoverySourceKey(source);
+                if (supportedEntityEventAdoption) {
+                    const events = legacyAdoptionReplayEventsBySource.get(sourceKey) || [];
+                    if (events.length === 0)
+                        throw new Error('Legacy entity-event adoption recovery replay is empty.');
+                    const payloadJson = canonicalWorkspaceSyncJson({ events });
+                    replayPayloads.set(sourceKey, {
+                        payloadJson,
+                        payloadFingerprint: fingerprintWorkspaceSyncPayload({ events }),
+                        replayMutationKind: 'adopt-legacy-batch',
+                        workflowDependencyCoalesced: false,
+                    });
+                }
+                else {
+                    replayPayloads.set(sourceKey, this.prepareRecoveryPayload(tenantId, workspaceId, source));
+                }
             }
             for (const source of sources) {
                 const sourceClientId = requireText(source.client_id, 'Source client id');
@@ -1512,11 +1608,22 @@ export class WorkspaceSyncDurabilityStore {
                     WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
                     ORDER BY domain, entity_id
                 `).all(tenantId, workspaceId, sourceClientId, sourceOperationId);
+                const legacyReplayEvents = source.dispatch_class === 'legacy-adoption'
+                    && source.domain === 'entity-event'
+                    && source.mutation_kind === 'adopt-legacy-batch'
+                    ? legacyAdoptionReplayEventsBySource.get(recoverySourceKey(source)) || []
+                    : null;
+                const replayEventIds = legacyReplayEvents
+                    ? new Set(legacyReplayEvents.map((event) => event.id))
+                    : null;
                 const replayTargets = source.domain === 'task-comments'
                     && source.mutation_kind === 'append'
                     ? sourceTargets.filter((target) => (target.domain === 'task-comments'
                         && target.entity_id === source.entity_id))
-                    : sourceTargets;
+                    : replayEventIds
+                        ? sourceTargets.filter((target) => (target.domain === 'entity-event'
+                            && replayEventIds.has(String(target.entity_id || ''))))
+                        : sourceTargets;
                 if (replayTargets.length === 0)
                     throw new Error('Workspace sync recovery source has no targets.');
                 const targetRevisions = replayTargets.map((target) => ({
@@ -1528,7 +1635,9 @@ export class WorkspaceSyncDurabilityStore {
                         entityId: requireText(target.entity_id, 'Target entity id'),
                     }),
                 }));
-                const primary = targetRevisions.find(({ target }) => (target.domain === source.domain && target.entity_id === source.entity_id));
+                const replayEntityId = legacyReplayEvents?.[0]?.id
+                    || requireText(source.entity_id, 'Source entity id');
+                const primary = targetRevisions.find(({ target }) => (target.domain === source.domain && target.entity_id === replayEntityId));
                 if (!primary)
                     throw new Error('Workspace sync recovery source primary target is missing.');
                 const enqueueSequence = this.allocateOutboxEnqueueSequence(tenantId, workspaceId, now);
@@ -1538,18 +1647,18 @@ export class WorkspaceSyncDurabilityStore {
                         dispatch_class, domain, entity_id, mutation_kind,
                         owns_task_metadata, owns_task_lifecycle, owns_task_assignee,
                         base_entity_revision, base_lifecycle_revision,
-                        payload_json, payload_fingerprint, status, attempt_count,
+                        payload_json, payload_fingerprint, canonical_intent_json, status, attempt_count,
                         initial_not_found_attempt_count, enqueue_sequence, rebase_before_first_attempt,
                         next_attempt_at, recovery_batch_id,
                         replay_of_client_id, replay_of_operation_id, created_at, updated_at
-                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 0, 0, ?, 1,
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 0, 0, ?, 1,
                         ?, ?, ?, ?, ?, ?)
                     ON CONFLICT (tenant_id, workspace_id, client_id, operation_id) DO NOTHING
-                `).run(tenantId, workspaceId, operationId, WORKSPACE_SYNC_CONTRACT_VERSION, sourceClientId, requireOutboxDispatchClass(source.dispatch_class), requireText(source.domain, 'Source domain'), requireText(source.entity_id, 'Source entity id'), replayPayload.replayMutationKind, Number(source.owns_task_metadata) === 1 ? 1 : 0, Number(source.owns_task_lifecycle) === 1 ? 1 : 0, Number(source.owns_task_assignee) === 1 ? 1 : 0, primary.revision.entityRevision, primary.revision.lifecycleRevision, replayPayload.payloadJson, replayPayload.payloadFingerprint, enqueueSequence, now, recoveryBatchId, sourceClientId, sourceOperationId, now, now);
+                `).run(tenantId, workspaceId, operationId, WORKSPACE_SYNC_CONTRACT_VERSION, sourceClientId, requireOutboxDispatchClass(source.dispatch_class), requireText(source.domain, 'Source domain'), replayEntityId, replayPayload.replayMutationKind, Number(source.owns_task_metadata) === 1 ? 1 : 0, Number(source.owns_task_lifecycle) === 1 ? 1 : 0, Number(source.owns_task_assignee) === 1 ? 1 : 0, primary.revision.entityRevision, primary.revision.lifecycleRevision, replayPayload.payloadJson, replayPayload.payloadFingerprint, source.canonical_intent_json == null ? null : String(source.canonical_intent_json), enqueueSequence, now, recoveryBatchId, sourceClientId, sourceOperationId, now, now);
                 this.db.prepare(`
                     UPDATE workspace_sync_outbox
                     SET base_entity_revision = ?, base_lifecycle_revision = ?,
-                        payload_json = ?, payload_fingerprint = ?,
+                        payload_json = ?, payload_fingerprint = ?, canonical_intent_json = ?,
                         status = 'pending', attempt_count = 0, initial_not_found_attempt_count = 0,
                         rebase_before_first_attempt = 1, next_attempt_at = ?,
                         lease_owner = NULL, lease_expires_at = NULL,
@@ -1559,7 +1668,7 @@ export class WorkspaceSyncDurabilityStore {
                     WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
                       AND recovery_batch_id = ? AND replay_of_client_id = ? AND replay_of_operation_id = ?
                       AND status = 'superseded'
-                `).run(primary.revision.entityRevision, primary.revision.lifecycleRevision, replayPayload.payloadJson, replayPayload.payloadFingerprint, now, now, tenantId, workspaceId, sourceClientId, operationId, recoveryBatchId, sourceClientId, sourceOperationId);
+                `).run(primary.revision.entityRevision, primary.revision.lifecycleRevision, replayPayload.payloadJson, replayPayload.payloadFingerprint, source.canonical_intent_json == null ? null : String(source.canonical_intent_json), now, now, tenantId, workspaceId, sourceClientId, operationId, recoveryBatchId, sourceClientId, sourceOperationId);
                 if (replayPayload.workflowDependencyCoalesced) {
                     this.db.prepare(`
                         UPDATE workspace_sync_outbox
@@ -1577,7 +1686,7 @@ export class WorkspaceSyncDurabilityStore {
                 `).get(tenantId, workspaceId, sourceClientId, operationId);
                 if (!replayRow
                     || replayRow.domain !== source.domain
-                    || replayRow.entity_id !== source.entity_id
+                    || replayRow.entity_id !== replayEntityId
                     || replayRow.mutation_kind !== replayPayload.replayMutationKind
                     || replayRow.payload_fingerprint !== replayPayload.payloadFingerprint
                     || replayRow.recovery_batch_id !== recoveryBatchId
@@ -1936,9 +2045,15 @@ export class WorkspaceSyncDurabilityStore {
               AND (
                 (domain = 'task-attachment-links' AND mutation_kind = 'replace')
                 OR (domain = 'task' AND mutation_kind = 'create')
+                OR (domain = 'workstream' AND mutation_kind IN ('create', 'metadata-update'))
+                OR (domain = 'initiative' AND mutation_kind IN ('create', 'metadata-update'))
               )
               AND status IN ('pending', 'in_flight')
-              AND last_error_code = 'TASK_ATTACHMENT_ASSET_NOT_READY'
+              AND last_error_code IN (
+                'TASK_ATTACHMENT_ASSET_NOT_READY',
+                'WORKSTREAM_ATTACHMENT_NOT_READY',
+                'INITIATIVE_ATTACHMENT_NOT_READY'
+              )
             ORDER BY enqueue_sequence
         `).all(tenantId, workspaceId, WORKSPACE_SYNC_CONTRACT_VERSION);
         const assetIds = new Set();
@@ -1952,9 +2067,13 @@ export class WorkspaceSyncDurabilityStore {
             }
             if (!payload || typeof payload !== 'object' || Array.isArray(payload))
                 continue;
-            const links = String(row.domain || '') === 'task'
+            const domain = String(row.domain || '');
+            const links = domain === 'task'
                 ? payload.attachmentLinks
-                : payload.links;
+                : domain === 'task-attachment-links'
+                    ? payload.links
+                    : payload.attachments
+                        ?? payload.patch?.attachments;
             if (!Array.isArray(links))
                 continue;
             for (const link of links) {
@@ -2643,7 +2762,20 @@ export class WorkspaceSyncDurabilityStore {
                 for (const target of targets) {
                     insertTarget.run(ids[0], ids[1], ids[2], ids[3], target.domain, target.entityId, target.mutationKind, target.baseEntityRevision, target.baseLifecycleRevision, target.ownsTaskMetadata ? 1 : 0, target.ownsTaskLifecycle ? 1 : 0, target.ownsTaskAssignee ? 1 : 0, now);
                 }
-                return { enqueued: true, mutationResult: input.applyLocalMutation() };
+                const mutationResult = input.applyLocalMutation();
+                if (input.buildCanonicalIntent) {
+                    const canonicalIntentJson = canonicalWorkspaceSyncJson(input.buildCanonicalIntent(mutationResult));
+                    const updated = this.db.prepare(`
+                        UPDATE workspace_sync_outbox
+                        SET canonical_intent_json = ?, updated_at = ?
+                        WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
+                          AND status = 'pending'
+                    `).run(canonicalIntentJson, now, ...ids);
+                    if (Number(updated.changes || 0) !== 1) {
+                        throw new Error('Workspace sync canonical intent changed before it was persisted.');
+                    }
+                }
+                return { enqueued: true, mutationResult };
             }
             const existing = this.db.prepare(`
                 SELECT contract_version, dispatch_class, domain, entity_id, mutation_kind,
@@ -3268,9 +3400,9 @@ export class WorkspaceSyncDurabilityStore {
     // Workstream/initiative attachment-only metadata patches are Partial<>
     // merges, not full snapshots. The cloud accepts those patches against its
     // current revision, so this bounded retry can preserve unrelated concurrent
-    // metadata. Other metadata patches remain exact-revision operations: this
-    // selector may retry one once, but the cloud will reject it again rather
-    // than allowing a stale title or structural edit to overwrite newer state.
+    // metadata. It also covers an idempotent acknowledgement whose revision was
+    // advanced by the prerequisite V2 content push before local installation.
+    // Other metadata patches remain exact-revision operations and are excluded.
     requeueBoundedWorkstreamMetadataRevisionConflicts(input) {
         const tenantId = requireText(input.tenantId, 'Tenant id');
         const workspaceId = requireText(input.workspaceId, 'Workspace id');
@@ -3285,9 +3417,19 @@ export class WorkspaceSyncDurabilityStore {
                 updated_at = ?
             WHERE tenant_id = ? AND workspace_id = ? AND status = 'blocked'
               AND domain = 'workstream' AND mutation_kind = 'metadata-update'
-              AND attempt_count = 1
               AND workstream_metadata_revision_rebase_count < 1
-              AND last_error_code = 'WORKSPACE_SYNC_REVISION_CONFLICT'
+              AND (
+                  (attempt_count = 1 AND last_error_code = 'WORKSPACE_SYNC_REVISION_CONFLICT')
+                  OR (
+                      last_error_code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID'
+                      AND last_error_message = 'Authoritative workstream revisions do not advance the captured bases exactly once.'
+                      AND json_type(payload_json, '$.patch.attachments') = 'array'
+                      AND NOT EXISTS (
+                          SELECT 1 FROM json_each(payload_json, '$.patch')
+                          WHERE key <> 'attachments'
+                      )
+                  )
+              )
         `).run(now, now, tenantId, workspaceId);
         return Number(result.changes || 0);
     }
@@ -3305,9 +3447,19 @@ export class WorkspaceSyncDurabilityStore {
                 updated_at = ?
             WHERE tenant_id = ? AND workspace_id = ? AND status = 'blocked'
               AND domain = 'initiative' AND mutation_kind = 'metadata-update'
-              AND attempt_count = 1
               AND initiative_metadata_revision_rebase_count < 1
-              AND last_error_code = 'WORKSPACE_SYNC_REVISION_CONFLICT'
+              AND (
+                  (attempt_count = 1 AND last_error_code = 'WORKSPACE_SYNC_REVISION_CONFLICT')
+                  OR (
+                      last_error_code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID'
+                      AND last_error_message = 'Authoritative initiative revisions do not advance the captured bases exactly once.'
+                      AND json_type(payload_json, '$.patch.attachments') = 'array'
+                      AND NOT EXISTS (
+                          SELECT 1 FROM json_each(payload_json, '$.patch')
+                          WHERE key <> 'attachments'
+                      )
+                  )
+              )
         `).run(now, now, tenantId, workspaceId);
         return Number(result.changes || 0);
     }
@@ -3753,7 +3905,7 @@ export class WorkspaceSyncDurabilityStore {
                            mutation_kind, owns_task_metadata, owns_task_lifecycle, owns_task_assignee,
                            CAST(base_entity_revision AS TEXT) AS base_entity_revision,
                            CAST(base_lifecycle_revision AS TEXT) AS base_lifecycle_revision,
-                           payload_json, payload_fingerprint, status, attempt_count,
+                           payload_json, payload_fingerprint, canonical_intent_json, status, attempt_count,
                            initial_not_found_attempt_count,
                            CAST(enqueue_sequence AS TEXT) AS enqueue_sequence,
                            rebase_before_first_attempt,
@@ -4526,6 +4678,9 @@ export class WorkspaceSyncDurabilityStore {
             workflowDependencyCoalesced: true,
         };
     }
+    lockWorkspaceSequenceForMutation(input) {
+        this.allocateSequenceRange(requireText(input.tenantId, 'Tenant id'), requireText(input.workspaceId, 'Workspace id'), requireIsoTimestamp(input.now, 'Lock time'), 0);
+    }
     allocateSequenceRange(tenantId, workspaceId, now, count) {
         const row = this.db.prepare(`
             INSERT INTO workspace_sync_sequences (tenant_id, workspace_id, last_sequence, updated_at)
@@ -4581,6 +4736,9 @@ export class WorkspaceSyncDurabilityStore {
             baseLifecycleRevision: normalizeSequence(row.base_lifecycle_revision),
             payloadJson: requireText(row.payload_json, 'Payload'),
             payloadFingerprint: requireText(row.payload_fingerprint, 'Payload fingerprint'),
+            canonicalIntentJson: row.canonical_intent_json == null
+                ? null
+                : requireText(row.canonical_intent_json, 'Canonical intent'),
             status: requireText(row.status, 'Outbox status'),
             attemptCount: Number(row.attempt_count || 0),
             initialNotFoundAttemptCount: Number(row.initial_not_found_attempt_count || 0),

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

@@ -2,15 +2,15 @@ import type { AttachmentItem, TaskEvent, TaskEventDetails, TaskItem } from '../.
 import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js';
 import { serializeTaskActivityForSync, type WorkspaceSyncActivityRevision } from './taskActivityJournal.js';
 import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
-import { type WorkspaceSyncV3TaskAttachmentLink, type WorkspaceSyncV3TaskAttachmentLinksPayload } from './workspaceSyncV3NestedTaskCodecs.js';
+import { type WorkspaceSyncV3TaskAttachmentLink, type WorkspaceSyncV3TaskAttachmentLinksV2Payload } from './workspaceSyncV3NestedTaskCodecs.js';
 export declare class DurableTaskAttachmentLinksMutationError extends Error {
-    readonly code: 'TASK_NOT_FOUND' | 'TASK_ARCHIVED_READ_ONLY' | 'TASK_ATTACHMENT_LINKS_INVALID' | 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_ATTACHMENT_LINKS_DEPENDENCY_PENDING' | 'TASK_ATTACHMENT_ASSET_NOT_READY';
+    readonly code: 'TASK_NOT_FOUND' | 'TASK_ARCHIVED_READ_ONLY' | 'TASK_ATTACHMENT_LINKS_INVALID' | 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_ATTACHMENT_LINKS_DEPENDENCY_PENDING' | 'TASK_ATTACHMENT_ASSET_NOT_READY' | 'TASK_DETAIL_REVISION_CONFLICT';
     readonly statusCode: number;
     readonly details?: Record<string, unknown> | undefined;
     readonly retryable?: boolean | undefined;
     readonly retryAfterAt?: string | undefined;
     readonly retryHint?: string | undefined;
-    constructor(message: string, code: 'TASK_NOT_FOUND' | 'TASK_ARCHIVED_READ_ONLY' | 'TASK_ATTACHMENT_LINKS_INVALID' | 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_ATTACHMENT_LINKS_DEPENDENCY_PENDING' | 'TASK_ATTACHMENT_ASSET_NOT_READY', statusCode: number, details?: Record<string, unknown> | undefined, retryable?: boolean | undefined, retryAfterAt?: string | undefined, retryHint?: string | undefined);
+    constructor(message: string, code: 'TASK_NOT_FOUND' | 'TASK_ARCHIVED_READ_ONLY' | 'TASK_ATTACHMENT_LINKS_INVALID' | 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_ATTACHMENT_LINKS_DEPENDENCY_PENDING' | 'TASK_ATTACHMENT_ASSET_NOT_READY' | 'TASK_DETAIL_REVISION_CONFLICT', statusCode: number, details?: Record<string, unknown> | undefined, retryable?: boolean | undefined, retryAfterAt?: string | undefined, retryHint?: string | undefined);
 }
 export type DurableTaskAttachmentLinksResponse = {
     success: true;
@@ -37,7 +37,7 @@ export type DurableTaskAttachmentLinksResponse = {
             sequence: string;
             entityRevision: string;
             lifecycleRevision: string;
-            payload: WorkspaceSyncV3TaskAttachmentLinksPayload;
+            payload: WorkspaceSyncV3TaskAttachmentLinksV2Payload;
         };
     };
     activity: ReturnType<typeof serializeTaskActivityForSync>;
@@ -99,6 +99,7 @@ export declare function runDurableTaskAttachmentLinksReplace(input: {
     operationId: string;
     taskId: string;
     links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+    cardCoverAssetId?: string | null;
     baseEntityRevision: string | number;
     baseLifecycleRevision: string | number;
     now: string;
@@ -107,5 +108,7 @@ export declare function runDurableTaskAttachmentLinksReplace(input: {
     actorRef: string;
     resolveActorRef?: () => string;
     originActorRef?: string;
+    expectedDetailRevision?: string;
+    assertPrecondition?: () => void;
     onPostCommitError?: (error: unknown) => void;
 }): DurableTaskAttachmentLinksMutationResult;