@taskforcehq/taskforce 0.3.329 → 0.3.332

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;
@@ -26,6 +27,7 @@ const TASK_AGGREGATE_SUCCESSOR_MUTATIONS = new Map([
 const TASK_ROOT_SUCCESSOR_MUTATIONS = new Set([
     'metadata-update', 'set-status', 'archive', 'unarchive', 'complete', 'reopen',
 ]);
+const TASK_TERMINAL_SUCCESSOR_MUTATIONS = new Set(['delete']);
 const TASK_CREATE_RECOVERY_ERROR_CODES = new Set([
     'TASK_CREATE_ID_CONFLICT',
     'WORKSPACE_SYNC_REVISION_CONFLICT',
@@ -794,12 +796,137 @@ export class WorkspaceSyncDurabilityStore {
                    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
+                   rebase_before_first_attempt, lease_owner, lease_expires_at,
+                   last_error_code
             FROM workspace_sync_outbox
             WHERE tenant_id = ? AND workspace_id = ? AND client_id = ? AND operation_id = ?
         `).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,
@@ -1218,6 +1345,17 @@ export class WorkspaceSyncDurabilityStore {
                     }
                 }
             }
+            else if (input.replayPolicy === 'authoritative-workflow-runtime') {
+                if (selected.length !== 1) {
+                    throw new Error('Workflow runtime recovery has intersecting intent that requires semantic history reconciliation.');
+                }
+                const candidate = selected[0];
+                if (candidate.domain !== 'workflow-execution'
+                    || candidate.mutation_kind !== 'complete-step'
+                    || candidate.last_error_code !== 'WORKFLOW_RUNTIME_SEMANTIC_REPLAY_REQUIRED') {
+                    throw new Error('Workflow runtime recovery requires an exact authoritative semantic replay conflict.');
+                }
+            }
             this.db.prepare(`
                 INSERT INTO workspace_sync_outbox_recoveries (
                     tenant_id, workspace_id, recovery_batch_id,
@@ -1486,6 +1624,11 @@ export class WorkspaceSyncDurabilityStore {
                 }
             }
             const sources = recoverySources.filter((source) => {
+                if (source.domain === 'workflow-execution'
+                    && source.mutation_kind === 'complete-step'
+                    && source.last_error_code === 'WORKFLOW_RUNTIME_SEMANTIC_REPLAY_REQUIRED') {
+                    return false;
+                }
                 if (source.domain === 'task-comments' && source.mutation_kind === 'append') {
                     return !this.isTaskCommentAppendRecoveryIntentSatisfied(tenantId, workspaceId, source);
                 }
@@ -2457,9 +2600,21 @@ 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 queueableTaskDelete = domain === 'task'
+            && TASK_TERMINAL_SUCCESSOR_MUTATIONS.has(mutationKind)
+            && additionalTargets.length === 0
+            && ownsTaskMetadata
+            && ownsTaskLifecycle
+            && !ownsTaskAssignee;
         const queueableTaskAggregate = Boolean(TASK_AGGREGATE_SUCCESSOR_MUTATIONS.get(domain)?.has(mutationKind))
             && ((domain === 'task-comments' && mutationKind === 'reconcile' && additionalTargets.length === 0)
                 || (additionalTargets.length === 1
@@ -2470,7 +2625,8 @@ export class WorkspaceSyncDurabilityStore {
                     && !taskAggregateRootTarget.ownsTaskLifecycle
                     && !taskAggregateRootTarget.ownsTaskAssignee))
             && !ownsTaskMetadata && !ownsTaskLifecycle && !ownsTaskAssignee;
-        if (queuedTaskSuccessor && (input.revisionSource !== 'current' || (!queueableTaskRoot && !queueableTaskAggregate))) {
+        if (queuedTaskSuccessor && (input.revisionSource !== 'current'
+            || (!queueableTaskRoot && !queueableTaskDelete && !queueableTaskAggregate))) {
             throw new Error('Queued task successors require a recognized task root or aggregate operation.');
         }
         const additionalTargetKeys = new Set();
@@ -2682,11 +2838,13 @@ export class WorkspaceSyncDurabilityStore {
                                 const isTaskRoot = activeDomain === 'task'
                                     && row.entity_id === entityId
                                     && (TASK_ROOT_SUCCESSOR_MUTATIONS.has(activeMutationKind)
-                                        || (queueableTaskAggregate && activeMutationKind === 'create'))
+                                        || (activeMutationKind === 'create'
+                                            && Number(row.owns_task_metadata) === 0
+                                            && Number(row.owns_task_lifecycle) === 0
+                                            && Number(row.owns_task_assignee) === 0))
                                     && Number(row.target_count) === 1;
-                                return isTaskRoot
-                                    || isCompatibleTaskAggregate(row)
-                                    || isCompatibleWorkflowRuntimeAggregate(row);
+                                return isTaskRoot || (!queueableTaskDelete && (isCompatibleTaskAggregate(row)
+                                    || isCompatibleWorkflowRuntimeAggregate(row)));
                             });
                         const compatibleWorkflowRuntimeSuccessor = queuedWorkflowRuntimeSuccessor
                             && active.every((row) => (row.domain === 'workflow-execution'
@@ -2786,6 +2944,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
@@ -4715,9 +4899,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 {
@@ -4748,6 +4941,7 @@ export class WorkspaceSyncDurabilityStore {
             initiativeMetadataRevisionRebaseCount: Number(row.initiative_metadata_revision_rebase_count || 0),
             leaseOwner: row.lease_owner == null ? null : String(row.lease_owner),
             leaseExpiresAt: row.lease_expires_at == null ? null : String(row.lease_expires_at),
+            lastErrorCode: row.last_error_code == null ? null : String(row.last_error_code),
         };
     }
 }

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

@@ -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?: {
@@ -89,6 +99,7 @@ export declare function runDurableTaskChecklistReplace(input: {
     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,7 +99,7 @@ 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 }

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,7 @@ export declare function runDurableTaskStatusMutation(input: {
     resolveActorRef?: () => string;
     originActorRef?: string;
     includeWorkflowRuntimeJournal?: boolean;
+    rejectWorkflowRuntimeActivation?: boolean;
     expectedDetailRevision?: string;
     assertPrecondition?: () => void;
     onPostCommitError?: (error: unknown) => void;

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({
@@ -48,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,
@@ -95,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) {
@@ -158,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,
             }, {
@@ -208,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,
@@ -224,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,
@@ -261,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,
@@ -285,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) }
                     : {}),
@@ -292,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,8 +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";