@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/sync/v3/syncDurabilityStore.js

@@ -11,6 +11,7 @@ import { WorkspaceSyncJournalReader } from './workspaceSyncJournalReader.js';
 import { isLegacyEntityEventAdoptionIdentity, LEGACY_ENTITY_EVENT_ADOPTION_MAX_PAYLOAD_BYTES, } from './entityEventLegacyAdoptionContract.js';
 import { validateWorkspaceSyncV3EntityEventPayload } from './workspaceSyncV3NestedTaskCodecs.js';
 import { fingerprintWorkspaceSyncPayload } from './workspaceSyncPayloadFingerprint.js';
+import { assertDurableOperationFingerprint, assertDurableOperationIdentity, DurableOperationReplayIdentityConflictError, } from './durableOperationReplay.js';
 export { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
 export { fingerprintWorkspaceSyncPayload } from './workspaceSyncPayloadFingerprint.js';
 export const WORKSPACE_SYNC_CONTRACT_VERSION = 3;
@@ -791,7 +792,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
@@ -800,6 +801,130 @@ export class WorkspaceSyncDurabilityStore {
         `).get(...operationParams(identity));
         return row ? this.mapOutboxRow(row) : null;
     }
+    assertOutboxOperationIdentity(record, expected) {
+        assertDurableOperationIdentity({
+            operationId: record.operationId,
+            domain: record.domain,
+            entityId: record.entityId,
+            mutationKind: record.mutationKind,
+            payloadFingerprint: record.payloadFingerprint,
+        }, {
+            operationId: record.operationId,
+            domain: expected.domain,
+            entityId: expected.entityId,
+            mutationKind: expected.mutationKind,
+            payloadFingerprint: expected.payloadFingerprint || record.payloadFingerprint,
+        });
+    }
+    readOutboxOperationLookup(identity) {
+        const row = this.db.prepare(`
+            SELECT status, authoritative_response_json, created_at,
+                   mutation_kind, payload_fingerprint, domain, entity_id
+            FROM workspace_sync_outbox
+            WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
+            LIMIT 1
+        `).get(...operationParams(identity));
+        if (!row)
+            return null;
+        return {
+            ...identity,
+            status: requireText(row.status, 'Outbox status'),
+            createdAt: requireIsoTimestamp(row.created_at, 'Outbox creation time'),
+            domain: requireText(row.domain, 'Outbox domain'),
+            entityId: requireText(row.entity_id, 'Outbox entity id'),
+            mutationKind: requireText(row.mutation_kind, 'Outbox mutation kind'),
+            payloadFingerprint: requireText(row.payload_fingerprint, 'Outbox payload fingerprint'),
+            authoritativeResponseJson: row.authoritative_response_json == null
+                ? null
+                : requireText(row.authoritative_response_json, 'Outbox authoritative response'),
+        };
+    }
+    pruneTerminalOutboxOperations(input) {
+        const tenantId = requireText(input.tenantId, 'Tenant id');
+        const workspaceId = requireText(input.workspaceId, 'Workspace id');
+        const terminalBefore = requireIsoTimestamp(input.terminalBefore, 'Operation retention cutoff');
+        const limit = Math.max(1, Math.min(1_000, Math.floor(input.limit ?? 100)));
+        const eligibility = `
+            candidate.tenant_id = ? AND candidate.workspace_id = ?
+            AND candidate.status IN ('accepted', 'superseded')
+            AND candidate.updated_at < ?
+            AND NOT EXISTS (
+                SELECT 1
+                FROM workspace_sync_outbox AS replay
+                WHERE replay.tenant_id = candidate.tenant_id
+                  AND replay.workspace_id = candidate.workspace_id
+                  AND replay.replay_of_client_id = candidate.client_id
+                  AND replay.replay_of_operation_id = candidate.operation_id
+            )
+        `;
+        return this.db.transaction(() => {
+            const candidates = this.db.prepare(`
+                SELECT candidate.client_id, candidate.operation_id
+                FROM workspace_sync_outbox AS candidate
+                WHERE ${eligibility}
+                ORDER BY candidate.updated_at, candidate.client_id, candidate.operation_id
+                LIMIT ?
+            `).all(tenantId, workspaceId, terminalBefore, limit);
+            let deleted = 0;
+            for (const candidate of candidates) {
+                const clientId = requireText(candidate.client_id, 'Retention client id');
+                const operationId = requireText(candidate.operation_id, 'Retention operation id');
+                const result = this.db.prepare(`
+                    DELETE FROM workspace_sync_outbox AS candidate
+                    WHERE ${eligibility}
+                      AND candidate.client_id = ? AND candidate.operation_id = ?
+                `).run(tenantId, workspaceId, terminalBefore, clientId, operationId);
+                if (Number(result.changes || 0) !== 1)
+                    continue;
+                this.db.prepare(`
+                    DELETE FROM workspace_sync_outbox_targets
+                    WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
+                `).run(tenantId, workspaceId, clientId, operationId);
+                deleted += 1;
+            }
+            const remaining = this.db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM workspace_sync_outbox AS candidate
+                WHERE ${eligibility}
+            `).get(tenantId, workspaceId, terminalBefore);
+            return { deleted, remainingEligible: Number(remaining?.count || 0) };
+        })();
+    }
+    pruneCommittedOperationResults(input) {
+        const tenantId = requireText(input.tenantId, 'Tenant id');
+        const workspaceId = requireText(input.workspaceId, 'Workspace id');
+        const terminalBefore = requireIsoTimestamp(input.terminalBefore, 'Operation retention cutoff');
+        const limit = Math.max(1, Math.min(1_000, Math.floor(input.limit ?? 100)));
+        return this.db.transaction(() => {
+            const candidates = this.db.prepare(`
+                SELECT client_id, operation_id
+                FROM workspace_sync_operation_results
+                WHERE tenant_id = ? AND workspace_id = ?
+                  AND status = 'committed' AND updated_at < ?
+                ORDER BY updated_at, client_id, operation_id
+                LIMIT ?
+            `).all(tenantId, workspaceId, terminalBefore, limit);
+            let deleted = 0;
+            for (const candidate of candidates) {
+                const clientId = requireText(candidate.client_id, 'Retention client id');
+                const operationId = requireText(candidate.operation_id, 'Retention operation id');
+                const result = this.db.prepare(`
+                    DELETE FROM workspace_sync_operation_results
+                    WHERE tenant_id = ? AND workspace_id = ?
+                      AND client_id = ? AND operation_id = ?
+                      AND status = 'committed' AND updated_at < ?
+                `).run(tenantId, workspaceId, clientId, operationId, terminalBefore);
+                deleted += Number(result.changes || 0);
+            }
+            const remaining = this.db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM workspace_sync_operation_results
+                WHERE tenant_id = ? AND workspace_id = ?
+                  AND status = 'committed' AND updated_at < ?
+            `).get(tenantId, workspaceId, terminalBefore);
+            return { deleted, remainingEligible: Number(remaining?.count || 0) };
+        })();
+    }
     readV3DispatchSettlementEvidence(identity) {
         const row = this.db.prepare(`
             SELECT outbox.status, outbox.authoritative_response_json,
@@ -847,7 +972,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
@@ -1028,7 +1153,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
@@ -1396,7 +1521,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
@@ -1646,18 +1772,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'), 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, 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,
@@ -1667,7 +1793,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
@@ -2456,9 +2582,15 @@ export class WorkspaceSyncDurabilityStore {
             })()
             : null;
         const taskAggregateRootTarget = additionalTargets[0];
+        const queueableTaskReviewHandoff = domain === 'task'
+            && mutationKind === 'set-status'
+            && additionalTargets.length === 1
+            && taskAggregateRootTarget.domain === 'task-comments'
+            && taskAggregateRootTarget.entityId === entityId
+            && taskAggregateRootTarget.mutationKind === 'append';
         const queueableTaskRoot = domain === 'task'
             && TASK_ROOT_SUCCESSOR_MUTATIONS.has(mutationKind)
-            && additionalTargets.length === 0;
+            && (additionalTargets.length === 0 || queueableTaskReviewHandoff);
         const queueableTaskAggregate = Boolean(TASK_AGGREGATE_SUCCESSOR_MUTATIONS.get(domain)?.has(mutationKind))
             && ((domain === 'task-comments' && mutationKind === 'reconcile' && additionalTargets.length === 0)
                 || (additionalTargets.length === 1
@@ -2761,7 +2893,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,
@@ -2772,6 +2917,32 @@ export class WorkspaceSyncDurabilityStore {
                 FROM workspace_sync_outbox
                 WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
             `).get(...ids);
+            if (existing) {
+                try {
+                    const existingPayloadFingerprint = String(existing.payload_fingerprint || '');
+                    assertDurableOperationIdentity({
+                        operationId: ids[3],
+                        domain: String(existing.domain || ''),
+                        entityId: String(existing.entity_id || ''),
+                        mutationKind: String(existing.mutation_kind || ''),
+                        payloadFingerprint: existingPayloadFingerprint,
+                    }, {
+                        operationId: ids[3],
+                        domain,
+                        entityId,
+                        mutationKind,
+                        payloadFingerprint: existingPayloadFingerprint === coalescedWorkflowPayloadFingerprint
+                            ? coalescedWorkflowPayloadFingerprint
+                            : payloadFingerprint,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof DurableOperationReplayIdentityConflictError) {
+                        throw new WorkspaceSyncIdempotencyConflictError();
+                    }
+                    throw error;
+                }
+            }
             const matches = existing
                 && Number(existing.contract_version) === WORKSPACE_SYNC_CONTRACT_VERSION
                 && existing.dispatch_class === dispatchClass
@@ -3891,7 +4062,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,
@@ -4664,6 +4835,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)
@@ -4698,9 +4872,18 @@ export class WorkspaceSyncDurabilityStore {
     assertMatchingOperation(row, requestFingerprint) {
         if (!row)
             throw new Error('Workspace sync operation does not exist.');
-        if (Number(row.contract_version) !== WORKSPACE_SYNC_CONTRACT_VERSION || row.request_fingerprint !== requestFingerprint) {
+        if (Number(row.contract_version) !== WORKSPACE_SYNC_CONTRACT_VERSION) {
             throw new WorkspaceSyncIdempotencyConflictError();
         }
+        try {
+            assertDurableOperationFingerprint(String(row.request_fingerprint || ''), requestFingerprint);
+        }
+        catch (error) {
+            if (error instanceof DurableOperationReplayIdentityConflictError) {
+                throw new WorkspaceSyncIdempotencyConflictError();
+            }
+            throw error;
+        }
     }
     mapOutboxRow(row) {
         return {
@@ -4719,6 +4902,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>;
@@ -108,5 +108,7 @@ export declare function runDurableTaskAttachmentLinksReplace(input: {
     actorRef: string;
     resolveActorRef?: () => string;
     originActorRef?: string;
+    expectedDetailRevision?: string;
+    assertPrecondition?: () => void;
     onPostCommitError?: (error: unknown) => void;
 }): DurableTaskAttachmentLinksMutationResult;

package/dist/sync/v3/taskAttachmentLinksMutationService.js

@@ -3,7 +3,7 @@ import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js
 import { buildTaskAttachmentLinksActivityEventId } from './taskAttachmentLinksActivityIdentity.js';
 import { asWorkspaceSyncActivityRevision, buildTaskActivityJournalEntry, canonicalizeEntityActivityDetailsForSync, serializeTaskActivityForSync, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, runReservedWorkspaceSyncV3Operation, WORKSPACE_SYNC_CONTRACT_VERSION, } from './syncDurabilityStore.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { resolveDeferredMutationActorRef } from './workspaceSyncV3OriginActor.js';
 export class DurableTaskAttachmentLinksMutationError extends Error {
     code;
@@ -61,6 +61,9 @@ export function runDurableTaskAttachmentLinksReplace(input) {
                 ? { cardCoverAssetId: input.cardCoverAssetId }
                 : {}),
             ...(input.originActorRef ? { originActorRef: input.originActorRef } : {}),
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
         },
     });
     const activityEventId = buildTaskAttachmentLinksActivityEventId({
@@ -74,6 +77,16 @@ export function runDurableTaskAttachmentLinksReplace(input) {
             throw new Error('Durable task attachment-link activity was not persisted.');
         return activity;
     };
+    const readAttachmentPayload = () => {
+        const task = input.core.getTask(input.taskId, input.workspaceId);
+        if (!task)
+            throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+        return serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+            taskId: input.taskId,
+            links: input.core.listTaskAttachmentLinksForDurableSync(input.taskId, input.workspaceId),
+            cardCoverAssetId: task.cardCoverAssetId ?? null,
+        });
+    };
     const result = runReservedWorkspaceSyncV3Operation({
         store: input.store, identity, requestFingerprint,
         now: input.now, leaseExpiresAt: input.leaseExpiresAt, leaseOwner: input.leaseOwner,
@@ -101,16 +114,11 @@ export function runDurableTaskAttachmentLinksReplace(input) {
                     }, {
                         domain: 'task-attachment-links', entityId: input.taskId, mutationKind: 'replace', revisionKind: 'metadata',
                         baseEntityRevision: input.baseEntityRevision, baseLifecycleRevision: input.baseLifecycleRevision,
-                        buildCanonicalFingerprint: () => fingerprintWorkspaceSyncPayload(serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-                            taskId: input.taskId,
-                            links: input.core.listTaskAttachmentLinksForDurableSync(input.taskId, input.workspaceId),
-                        })),
-                        buildAuthoritativePayload: () => serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-                            taskId: input.taskId,
-                            links: input.core.listTaskAttachmentLinksForDurableSync(input.taskId, input.workspaceId),
-                        }),
+                        buildCanonicalFingerprint: () => fingerprintWorkspaceSyncPayload(readAttachmentPayload()),
+                        buildAuthoritativePayload: readAttachmentPayload,
                     }, buildTaskActivityJournalEntry({ eventId: activityEventId, readEvent: readActivity })],
                 applyMutation: () => {
+                    input.assertPrecondition?.();
                     const existing = input.core.getTask(input.taskId, input.workspaceId);
                     if (!existing)
                         throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
@@ -181,9 +189,10 @@ export function runDurableTaskAttachmentLinksReplace(input) {
                                 sequence: attachmentLinksRevision.sequence,
                                 entityRevision: attachmentLinksRevision.entityRevision,
                                 lifecycleRevision: attachmentLinksRevision.lifecycleRevision,
-                                payload: serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                                payload: serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
                                     taskId: task.id,
                                     links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                                    cardCoverAssetId: task.cardCoverAssetId ?? null,
                                 }),
                             },
                         },

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

@@ -4,13 +4,13 @@ import { serializeTaskActivityForSync, type WorkspaceSyncActivityRevision } from
 import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
 import { type WorkspaceSyncV3TaskChecklistPayload } from './workspaceSyncV3NestedTaskCodecs.js';
 export declare class DurableTaskChecklistMutationError extends Error {
-    readonly code: 'TASK_NOT_FOUND' | 'TASK_ARCHIVED_READ_ONLY' | 'TASK_CHECKLIST_INVALID' | 'TASK_CHECKLIST_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_CHECKLIST_DEPENDENCY_PENDING';
+    readonly code: 'TASK_NOT_FOUND' | 'TASK_ARCHIVED_READ_ONLY' | 'TASK_CHECKLIST_INVALID' | 'TASK_CHECKLIST_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_CHECKLIST_DEPENDENCY_PENDING' | '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_CHECKLIST_INVALID' | 'TASK_CHECKLIST_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_CHECKLIST_DEPENDENCY_PENDING', 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_CHECKLIST_INVALID' | 'TASK_CHECKLIST_IDENTITY_CONFLICT' | 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED' | 'TASK_CHECKLIST_DEPENDENCY_PENDING' | 'TASK_DETAIL_REVISION_CONFLICT', statusCode: number, details?: Record<string, unknown> | undefined, retryable?: boolean | undefined, retryAfterAt?: string | undefined, retryHint?: string | undefined);
 }
 export type DurableTaskChecklistResponse = {
     success: true;
@@ -52,6 +52,16 @@ export type DurableTaskChecklistMutationResult = {
     responseJson: string;
     response: DurableTaskChecklistResponse;
 };
+export type TaskChecklistItemUpdateIntent = {
+    kind: 'item-update';
+    itemId: string;
+    patch: {
+        text?: string;
+        done?: boolean;
+        order?: number;
+    };
+};
+export declare function validateTaskChecklistItemUpdateIntent(value: unknown): TaskChecklistItemUpdateIntent;
 export interface DurableTaskChecklistServiceCore {
     getTask(id: string, workspaceId?: string): TaskItem | null;
     updateTask(id: string, updates: Partial<TaskItem>, workspaceId?: string, options?: {
@@ -88,5 +98,8 @@ export declare function runDurableTaskChecklistReplace(input: {
     actorRef: string;
     resolveActorRef?: () => string;
     originActorRef?: string;
+    expectedDetailRevision?: string;
+    itemUpdateIntent?: TaskChecklistItemUpdateIntent;
+    assertPrecondition?: () => void;
     onPostCommitError?: (error: unknown) => void;
 }): DurableTaskChecklistMutationResult;

package/dist/sync/v3/taskChecklistMutationService.js

@@ -22,6 +22,37 @@ export class DurableTaskChecklistMutationError extends Error {
         this.name = 'DurableTaskChecklistMutationError';
     }
 }
+export function validateTaskChecklistItemUpdateIntent(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new DurableTaskChecklistMutationError('Task checklist item update intent is invalid.', 'TASK_CHECKLIST_INVALID', 400);
+    }
+    const source = value;
+    const patch = source.patch;
+    if (source.kind !== 'item-update'
+        || Object.keys(source).some((key) => key !== 'kind' && key !== 'itemId' && key !== 'patch')
+        || typeof source.itemId !== 'string' || !source.itemId.trim()
+        || !patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new DurableTaskChecklistMutationError('Task checklist item update intent is invalid.', 'TASK_CHECKLIST_INVALID', 400);
+    }
+    const patchSource = patch;
+    if (Object.keys(patchSource).some((key) => key !== 'text' && key !== 'done' && key !== 'order')
+        || Object.keys(patchSource).length === 0
+        || (patchSource.text !== undefined && (typeof patchSource.text !== 'string' || !patchSource.text.trim()))
+        || (patchSource.done !== undefined && typeof patchSource.done !== 'boolean')
+        || (patchSource.order !== undefined
+            && (!Number.isInteger(patchSource.order) || Number(patchSource.order) < 0))) {
+        throw new DurableTaskChecklistMutationError('Task checklist item update intent is invalid.', 'TASK_CHECKLIST_INVALID', 400);
+    }
+    return {
+        kind: 'item-update',
+        itemId: source.itemId.trim(),
+        patch: {
+            ...(patchSource.text !== undefined ? { text: patchSource.text.trim() } : {}),
+            ...(patchSource.done !== undefined ? { done: patchSource.done } : {}),
+            ...(patchSource.order !== undefined ? { order: Number(patchSource.order) } : {}),
+        },
+    };
+}
 function canonicalItems(taskId, items) {
     try {
         return serializeWorkspaceSyncV3TaskChecklistPayload({ taskId, items }).items;
@@ -46,6 +77,18 @@ function revision(revisions, domain) {
 }
 export function runDurableTaskChecklistReplace(input) {
     const items = canonicalItems(input.taskId, input.items);
+    const itemUpdateIntent = input.itemUpdateIntent
+        ? validateTaskChecklistItemUpdateIntent(input.itemUpdateIntent)
+        : undefined;
+    if (itemUpdateIntent) {
+        const target = items.find((item) => item.id === itemUpdateIntent.itemId);
+        if (!target
+            || (itemUpdateIntent.patch.text !== undefined && target.title !== itemUpdateIntent.patch.text)
+            || (itemUpdateIntent.patch.done !== undefined && target.isCompleted !== itemUpdateIntent.patch.done)
+            || (itemUpdateIntent.patch.order !== undefined && target.order !== itemUpdateIntent.patch.order)) {
+            throw new DurableTaskChecklistMutationError('Task checklist item update intent does not match the replacement aggregate.', 'TASK_CHECKLIST_INVALID', 400);
+        }
+    }
     const identity = {
         tenantId: input.tenantId, workspaceId: input.workspaceId, clientId: input.clientId, operationId: input.operationId,
     };
@@ -56,8 +99,11 @@ export function runDurableTaskChecklistReplace(input) {
             domain: 'task-checklist', entityId: input.taskId, mutationKind: 'replace',
             baseEntityRevision: String(input.baseEntityRevision),
             baseLifecycleRevision: String(input.baseLifecycleRevision),
-            items,
+            ...(itemUpdateIntent ? { itemUpdateIntent } : { items }),
             ...(input.originActorRef ? { originActorRef: input.originActorRef } : {}),
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
         },
     });
     const activityEventId = buildTaskChecklistActivityEventId({
@@ -100,6 +146,7 @@ export function runDurableTaskChecklistReplace(input) {
                 }),
             }, buildTaskActivityJournalEntry({ eventId: activityEventId, readEvent: readActivity })],
         applyMutation: () => {
+            input.assertPrecondition?.();
             const existing = input.core.getTask(input.taskId, input.workspaceId);
             if (!existing)
                 throw new DurableTaskChecklistMutationError('Task not found.', 'TASK_NOT_FOUND', 404);

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

@@ -2,7 +2,7 @@ import { type DurableTaskCreateMutationCore } from '../../core/TaskDurableCreate
 import type { EntityEvent, TaskEvent, TaskItem } from '../../core/Taskforce.js';
 import { serializeTaskForSync } from '../taskSyncPayload.js';
 import type { WorkspaceSyncTaskEventSnapshot } from '../workspaceSyncModel.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, type WorkspaceSyncV3TaskAttachmentLink } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, type WorkspaceSyncV3TaskAttachmentLink } from './workspaceSyncV3NestedTaskCodecs.js';
 import { type WorkspaceSyncActivityRevision } from './taskActivityJournal.js';
 import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
 export interface DurableTaskCreateServiceCore extends DurableTaskCreateMutationCore {
@@ -64,7 +64,7 @@ export type DurableTaskCreateResponse = {
         sequence: string;
         entityRevision: string;
         lifecycleRevision: string;
-        payload: ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksPayload>;
+        payload: ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload>;
     };
     activity: WorkspaceSyncTaskEventSnapshot;
     activityRevision: WorkspaceSyncActivityRevision;

package/dist/sync/v3/taskCreateMutationService.js

@@ -1,7 +1,7 @@
 import { applyTaskCreateForDurableSync, assertTaskCreateIdentityAvailable, validateDurableTaskCreateInput, } from '../../core/TaskDurableCreateMutationService.js';
 import { serializeTaskForSync } from '../taskSyncPayload.js';
 import { buildTaskCreateActivityEventId } from './taskCreateActivityIdentity.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { asWorkspaceSyncActivityRevision, buildEntityActivityJournalEntry, buildTaskActivityJournalEntry, serializeTaskActivityForSync, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION, } from './syncDurabilityStore.js';
 function requireZeroBaseRevision(value, label) {
@@ -151,13 +151,15 @@ export function runDurableTaskCreate(input) {
                 domain: 'task-attachment-links', entityId: taskId, mutationKind: 'replace', revisionKind: 'metadata',
                 baseEntityRevision: 0, baseLifecycleRevision: 0,
                 include: () => attachmentLinks.length > 0,
-                buildCanonicalFingerprint: (task) => fingerprintWorkspaceSyncPayload(serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                buildCanonicalFingerprint: (task) => fingerprintWorkspaceSyncPayload(serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
                     taskId: task.id,
                     links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                    cardCoverAssetId: task.cardCoverAssetId ?? null,
                 })),
-                buildAuthoritativePayload: (task) => serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                buildAuthoritativePayload: (task) => serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
                     taskId: task.id,
                     links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                    cardCoverAssetId: task.cardCoverAssetId ?? null,
                 }),
             }, buildTaskActivityJournalEntry({ eventId: activityEventId, readEvent: readActivity }), {
                 ...buildEntityActivityJournalEntry({
@@ -257,9 +259,10 @@ export function runDurableTaskCreate(input) {
                         sequence: attachmentRevision.sequence,
                         entityRevision: attachmentRevision.entityRevision,
                         lifecycleRevision: attachmentRevision.lifecycleRevision,
-                        payload: serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                        payload: serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
                             taskId: task.id,
                             links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                            cardCoverAssetId: task.cardCoverAssetId ?? null,
                         }),
                     } } : {}),
                 activity: serializeTaskActivityForSync(activity),

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

@@ -45,6 +45,7 @@ export interface DurableTaskMetadataServiceCore extends DurableTaskMetadataMutat
         workspaceId: string;
         eventId: string;
     }): EntityEvent | null;
+    assertTaskDetailRevisionForUpdate?(id: string, expectedDetailRevision: string, workspaceId?: string): void;
 }
 export declare function runDurableTaskMetadataUpdate(input: {
     store: WorkspaceSyncDurabilityStore;
@@ -67,5 +68,7 @@ export declare function runDurableTaskMetadataUpdate(input: {
     originActorRef?: string;
     saveSource?: 'manual' | 'autosave';
     activityAction?: 'task-updated' | 'task-schedule-changed';
+    expectedDetailRevision?: string;
+    assertPrecondition?: () => void;
     onPostCommitError?: (error: unknown) => void;
 }): DurableTaskMetadataMutationResult;