@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/sync/v3/localTaskStatusOutboxService.js

@@ -1,12 +1,15 @@
 import { applyTaskStatusMutationForDurableSync, validateDurableTaskStatusMutationPayload, } from '../../core/TaskDurableStatusMutationService.js';
 import { serializeTaskForSync } from '../taskSyncPayload.js';
 import { buildTaskLifecycleActivityEventId } from './taskLifecycleActivityIdentity.js';
+import { buildTaskCommentActivityEventId } from './taskCommentActivityIdentity.js';
 import { validateTaskActivityAuthoritativeRevision } from './taskActivityAuthoritativeRevision.js';
 import { serializeEntityActivityForSync, serializeTaskActivityForSync, WORKSPACE_SYNC_ENTITY_EVENT_APPEND, WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, } from './taskActivityJournal.js';
 import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
 import { WorkflowStore } from '../../storage/workflowStore.js';
 import { normalizeTaskStatusOperationWithWorkflowAssignment, normalizeWorkflowAssignmentSyncRecord, } from './workflowAssignmentSync.js';
 import { withOriginActorPayload } from './workspaceSyncV3OriginActor.js';
+import { mergeWorkspaceSyncV3TaskCommentsPayload, serializeWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
 export class LocalAuthoritativeTaskStatusError extends Error {
     code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
     constructor(message) {
@@ -19,6 +22,16 @@ function isCanonicalIso(value) {
         && Number.isFinite(Date.parse(value))
         && new Date(value).toISOString() === value;
 }
+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 LocalAuthoritativeTaskStatusError('Task status operation timestamp is invalid.');
+    }
+    return Number.isFinite(currentMs) && currentMs >= requestedMs
+        ? new Date(currentMs + 1).toISOString()
+        : requested;
+}
 function normalizeAssignee(value) {
     const normalized = typeof value === 'string' ? value.trim() : '';
     return normalized && normalized.toLowerCase() !== 'unassigned' ? normalized : null;
@@ -46,13 +59,27 @@ export function enqueueLocalTaskStatusMutation(input) {
     const taskId = String(input.taskId || '').trim();
     if (!taskId)
         throw new LocalAuthoritativeTaskStatusError('Task id is required.');
-    const statusPayload = validateDurableTaskStatusMutationPayload(input.payload);
+    const operationPayload = normalizeTaskStatusOperationWithWorkflowAssignment(input.payload);
+    const statusPayload = validateDurableTaskStatusMutationPayload({
+        status: operationPayload.status,
+        assigneeIntent: operationPayload.assigneeIntent,
+        canceledReason: operationPayload.canceledReason,
+        metadataPatch: operationPayload.metadataPatch,
+    });
     const assignment = statusPayload.status === 'in-progress'
         ? new WorkflowStore(input.core.getDatabaseAdapter(), input.core.getTenantId())
             .getAssignmentForTaskSync(input.identity.workspaceId, taskId)
         : null;
+    const reviewHandoff = operationPayload.reviewHandoff ? {
+        comment: {
+            ...operationPayload.reviewHandoff.comment,
+            author: input.actorRef,
+            submittedAuthor: input.actorRef,
+        },
+    } : null;
     const payload = {
-        ...statusPayload,
+        ...operationPayload,
+        ...(reviewHandoff ? { reviewHandoff } : {}),
         ...(assignment?.execution.status === 'pending' ? { workflowAssignment: assignment } : {}),
     };
     const activityEventId = buildTaskLifecycleActivityEventId({
@@ -62,6 +89,23 @@ export function enqueueLocalTaskStatusMutation(input) {
         taskId,
         mutationKind: 'set-status',
     });
+    const reviewComment = payload.reviewHandoff ? {
+        ...payload.reviewHandoff.comment,
+        timestamp: input.now,
+    } : null;
+    const reviewCommentActivityEventId = reviewComment ? buildTaskCommentActivityEventId({
+        workspaceId: input.identity.workspaceId,
+        clientId: input.identity.clientId,
+        operationId: input.identity.operationId,
+        taskId,
+        commentId: reviewComment.id,
+    }) : null;
+    const reviewCommentRevision = reviewComment ? input.store.readEntityRevisionCoordinates({
+        tenantId: input.identity.tenantId,
+        workspaceId: input.identity.workspaceId,
+        domain: 'task-comments',
+        entityId: taskId,
+    }) : null;
     const result = input.store.enqueueLocalOperation({
         identity: input.identity,
         domain: 'task',
@@ -74,6 +118,15 @@ export function enqueueLocalTaskStatusMutation(input) {
             taskLifecycle: true,
             taskAssignee: payload.assigneeIntent.kind !== 'preserve',
         },
+        ...(reviewComment ? {
+            additionalTargets: [{
+                    domain: 'task-comments',
+                    entityId: taskId,
+                    mutationKind: 'append',
+                    baseEntityRevision: reviewCommentRevision.entityRevision,
+                    baseLifecycleRevision: reviewCommentRevision.lifecycleRevision,
+                }],
+        } : {}),
         payload: withOriginActorPayload({
             ...payload,
             ...(input.expectedDetailRevision
@@ -92,7 +145,7 @@ export function enqueueLocalTaskStatusMutation(input) {
                 }
                 input.core.assertTaskDetailRevisionForUpdate(taskId, input.expectedDetailRevision, input.identity.workspaceId);
             }
-            return applyTaskStatusMutationForDurableSync({
+            let mutation = applyTaskStatusMutationForDurableSync({
                 core: input.core,
                 workspaceId: input.identity.workspaceId,
                 taskId,
@@ -104,6 +157,35 @@ export function enqueueLocalTaskStatusMutation(input) {
                 actorRef: input.actorRef,
                 taskEventId: activityEventId,
             });
+            if (reviewComment) {
+                const comments = serializeWorkspaceSyncV3TaskCommentsPayload({
+                    taskId,
+                    comments: mutation.task.comments || [],
+                }).comments;
+                if (comments.some((comment) => comment.id === reviewComment.id)) {
+                    throw new LocalAuthoritativeTaskStatusError(`Review handoff comment identity conflict: ${reviewComment.id}.`);
+                }
+                const updatedAt = nextTaskUpdatedAt(String(mutation.task.updatedAt || mutation.task.createdAt), input.now);
+                const updated = input.core.updateTask(taskId, { comments: [...comments, reviewComment] }, input.identity.workspaceId, {
+                    persistBackup: false,
+                    emitRealtime: false,
+                    skipTaskEvents: true,
+                    syncUpdatedAt: updatedAt,
+                    allowV3OwnedMetadataWrite: true,
+                });
+                if (!updated)
+                    throw new LocalAuthoritativeTaskStatusError('Review handoff task disappeared.');
+                input.core.addTaskCommentEventForDurableSync({
+                    taskId,
+                    workspaceId: input.identity.workspaceId,
+                    actor: input.actorRef,
+                    eventId: reviewCommentActivityEventId,
+                    createdAt: String(updated.updatedAt),
+                    comment: reviewComment,
+                });
+                mutation = { ...mutation, task: updated };
+            }
+            return mutation;
         },
         buildCanonicalIntent: (result) => ({
             metadataPatch: Object.fromEntries(Object.keys(payload.metadataPatch).map((key) => [
@@ -117,7 +199,7 @@ export function enqueueLocalTaskStatusMutation(input) {
     const mutationResult = result.mutationResult;
     if (!mutationResult)
         throw new LocalAuthoritativeTaskStatusError('Local task status mutation result is missing.');
-    if (!mutationResult.noOp) {
+    if (!mutationResult.noOp || reviewComment) {
         try {
             input.core.notifyDurableTaskLifecycleCommitted(input.identity.workspaceId, taskId);
         }
@@ -174,6 +256,66 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
         throw new LocalAuthoritativeTaskStatusError('Persisted task status payload fingerprint is invalid.');
     }
     const operationPayload = normalizeTaskStatusOperationWithWorkflowAssignment(persistedPayload);
+    const requestedReviewHandoff = operationPayload.reviewHandoff || null;
+    const reviewHandoff = response.reviewHandoff || null;
+    if (Boolean(requestedReviewHandoff) !== Boolean(reviewHandoff)) {
+        throw new LocalAuthoritativeTaskStatusError('Authoritative review handoff presence is invalid.');
+    }
+    let reviewCommentsPayload = null;
+    let reviewCommentActivity = null;
+    let reviewCommentTimestamp = null;
+    if (requestedReviewHandoff && reviewHandoff) {
+        reviewCommentsPayload = serializeWorkspaceSyncV3TaskCommentsPayload({
+            taskId: task.id,
+            comments: reviewHandoff.comments.payload.comments,
+        });
+        reviewCommentActivity = reviewHandoff.activity;
+        const requestedComment = requestedReviewHandoff.comment;
+        const authoritativeComment = reviewCommentsPayload.comments.find((comment) => comment.id === requestedComment.id);
+        reviewCommentTimestamp = authoritativeComment?.timestamp || null;
+        const expectedActivityId = buildTaskCommentActivityEventId({
+            workspaceId: input.identity.workspaceId,
+            clientId: input.identity.clientId,
+            operationId: input.identity.operationId,
+            taskId: task.id,
+            commentId: requestedComment.id,
+        });
+        const reviewCommentActivityDetails = reviewCommentActivity.details;
+        if (reviewHandoff.comments.domain !== 'task-comments'
+            || reviewHandoff.comments.entityId !== task.id
+            || reviewHandoff.comments.mutationKind !== 'append'
+            || !/^(0|[1-9]\d*)$/.test(reviewHandoff.comments.sequence)
+            || !/^(0|[1-9]\d*)$/.test(reviewHandoff.comments.entityRevision)
+            || reviewHandoff.comments.lifecycleRevision !== '0'
+            || reviewCommentsPayload.taskId !== task.id
+            || !authoritativeComment
+            || authoritativeComment.author !== requestedComment.author
+            || authoritativeComment.submittedAuthor !== requestedComment.submittedAuthor
+            || authoritativeComment.text !== requestedComment.text
+            || !isCanonicalIso(authoritativeComment.timestamp)
+            || reviewCommentActivity.id !== expectedActivityId
+            || reviewCommentActivity.workspaceId !== input.identity.workspaceId
+            || reviewCommentActivity.entityType !== 'task'
+            || reviewCommentActivity.entityId !== task.id
+            || reviewCommentActivity.taskId !== task.id
+            || reviewCommentActivity.action !== 'task-comment-added'
+            || !String(reviewCommentActivity.actor || '').trim()
+            || !['human', 'ai', 'system'].includes(reviewCommentActivity.actorType)
+            || reviewCommentActivity.createdAt !== task.updatedAt
+            || !reviewCommentActivityDetails
+            || Object.keys(reviewCommentActivityDetails).sort().join(',') !== 'commentId,preview,submittedAuthor'
+            || reviewCommentActivityDetails.commentId !== authoritativeComment.id
+            || reviewCommentActivityDetails.submittedAuthor !== authoritativeComment.submittedAuthor
+            || reviewCommentActivityDetails.preview !== authoritativeComment.text.slice(0, 160)
+            || reviewHandoff.activityRevision.domain !== 'entity-event'
+            || reviewHandoff.activityRevision.entityId !== expectedActivityId
+            || !/^(0|[1-9]\d*)$/.test(reviewHandoff.activityRevision.sequence)
+            || reviewHandoff.activityRevision.entityRevision !== '1'
+            || reviewHandoff.activityRevision.lifecycleRevision !== '0'
+            || canonicalWorkspaceSyncJson(reviewCommentsPayload) !== canonicalWorkspaceSyncJson(serializeWorkspaceSyncV3TaskCommentsPayload({ taskId: task.id, comments: task.comments || [] }))) {
+            throw new LocalAuthoritativeTaskStatusError('Authoritative review handoff is invalid.');
+        }
+    }
     const requestedWorkflowAssignment = operationPayload.workflowAssignment || null;
     const workflowIdentityMismatch = (expected, actual) => expected.template.id !== actual.template.id
         || expected.version.id !== actual.version.id
@@ -205,7 +347,11 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
     if (!validLifecycle || authoritative.metadataOwned !== expectsMetadataOwnership) {
         throw new LocalAuthoritativeTaskStatusError('Authoritative task status state does not match the persisted request.');
     }
-    const localCanonical = input.core.getTask(task.id, input.identity.workspaceId);
+    const activeSuccessors = input.store.listActiveOutboxSuccessors(input.identity);
+    const localCanonical = input.core.getTask(task.id, input.identity.workspaceId)
+        || (activeSuccessors.some((successor) => successor.mutationKind === 'delete')
+            ? input.core.getDeletedTask(task.id, input.identity.workspaceId)?.taskSnapshot
+            : null);
     if (!localCanonical)
         throw new LocalAuthoritativeTaskStatusError('Local task status projection is missing.');
     let canonicalMetadataIntent = null;
@@ -269,7 +415,7 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
             || activity.taskId !== task.id
             || activity.action !== 'task-status-changed'
             || !isCanonicalIso(activity.createdAt)
-            || activity.createdAt !== task.updatedAt
+            || activity.createdAt !== (reviewCommentTimestamp || task.updatedAt)
             || typeof activity.actor !== 'string' || !activity.actor.trim()
             || !['human', 'ai', 'system'].includes(activity.actorType)
             || !activity.details || typeof activity.details !== 'object' || Array.isArray(activity.details)
@@ -279,12 +425,37 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
             throw new LocalAuthoritativeTaskStatusError('Authoritative task status activity is invalid.');
         }
     }
-    const revision = validateTaskActivityAuthoritativeRevision({
-        response: response,
-        authoritative: authoritative,
-        activityId: activity?.id || null,
-        invalid: (message) => new LocalAuthoritativeTaskStatusError(message),
-    });
+    const reviewIntermediateRevisions = reviewHandoff ? [
+        { sequence: reviewHandoff.comments.sequence },
+        { sequence: reviewHandoff.activityRevision.sequence },
+    ] : [];
+    const revision = activity === null && reviewHandoff
+        ? (() => {
+            const taskSequence = authoritative.sequence;
+            const commentsSequence = reviewHandoff.comments.sequence;
+            const commentActivitySequence = reviewHandoff.activityRevision.sequence;
+            if (!/^(0|[1-9]\d*)$/.test(taskSequence)
+                || BigInt(commentsSequence) !== BigInt(taskSequence) + 1n
+                || BigInt(commentActivitySequence) !== BigInt(commentsSequence) + 1n
+                || response.operationHighWatermark !== commentActivitySequence
+                || response.dependentActivityRevisions !== undefined) {
+                throw new LocalAuthoritativeTaskStatusError('Authoritative review handoff revisions are not in canonical sequence order.');
+            }
+            return {
+                taskSequence,
+                operationHighWatermark: commentActivitySequence,
+                activityRevision: null,
+                legacySingleEntry: false,
+                dependentActivityRevisions: [],
+            };
+        })()
+        : validateTaskActivityAuthoritativeRevision({
+            response: response,
+            authoritative: authoritative,
+            activityId: activity?.id || null,
+            invalid: (message) => new LocalAuthoritativeTaskStatusError(message),
+            intermediateRevisions: reviewIntermediateRevisions,
+        });
     const dependentActivities = Array.isArray(response.dependentActivities)
         ? response.dependentActivities
         : [];
@@ -373,7 +544,23 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
                 canonicalFingerprint,
                 metadataOwned: authoritative.metadataOwned,
                 reopenAssigneeOwned: authoritative.assigneeOwned,
-            }, ...(!revision.legacySingleEntry && revision.activityRevision && activity ? [{
+            }, ...(reviewHandoff && reviewCommentsPayload && reviewCommentActivity ? [{
+                    domain: 'task-comments',
+                    entityId: task.id,
+                    mutationKind: 'append',
+                    entityRevision: reviewHandoff.comments.entityRevision,
+                    lifecycleRevision: reviewHandoff.comments.lifecycleRevision,
+                    sequence: reviewHandoff.comments.sequence,
+                    canonicalFingerprint: fingerprintWorkspaceSyncPayload(reviewCommentsPayload),
+                }, {
+                    domain: WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN,
+                    entityId: reviewCommentActivity.id,
+                    mutationKind: WORKSPACE_SYNC_ENTITY_EVENT_APPEND,
+                    entityRevision: reviewHandoff.activityRevision.entityRevision,
+                    lifecycleRevision: reviewHandoff.activityRevision.lifecycleRevision,
+                    sequence: reviewHandoff.activityRevision.sequence,
+                    canonicalFingerprint: fingerprintWorkspaceSyncPayload(serializeTaskActivityForSync(reviewCommentActivity)),
+                }] : []), ...(!revision.legacySingleEntry && revision.activityRevision && activity ? [{
                     domain: WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN,
                     entityId: activity.id,
                     mutationKind: WORKSPACE_SYNC_ENTITY_EVENT_APPEND,
@@ -398,14 +585,49 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
                     expectedTaskId: task.id,
                 });
             }
-            const successors = input.store.listActiveOutboxSuccessors(input.identity);
+            const successors = activeSuccessors;
             const hasSuccessor = successors.length > 0;
-            let updated = hasSuccessor
+            const activeTask = hasSuccessor
                 ? input.core.getTask(task.id, input.identity.workspaceId)
+                : null;
+            const deletedSnapshot = !activeTask && successors.some((successor) => successor.mutationKind === 'delete')
+                ? input.core.getDeletedTask(task.id, input.identity.workspaceId)?.taskSnapshot
+                : null;
+            let updated = hasSuccessor
+                ? activeTask || deletedSnapshot
                 : input.core.installDurableTaskStatusAuthoritativeForSync(task, payload, installAssignee, input.identity.workspaceId);
             if (!updated)
                 throw new LocalAuthoritativeTaskStatusError('Local task status projection is missing.');
-            if (hasSuccessor
+            if (reviewHandoff && reviewCommentsPayload && reviewCommentActivity && !deletedSnapshot) {
+                const localComments = serializeWorkspaceSyncV3TaskCommentsPayload({
+                    taskId: updated.id,
+                    comments: updated.comments || [],
+                });
+                const installedComments = hasSuccessor
+                    ? mergeWorkspaceSyncV3TaskCommentsPayload({
+                        taskId: updated.id,
+                        left: reviewCommentsPayload.comments,
+                        right: localComments.comments.filter((comment) => (!reviewCommentsPayload.comments.some((accepted) => accepted.id === comment.id))),
+                    })
+                    : reviewCommentsPayload;
+                updated = input.core.updateTask(task.id, { comments: installedComments.comments }, input.identity.workspaceId, {
+                    persistBackup: false,
+                    emitRealtime: false,
+                    skipTaskEvents: true,
+                    syncUpdatedAt: updated.updatedAt,
+                    allowV3OwnedMetadataWrite: true,
+                });
+                if (!updated)
+                    throw new LocalAuthoritativeTaskStatusError('Review handoff task disappeared locally.');
+                input.core.upsertEntityEventForSync(reviewCommentActivity, { allowAuthoritativeReplacement: true });
+                activityReconciled = true;
+            }
+            else if (reviewHandoff && reviewCommentActivity && deletedSnapshot) {
+                input.core.upsertEntityEventForSync(reviewCommentActivity, { allowAuthoritativeReplacement: true });
+                activityReconciled = true;
+            }
+            if (!deletedSnapshot
+                && hasSuccessor
                 && installAssignee
                 && !successors.some((successor) => successor.ownsTaskAssignee)
                 && normalizeAssignee(updated.assignee) !== normalizeAssignee(task.assignee)) {

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

@@ -90,6 +90,16 @@ export type WorkspaceSyncOutboxRecord = WorkspaceSyncOperationIdentity & {
     initiativeMetadataRevisionRebaseCount?: number;
     leaseOwner: string | null;
     leaseExpiresAt: string | null;
+    lastErrorCode: string | null;
+};
+export type WorkspaceSyncOutboxOperationLookup = WorkspaceSyncOperationIdentity & {
+    status: string;
+    createdAt: string;
+    domain: string;
+    entityId: string;
+    mutationKind: string;
+    payloadFingerprint: string;
+    authoritativeResponseJson: string | null;
 };
 export type WorkspaceSyncOutboxSupersession = {
     recoveryBatchId: string;
@@ -325,6 +335,31 @@ export declare class WorkspaceSyncDurabilityStore {
         createdAt: string;
     } | null;
     readOutboxOperation(identity: WorkspaceSyncOperationIdentity): WorkspaceSyncOutboxRecord | null;
+    assertOutboxOperationIdentity(record: Readonly<WorkspaceSyncOutboxRecord>, expected: {
+        domain: string;
+        entityId: string;
+        mutationKind: string;
+        payloadFingerprint?: string;
+    }): void;
+    readOutboxOperationLookup(identity: WorkspaceSyncOperationIdentity): WorkspaceSyncOutboxOperationLookup | null;
+    pruneTerminalOutboxOperations(input: {
+        tenantId: string;
+        workspaceId: string;
+        terminalBefore: string;
+        limit?: number;
+    }): {
+        deleted: number;
+        remainingEligible: number;
+    };
+    pruneCommittedOperationResults(input: {
+        tenantId: string;
+        workspaceId: string;
+        terminalBefore: string;
+        limit?: number;
+    }): {
+        deleted: number;
+        remainingEligible: number;
+    };
     readV3DispatchSettlementEvidence(identity: WorkspaceSyncOperationIdentity): WorkspaceSyncV3DispatchSettlementEvidence | null;
     listBlockedInvalidOutboxOperations(input: {
         tenantId: string;
@@ -363,7 +398,7 @@ export declare class WorkspaceSyncDurabilityStore {
         identity: WorkspaceSyncOperationIdentity;
         recoveryBatchId: string;
         now: string;
-        replayPolicy?: 'task-root';
+        replayPolicy?: 'task-root' | 'authoritative-workflow-runtime';
         appendToExistingRecovery?: boolean;
     }): WorkspaceSyncOutboxSupersession;
     recordOutboxRecoveryBaseline(input: {