@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/sync/v3/taskMetadataMutationService.js

@@ -35,6 +35,9 @@ export function runDurableTaskMetadataUpdate(input) {
             ...(input.activityAction && input.activityAction !== 'task-updated'
                 ? { activityAction: input.activityAction }
                 : {}),
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
         },
     });
     const activityEventId = buildTaskMetadataActivityEventId({
@@ -112,6 +115,7 @@ export function runDurableTaskMetadataUpdate(input) {
                 })),
             }],
         applyMutation: () => {
+            input.assertPrecondition?.();
             const actorRef = resolveDeferredMutationActorRef(input);
             if (!carriers)
                 return applyTaskMetadataUpdateForDurableSync({

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

@@ -2,7 +2,7 @@ import type { TaskEvent } from '../../core/Taskforce.js';
 import type { TaskRestoreDestination } from '../../shared/taskRestoreDestination.js';
 import { type DurableTaskRestoreCore } from '../../core/TaskDurableRestoreMutationService.js';
 import { serializeTaskForSync } from '../taskSyncPayload.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 DurableTaskRestoreServiceCore extends DurableTaskRestoreCore {
@@ -57,7 +57,7 @@ export type DurableTaskRestoreResponse = {
         sequence: string;
         entityRevision: string;
         lifecycleRevision: string;
-        payload: ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksPayload>;
+        payload: ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload>;
     };
     activity: TaskEvent;
     activityRevision: WorkspaceSyncActivityRevision;

package/dist/sync/v3/taskRestoreMutationService.js

@@ -1,7 +1,7 @@
 import { applyTaskRestoreForDurableSync, } from '../../core/TaskDurableRestoreMutationService.js';
 import { serializeTaskForSync } from '../taskSyncPayload.js';
 import { buildTaskLifecycleActivityEventId } from './taskLifecycleActivityIdentity.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { asWorkspaceSyncActivityRevision, buildTaskActivityJournalEntry, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION, } from './syncDurabilityStore.js';
 export function runDurableTaskRestore(input) {
@@ -90,13 +90,15 @@ export function runDurableTaskRestore(input) {
                 domain: 'task-attachment-links', entityId: input.taskId, mutationKind: 'replace', revisionKind: 'metadata',
                 baseEntityRevision: 0, baseLifecycleRevision: 0,
                 baseRevisionPolicy: 'current',
-                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 })],
         applyMutation: () => applyTaskRestoreForDurableSync({
@@ -151,9 +153,10 @@ export function runDurableTaskRestore(input) {
                     domain: 'task-attachment-links', entityId: task.id, mutationKind: 'replace',
                     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: readActivity(),

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

@@ -1,4 +1,4 @@
-import type { EntityEvent, TaskEvent } from '../../core/Taskforce.js';
+import type { Comment, EntityEvent, TaskEvent } from '../../core/Taskforce.js';
 import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
 import type { TaskActor } from '../../types.js';
 import { type DurableTaskStatusMutationCore } from '../../core/TaskDurableStatusMutationService.js';
@@ -6,6 +6,7 @@ import { serializeTaskForSync } from '../taskSyncPayload.js';
 import type { WorkflowAssignmentSyncRecord } from '../../storage/workflowStore.js';
 import { type WorkspaceSyncActivityRevision } from './taskActivityJournal.js';
 import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+import { type WorkspaceSyncV3TaskCommentsPayload } from './workspaceSyncV3NestedTaskCodecs.js';
 export interface DurableTaskStatusServiceCore extends DurableTaskStatusMutationCore {
     notifyDurableTaskLifecycleCommitted(workspaceId: string, taskId: string): void;
     getTaskEventForSync(input: {
@@ -19,6 +20,14 @@ export interface DurableTaskStatusServiceCore extends DurableTaskStatusMutationC
     }): EntityEvent | null;
     listAssignableActors(workspaceId: string): TaskActor[];
     getDatabaseAdapter(): DatabaseAdapter;
+    addTaskCommentEventForDurableSync(event: {
+        taskId: string;
+        workspaceId: string;
+        actor: string;
+        eventId: string;
+        createdAt: string;
+        comment: Comment;
+    }): void;
 }
 export type DurableTaskStatusResponse = {
     success: true;
@@ -45,7 +54,25 @@ export type DurableTaskStatusResponse = {
     dependentActivities?: EntityEvent[];
     dependentActivityRevisions?: WorkspaceSyncActivityRevision[];
     workflowAssignment?: WorkflowAssignmentSyncRecord;
+    reviewHandoff?: {
+        comments: {
+            domain: 'task-comments';
+            entityId: string;
+            mutationKind: 'append';
+            sequence: string;
+            entityRevision: string;
+            lifecycleRevision: string;
+            payload: WorkspaceSyncV3TaskCommentsPayload;
+        };
+        activity: TaskEvent;
+        activityRevision: WorkspaceSyncActivityRevision;
+    };
 };
+export declare class WorkflowRuntimeActivationFencedError extends Error {
+    readonly code = "WORKFLOW_RUNTIME_MUTATIONS_FENCED";
+    readonly statusCode = 503;
+    constructor();
+}
 export declare function runDurableTaskStatusMutation(input: {
     store: WorkspaceSyncDurabilityStore;
     core: DurableTaskStatusServiceCore;
@@ -64,6 +91,9 @@ export declare function runDurableTaskStatusMutation(input: {
     resolveActorRef?: () => string;
     originActorRef?: string;
     includeWorkflowRuntimeJournal?: boolean;
+    rejectWorkflowRuntimeActivation?: boolean;
+    expectedDetailRevision?: string;
+    assertPrecondition?: () => void;
     onPostCommitError?: (error: unknown) => void;
 }): {
     state: 'in_progress';

package/dist/sync/v3/taskStatusMutationService.js

@@ -8,7 +8,27 @@ import { asWorkspaceSyncActivityRevision, buildEntityActivityJournalEntry, build
 import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION, } from './syncDurabilityStore.js';
 import { resolveDeferredMutationActorRef } from './workspaceSyncV3OriginActor.js';
 import { buildWorkflowRuntimeEventId } from './workflowRuntimeOperationIdentity.js';
+import { buildTaskCommentActivityEventId } from './taskCommentActivityIdentity.js';
+import { serializeWorkspaceSyncV3TaskCommentAppendPayload, serializeWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { fingerprintWorkflowRuntimePayload, serializeWorkflowExecutionEventSyncPayload, serializeWorkflowExecutionRootSyncPayload, serializeWorkflowPublishedDefinitionSyncPayload, } from './workflowRuntimeSync.js';
+export class WorkflowRuntimeActivationFencedError extends Error {
+    code = 'WORKFLOW_RUNTIME_MUTATIONS_FENCED';
+    statusCode = 503;
+    constructor() {
+        super('Workflow execution changes are temporarily paused.');
+        this.name = 'WorkflowRuntimeActivationFencedError';
+    }
+}
+function nextTaskUpdatedAt(current, requested) {
+    const currentMs = Date.parse(current);
+    const requestedMs = Date.parse(requested);
+    if (!Number.isFinite(requestedMs) || new Date(requestedMs).toISOString() !== requested) {
+        throw new Error('Task status operation timestamp is invalid.');
+    }
+    return Number.isFinite(currentMs) && currentMs >= requestedMs
+        ? new Date(currentMs + 1).toISOString()
+        : requested;
+}
 export function runDurableTaskStatusMutation(input) {
     const operationPayload = normalizeTaskStatusOperationWithWorkflowAssignment(input.payload);
     const payload = validateDurableTaskStatusMutationPayload({
@@ -34,6 +54,9 @@ export function runDurableTaskStatusMutation(input) {
             baseLifecycleRevision: String(input.baseLifecycleRevision),
             payload: operationPayload,
             ...(input.originActorRef ? { originActorRef: input.originActorRef } : {}),
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
         },
     });
     const activityEventId = buildTaskLifecycleActivityEventId({
@@ -45,10 +68,24 @@ export function runDurableTaskStatusMutation(input) {
     });
     const membershipRemovedEventId = `${activityEventId}:workstream-removed`;
     const membershipAddedEventId = `${activityEventId}:workstream-added`;
+    const requestedReviewComment = operationPayload.reviewHandoff?.comment || null;
+    let reviewComment = null;
+    const reviewCommentActivityEventId = requestedReviewComment ? buildTaskCommentActivityEventId({
+        workspaceId: input.workspaceId,
+        clientId: input.clientId,
+        operationId: input.operationId,
+        taskId: input.taskId,
+        commentId: requestedReviewComment.id,
+    }) : null;
     const workflowStore = new WorkflowStore(input.core.getDatabaseAdapter(), input.tenantId);
     const workflowActivationService = new WorkflowTaskActivationService(workflowStore, (workspaceId) => input.core.listAssignableActors(workspaceId));
     const pendingAssignment = operationPayload.workflowAssignment
         || workflowStore.getAssignmentForTaskSync(input.workspaceId, input.taskId);
+    if (input.rejectWorkflowRuntimeActivation === true
+        && payload.status === 'in-progress'
+        && pendingAssignment?.execution.status === 'pending') {
+        throw new WorkflowRuntimeActivationFencedError();
+    }
     const workflowStartEventId = buildWorkflowRuntimeEventId({
         workspaceId: input.workspaceId,
         clientId: input.clientId,
@@ -92,6 +129,16 @@ export function runDurableTaskStatusMutation(input) {
             throw new Error('Task status activity was not committed.');
         return activity;
     };
+    const readReviewCommentActivity = () => {
+        const activity = input.core.getTaskEventForSync({
+            workspaceId: input.workspaceId,
+            taskId: input.taskId,
+            eventId: reviewCommentActivityEventId,
+        });
+        if (!activity)
+            throw new Error('Review handoff comment activity was not committed.');
+        return activity;
+    };
     const workflowAssignmentAfterMutation = () => {
         const assignment = workflowStore.getAssignmentForTaskSync(input.workspaceId, input.taskId);
         if (!assignment || assignment.execution.id !== pendingAssignment?.execution.id) {
@@ -155,7 +202,22 @@ export function runDurableTaskStatusMutation(input) {
                 reopenAssigneeOwned: (result) => result.assigneeOwned,
                 buildCanonicalFingerprint: (result) => (fingerprintWorkspaceSyncPayload(serializeTaskForSync(result.task))),
                 buildAuthoritativePayload: (result) => serializeTaskForSync(result.task),
-            }, {
+            }, ...(requestedReviewComment ? [{
+                    domain: 'task-comments', entityId: input.taskId, mutationKind: 'append', revisionKind: 'metadata',
+                    baseEntityRevision: 0, baseLifecycleRevision: 0, baseRevisionPolicy: 'current',
+                    buildCanonicalFingerprint: (result) => fingerprintWorkspaceSyncPayload(serializeWorkspaceSyncV3TaskCommentsPayload({
+                        taskId: result.task.id,
+                        comments: result.task.comments || [],
+                    })),
+                    buildAuthoritativePayload: (result) => (serializeWorkspaceSyncV3TaskCommentAppendPayload({
+                        taskId: result.task.id,
+                        comment: reviewComment,
+                        commentsAfterAppend: result.task.comments || [],
+                    })),
+                }, buildTaskActivityJournalEntry({
+                    eventId: reviewCommentActivityEventId,
+                    readEvent: readReviewCommentActivity,
+                })] : []), {
                 ...buildTaskActivityJournalEntry({ eventId: activityEventId, readEvent: readActivity }),
                 include: (result) => !result.noOp,
             }, {
@@ -184,6 +246,7 @@ export function runDurableTaskStatusMutation(input) {
                 })),
             }, ...workflowEntries],
         applyMutation: () => {
+            input.assertPrecondition?.();
             const currentTask = input.core.getTask(input.taskId, input.workspaceId);
             if (operationPayload.workflowAssignment) {
                 if (payload.status !== 'in-progress'
@@ -204,7 +267,7 @@ export function runDurableTaskStatusMutation(input) {
                 })
                 : null;
             const actorRef = resolveDeferredMutationActorRef(input);
-            const result = applyTaskStatusMutationForDurableSync({
+            let result = applyTaskStatusMutationForDurableSync({
                 core: input.core,
                 workspaceId: input.workspaceId,
                 taskId: input.taskId,
@@ -220,6 +283,42 @@ export function runDurableTaskStatusMutation(input) {
                 actorRef,
                 taskEventId: activityEventId,
             });
+            if (requestedReviewComment) {
+                const authoritativeReviewComment = {
+                    ...requestedReviewComment,
+                    author: actorRef,
+                    submittedAuthor: actorRef,
+                    timestamp: input.now,
+                };
+                reviewComment = authoritativeReviewComment;
+                const existingComments = serializeWorkspaceSyncV3TaskCommentsPayload({
+                    taskId: result.task.id,
+                    comments: result.task.comments || [],
+                }).comments;
+                const collision = existingComments.find((comment) => comment.id === authoritativeReviewComment.id);
+                if (collision) {
+                    throw new Error(`Review handoff comment identity conflict: ${authoritativeReviewComment.id}.`);
+                }
+                const updatedAt = nextTaskUpdatedAt(String(result.task.updatedAt || result.task.createdAt), input.now);
+                const updated = input.core.updateTask(result.task.id, { comments: [...existingComments, authoritativeReviewComment] }, input.workspaceId, {
+                    persistBackup: false,
+                    emitRealtime: false,
+                    skipTaskEvents: true,
+                    syncUpdatedAt: updatedAt,
+                    allowV3OwnedMetadataWrite: true,
+                });
+                if (!updated)
+                    throw new Error('Review handoff task disappeared during comment persistence.');
+                input.core.addTaskCommentEventForDurableSync({
+                    taskId: updated.id,
+                    workspaceId: input.workspaceId,
+                    actor: actorRef,
+                    eventId: reviewCommentActivityEventId,
+                    createdAt: String(updated.updatedAt),
+                    comment: authoritativeReviewComment,
+                });
+                result = { ...result, task: updated };
+            }
             if (activation) {
                 workflowActivationService.start({
                     workspaceId: input.workspaceId,
@@ -257,6 +356,9 @@ export function runDurableTaskStatusMutation(input) {
                     throw new Error('Dependent task status activity was not committed.');
                 return event;
             });
+            const reviewCommentsRevision = reviewComment ? revisions.find((revision) => (revision.domain === 'task-comments' && revision.entityId === input.taskId)) : null;
+            const reviewActivityRevisionValue = reviewComment ? revisions.find((revision) => (revision.domain === 'entity-event' && revision.entityId === reviewCommentActivityEventId)) : null;
+            const reviewActivity = reviewComment ? readReviewCommentActivity() : null;
             return {
                 success: true,
                 contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
@@ -281,6 +383,24 @@ export function runDurableTaskStatusMutation(input) {
                 activityRevision,
                 ...(dependentActivities.length > 0 ? { dependentActivities } : {}),
                 ...(dependentActivityRevisions.length > 0 ? { dependentActivityRevisions } : {}),
+                ...(reviewComment && reviewCommentsRevision && reviewActivityRevisionValue && reviewActivity ? {
+                    reviewHandoff: {
+                        comments: {
+                            domain: 'task-comments',
+                            entityId: result.task.id,
+                            mutationKind: 'append',
+                            sequence: reviewCommentsRevision.sequence,
+                            entityRevision: reviewCommentsRevision.entityRevision,
+                            lifecycleRevision: reviewCommentsRevision.lifecycleRevision,
+                            payload: serializeWorkspaceSyncV3TaskCommentsPayload({
+                                taskId: result.task.id,
+                                comments: result.task.comments || [],
+                            }),
+                        },
+                        activity: reviewActivity,
+                        activityRevision: asWorkspaceSyncActivityRevision(reviewActivityRevisionValue),
+                    },
+                } : {}),
                 ...(workflowStore.getAssignmentForTaskSync(input.workspaceId, result.task.id)
                     ? { workflowAssignment: workflowStore.getAssignmentForTaskSync(input.workspaceId, result.task.id) }
                     : {}),
@@ -288,7 +408,7 @@ export function runDurableTaskStatusMutation(input) {
         },
     });
     const response = JSON.parse(accepted.responseJson);
-    if (response.activity) {
+    if (response.activity || response.reviewHandoff) {
         try {
             input.core.notifyDurableTaskLifecycleCommitted(input.workspaceId, input.taskId);
         }

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

@@ -1,7 +1,13 @@
 import type { WorkflowAssignmentSyncRecord, WorkflowExecutionEventRecord, WorkflowExecutionRecord, WorkflowStepRecord, WorkflowTemplateRecord, WorkflowVersionRecord } from '../../storage/workflowStore.js';
+import type { Comment } from '../../core/Taskforce.js';
 import { type DurableTaskStatusMutationPayload } from '../../core/TaskDurableStatusMutationService.js';
+export type TaskStatusReviewHandoff = {
+    comment: Pick<Comment, 'id' | 'author' | 'submittedAuthor' | 'text'>;
+};
 export type TaskStatusOperationWithWorkflowAssignment = DurableTaskStatusMutationPayload & {
     workflowAssignment?: WorkflowAssignmentSyncRecord;
+    expectedDetailRevision?: string;
+    reviewHandoff?: TaskStatusReviewHandoff;
 };
 export declare class WorkflowAssignmentSyncError extends Error {
     readonly code = "WORKFLOW_ASSIGNMENT_SYNC_INVALID";

package/dist/sync/v3/workflowAssignmentSync.js

@@ -203,11 +203,41 @@ export function normalizeTaskStatusOperationWithWorkflowAssignment(raw) {
         }
         originActor = { kind: 'ai-profile', profileId };
     }
+    let reviewHandoff;
+    if (source.reviewHandoff !== undefined) {
+        if (status.status !== 'review') {
+            throw new WorkflowAssignmentSyncError('reviewHandoff is valid only when status is review.');
+        }
+        const handoff = object(source.reviewHandoff, 'reviewHandoff');
+        if (Object.keys(handoff).join(',') !== 'comment') {
+            throw new WorkflowAssignmentSyncError('reviewHandoff must contain exactly comment.');
+        }
+        const comment = object(handoff.comment, 'reviewHandoff.comment');
+        if (Object.keys(comment).sort().join(',') !== 'author,id,submittedAuthor,text') {
+            throw new WorkflowAssignmentSyncError('reviewHandoff.comment must contain exactly id, author, submittedAuthor, and text.');
+        }
+        const author = text(comment.author, 'reviewHandoff.comment.author');
+        const submittedAuthor = text(comment.submittedAuthor, 'reviewHandoff.comment.submittedAuthor');
+        const commentText = text(comment.text, 'reviewHandoff.comment.text');
+        if (author !== submittedAuthor) {
+            throw new WorkflowAssignmentSyncError('reviewHandoff comment authorship is invalid.');
+        }
+        reviewHandoff = { comment: {
+                id: text(comment.id, 'reviewHandoff.comment.id'),
+                author,
+                submittedAuthor,
+                text: commentText,
+            } };
+    }
     return {
         ...status,
         ...(source.workflowAssignment === undefined
             ? {}
             : { workflowAssignment: normalizeWorkflowAssignmentSyncRecord(source.workflowAssignment) }),
+        ...(reviewHandoff ? { reviewHandoff } : {}),
         ...(originActor ? { originActor } : {}),
+        ...(typeof source.expectedDetailRevision === 'string' && source.expectedDetailRevision.trim()
+            ? { expectedDetailRevision: source.expectedDetailRevision.trim() }
+            : {}),
     };
 }

package/dist/sync/v3/workspaceSyncJournalReader.js

@@ -31,7 +31,7 @@ export class WorkspaceSyncJournalReader {
             CAST(lifecycle_revision AS TEXT) AS lifecycle_revision, content_sha256,
             CAST(size_bytes AS TEXT) AS size_bytes, payload_json, occurred_at FROM workspace_sync_journal
             WHERE tenant_id = ? AND workspace_id = ? AND sequence > ? AND sequence <= ?
-            ORDER BY sequence ASC LIMIT ?`).all(input.tenantId, input.workspaceId, sequence(input.afterSequence), sequence(input.throughSequence), Math.max(1, Math.min(10_101, Math.floor(input.limit))));
+            ORDER BY workspace_sync_journal.sequence ASC LIMIT ?`).all(input.tenantId, input.workspaceId, sequence(input.afterSequence), sequence(input.throughSequence), Math.max(1, Math.min(10_101, Math.floor(input.limit))));
         return rows.map((row) => ({
             sequence: sequence(row.sequence), contractVersion: Number(row.contract_version), clientId: String(row.client_id || ''),
             operationId: String(row.operation_id || ''), domain: String(row.domain || ''),

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

@@ -0,0 +1,16 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+export declare const WORKSPACE_SYNC_OPERATION_RETENTION_DAYS = 90;
+export declare const WORKSPACE_SYNC_OPERATION_RETENTION_INTERVAL_MS: number;
+export declare const WORKSPACE_SYNC_OPERATION_RETENTION_BATCH_SIZE = 100;
+export declare const WORKSPACE_SYNC_OPERATION_RETENTION_WORKSPACE_LIMIT = 100;
+export interface WorkspaceSyncOperationRetentionResult {
+    deletedOutbox: number;
+    deletedResults: number;
+    remainingEligible: number;
+    workspacesProcessed: number;
+}
+export declare function pruneRetainedWorkspaceSyncOperations(input: {
+    db: DatabaseAdapter;
+    tenantId: string;
+    now?: Date;
+}): WorkspaceSyncOperationRetentionResult;

package/dist/sync/v3/workspaceSyncOperationRetentionService.js

@@ -0,0 +1,83 @@
+import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+export const WORKSPACE_SYNC_OPERATION_RETENTION_DAYS = 90;
+export const WORKSPACE_SYNC_OPERATION_RETENTION_INTERVAL_MS = 24 * 60 * 60_000;
+export const WORKSPACE_SYNC_OPERATION_RETENTION_BATCH_SIZE = 100;
+export const WORKSPACE_SYNC_OPERATION_RETENTION_WORKSPACE_LIMIT = 100;
+export function pruneRetainedWorkspaceSyncOperations(input) {
+    const now = input.now || new Date();
+    const cutoff = new Date(now.getTime() - WORKSPACE_SYNC_OPERATION_RETENTION_DAYS * 24 * 60 * 60_000).toISOString();
+    const workspaceRows = input.db.prepare(`
+        SELECT eligible.workspace_id
+        FROM (
+            SELECT candidate.workspace_id, candidate.updated_at AS terminal_at
+            FROM workspace_sync_outbox AS candidate
+            WHERE candidate.tenant_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
+              )
+            UNION ALL
+            SELECT workspace_id, updated_at AS terminal_at
+            FROM workspace_sync_operation_results
+            WHERE tenant_id = ? AND status = 'committed' AND updated_at < ?
+        ) AS eligible
+        GROUP BY eligible.workspace_id
+        ORDER BY MIN(eligible.terminal_at), eligible.workspace_id
+        LIMIT ?
+    `).all(input.tenantId, cutoff, input.tenantId, cutoff, WORKSPACE_SYNC_OPERATION_RETENTION_WORKSPACE_LIMIT);
+    const store = new WorkspaceSyncDurabilityStore(input.db);
+    let deletedOutbox = 0;
+    let deletedResults = 0;
+    for (const row of workspaceRows) {
+        const workspaceId = String(row.workspace_id || '').trim();
+        if (!workspaceId)
+            continue;
+        const outboxResult = store.pruneTerminalOutboxOperations({
+            tenantId: input.tenantId,
+            workspaceId,
+            terminalBefore: cutoff,
+            limit: WORKSPACE_SYNC_OPERATION_RETENTION_BATCH_SIZE,
+        });
+        deletedOutbox += outboxResult.deleted;
+        const result = store.pruneCommittedOperationResults({
+            tenantId: input.tenantId,
+            workspaceId,
+            terminalBefore: cutoff,
+            limit: WORKSPACE_SYNC_OPERATION_RETENTION_BATCH_SIZE,
+        });
+        deletedResults += result.deleted;
+    }
+    const remaining = input.db.prepare(`
+        SELECT (
+            SELECT COUNT(*)
+            FROM workspace_sync_outbox AS candidate
+            WHERE candidate.tenant_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
+              )
+        ) + (
+            SELECT COUNT(*)
+            FROM workspace_sync_operation_results
+            WHERE tenant_id = ? AND status = 'committed' AND updated_at < ?
+        ) AS count
+    `).get(input.tenantId, cutoff, input.tenantId, cutoff);
+    return {
+        deletedOutbox,
+        deletedResults,
+        remainingEligible: Number(remaining?.count || 0),
+        workspacesProcessed: workspaceRows.length,
+    };
+}

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

@@ -1,6 +1,6 @@
 import type { WorkspaceSyncIncomingTaskApplyModel } from '../syncApplyHandlers.js';
 import type { WorkspaceSyncChange } from '../workspaceSyncModel.js';
-export declare const WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS: readonly ["task/root-v1", "task-relationship/full-v1", "taxonomy/full-v1", "initiative/full-v1", "workstream/full-v1", "task-comments/full-v1", "task-checklist/full-v1", "task-attachment-links/full-v1", "entity-event/full-v1", "workstream-task-order/full-v1"];
+export declare const WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS: readonly ["task/root-v1", "task-relationship/full-v1", "taxonomy/full-v1", "initiative/full-v1", "workstream/full-v1", "task-comments/full-v1", "task-checklist/full-v1", "task-attachment-links/full-v1", "task-attachment-links/full-v2", "entity-event/full-v1", "workstream-task-order/full-v1"];
 export type WorkspaceSyncV2ProjectionExclusion = typeof WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS[number];
 export declare const WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS: readonly WorkspaceSyncV2ProjectionExclusion[];
 export declare function normalizeWorkspaceSyncV2ProjectionExclusions(values: Iterable<unknown> | null | undefined): WorkspaceSyncV2ProjectionExclusion[];

package/dist/sync/v3/workspaceSyncV2ProjectionExclusions.js

@@ -8,6 +8,7 @@ export const WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS = Object.freeze([
     'task-comments/full-v1',
     'task-checklist/full-v1',
     'task-attachment-links/full-v1',
+    'task-attachment-links/full-v2',
     'entity-event/full-v1',
     'workstream-task-order/full-v1',
 ]);
@@ -49,7 +50,9 @@ export function prepareWorkspaceSyncV2TaskCarriers(taskMutations, excludedProjec
         return taskMutations;
     const commentsOwned = excludedProjections.has('task-comments/full-v1');
     const checklistOwned = excludedProjections.has('task-checklist/full-v1');
-    const attachmentsOwned = excludedProjections.has('task-attachment-links/full-v1');
+    const cardCoverOwned = excludedProjections.has('task-attachment-links/full-v2');
+    const attachmentsOwned = excludedProjections.has('task-attachment-links/full-v1')
+        || cardCoverOwned;
     return {
         upserts: taskMutations.upserts.map(({ archived, task }) => {
             const existing = readExistingTask?.(String(task.id || '').trim());
@@ -63,6 +66,7 @@ export function prepareWorkspaceSyncV2TaskCarriers(taskMutations, excludedProjec
                     ...(commentsOwned ? { comments: existing.comments || [] } : {}),
                     ...(checklistOwned ? { checklistItems: existing.checklistItems || [] } : {}),
                     ...(attachmentsOwned ? { attachments: existing.attachments || [] } : {}),
+                    ...(cardCoverOwned ? { cardCoverAssetId: existing.cardCoverAssetId ?? null } : {}),
                 },
             };
         }),
@@ -100,7 +104,10 @@ export function partitionWorkspaceSyncV2LegacyChanges(changes, excludedProjectio
         if (change.op === 'upsert') {
             const commentsOwned = excludedProjections.has('task-comments/full-v1');
             const checklistOwned = excludedProjections.has('task-checklist/full-v1');
-            const attachmentsOwned = excludedProjections.has('task-attachment-links/full-v1');
+            const attachmentProjection = excludedProjections.has('task-attachment-links/full-v2')
+                ? 'task-attachment-links/full-v2'
+                : 'task-attachment-links/full-v1';
+            const attachmentsOwned = excludedProjections.has(attachmentProjection);
             if (excludedProjections.has('task/root-v1'))
                 suppress('task/root-v1');
             if (commentsOwned || checklistOwned || attachmentsOwned) {
@@ -115,7 +122,10 @@ export function partitionWorkspaceSyncV2LegacyChanges(changes, excludedProjectio
                 }
                 if (attachmentsOwned) {
                     delete task.attachments;
-                    suppress('task-attachment-links/full-v1');
+                    if (attachmentProjection === 'task-attachment-links/full-v2') {
+                        delete task.cardCoverAssetId;
+                    }
+                    suppress(attachmentProjection);
                 }
                 accepted.push({ ...change, task });
                 continue;

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

@@ -15,10 +15,13 @@ export interface WorkspaceSyncV3AttachmentApplyObligation {
     createdAt: string;
     updatedAt: string;
     nextAttemptAt: string;
+    terminalAt: string | null;
+    terminalReason: string | null;
     resolvedAt: string | null;
 }
 export interface WorkspaceSyncV3AttachmentApplyObligationSummary {
     open: number;
+    terminal: number;
     due: number;
     oldestOpenCreatedAt: string | null;
     nextAttemptAt: string | null;
@@ -70,6 +73,14 @@ export declare class WorkspaceSyncV3AttachmentApplyObligationStore {
         taskId: string;
         now: string;
     }): void;
+    markTerminalUnavailable(input: {
+        tenantId: string;
+        workspaceId: string;
+        taskId: string;
+        canonicalFingerprint: string;
+        reason: string;
+        now: string;
+    }): void;
     recordAttemptFailure(input: {
         tenantId: string;
         workspaceId: string;