@taskforcehq/taskforce 0.3.328 → 0.3.330

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,23 +118,80 @@ export function enqueueLocalTaskStatusMutation(input) {
             taskLifecycle: true,
             taskAssignee: payload.assigneeIntent.kind !== 'preserve',
         },
-        payload: withOriginActorPayload({ ...payload }, input.actorRef),
+        ...(reviewComment ? {
+            additionalTargets: [{
+                    domain: 'task-comments',
+                    entityId: taskId,
+                    mutationKind: 'append',
+                    baseEntityRevision: reviewCommentRevision.entityRevision,
+                    baseLifecycleRevision: reviewCommentRevision.lifecycleRevision,
+                }],
+        } : {}),
+        payload: withOriginActorPayload({
+            ...payload,
+            ...(input.expectedDetailRevision
+                ? { expectedDetailRevision: input.expectedDetailRevision }
+                : {}),
+        }, input.actorRef),
         ...(payload.workflowAssignment ? {
             coalesceWorkflowAssignmentExecutionId: payload.workflowAssignment.execution.id,
         } : {}),
         ...(input.requireV3CombinedOwnership ? { requireV3PlanningOwnership: 'combined' } : {}),
         now: input.now,
-        applyLocalMutation: () => applyTaskStatusMutationForDurableSync({
-            core: input.core,
-            workspaceId: input.identity.workspaceId,
-            taskId,
-            targetStatus: statusPayload.status,
-            metadataPatch: statusPayload.metadataPatch,
-            assigneeIntent: statusPayload.assigneeIntent,
-            canceledReason: statusPayload.canceledReason,
-            updatedAt: input.now,
-            actorRef: input.actorRef,
-            taskEventId: activityEventId,
+        applyLocalMutation: () => {
+            if (input.expectedDetailRevision) {
+                if (!input.core.assertTaskDetailRevisionForUpdate) {
+                    throw new Error('Task detail revision checks are unavailable.');
+                }
+                input.core.assertTaskDetailRevisionForUpdate(taskId, input.expectedDetailRevision, input.identity.workspaceId);
+            }
+            let mutation = applyTaskStatusMutationForDurableSync({
+                core: input.core,
+                workspaceId: input.identity.workspaceId,
+                taskId,
+                targetStatus: statusPayload.status,
+                metadataPatch: statusPayload.metadataPatch,
+                assigneeIntent: statusPayload.assigneeIntent,
+                canceledReason: statusPayload.canceledReason,
+                updatedAt: input.now,
+                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) => [
+                key,
+                result.task[key] ?? null,
+            ])),
         }),
     });
     if (!result.enqueued)
@@ -98,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);
         }
@@ -155,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
@@ -189,9 +350,31 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
     const localCanonical = input.core.getTask(task.id, input.identity.workspaceId);
     if (!localCanonical)
         throw new LocalAuthoritativeTaskStatusError('Local task status projection is missing.');
+    let canonicalMetadataIntent = null;
+    if (input.record.canonicalIntentJson) {
+        try {
+            const parsed = JSON.parse(input.record.canonicalIntentJson);
+            canonicalMetadataIntent = parsed.metadataPatch
+                && typeof parsed.metadataPatch === 'object'
+                && !Array.isArray(parsed.metadataPatch)
+                ? parsed.metadataPatch
+                : null;
+        }
+        catch {
+            canonicalMetadataIntent = null;
+        }
+        if (!canonicalMetadataIntent) {
+            throw new LocalAuthoritativeTaskStatusError('Persisted canonical task status intent is invalid.');
+        }
+    }
     for (const key of Object.keys(payload.metadataPatch)) {
+        if (canonicalMetadataIntent && !Object.prototype.hasOwnProperty.call(canonicalMetadataIntent, key)) {
+            throw new LocalAuthoritativeTaskStatusError('Persisted canonical task status intent is incomplete.');
+        }
         const actual = task[key];
-        const expected = localCanonical[key];
+        const expected = canonicalMetadataIntent
+            ? canonicalMetadataIntent[key]
+            : localCanonical[key];
         if (fingerprintWorkspaceSyncPayload(actual ?? null) !== fingerprintWorkspaceSyncPayload(expected ?? null)) {
             throw new LocalAuthoritativeTaskStatusError('Authoritative task metadata does not match the persisted request.');
         }
@@ -228,7 +411,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)
@@ -238,12 +421,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
         : [];
@@ -332,7 +540,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,
@@ -364,6 +588,30 @@ export function applyAuthoritativeTaskStatusAndAck(input) {
                 : input.core.installDurableTaskStatusAuthoritativeForSync(task, payload, installAssignee, input.identity.workspaceId);
             if (!updated)
                 throw new LocalAuthoritativeTaskStatusError('Local task status projection is missing.');
+            if (reviewHandoff && reviewCommentsPayload && reviewCommentActivity) {
+                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;
+            }
             if (hasSuccessor
                 && installAssignee
                 && !successors.some((successor) => successor.ownsTaskAssignee)

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

@@ -80,6 +80,7 @@ export type WorkspaceSyncOutboxRecord = WorkspaceSyncOperationIdentity & {
     baseLifecycleRevision: string;
     payloadJson: string;
     payloadFingerprint: string;
+    canonicalIntentJson: string | null;
     status: string;
     attemptCount: number;
     initialNotFoundAttemptCount: number;
@@ -90,6 +91,15 @@ export type WorkspaceSyncOutboxRecord = WorkspaceSyncOperationIdentity & {
     leaseOwner: string | null;
     leaseExpiresAt: 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;
     operationIds: string[];
@@ -324,6 +334,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;
@@ -542,6 +577,7 @@ export declare class WorkspaceSyncDurabilityStore {
         queuedTaskSuccessor?: boolean;
         queuedWorkflowRuntimeSuccessor?: boolean;
         coalesceWorkflowAssignmentExecutionId?: string;
+        buildCanonicalIntent?: (mutationResult: T) => unknown;
     }): {
         enqueued: boolean;
         mutationResult?: T;
@@ -760,6 +796,11 @@ export declare class WorkspaceSyncDurabilityStore {
     private assertTaskCommentAppendRecoveryEventOwned;
     private isTaskCommentAppendRecoveryIntentSatisfied;
     private prepareTaskRecoveryPayload;
+    lockWorkspaceSequenceForMutation(input: {
+        tenantId: string;
+        workspaceId: string;
+        now: string;
+    }): void;
     private allocateSequenceRange;
     private allocateOutboxEnqueueSequence;
     private readOperationRow;