@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/core/WorkflowAssignmentService.d.ts

@@ -0,0 +1,40 @@
+import { WorkflowStore, type WorkflowExecutionEventRecord, type WorkflowExecutionRecord, type WorkflowStepRecord, type WorkflowTemplateRecord, type WorkflowVersionRecord } from '../storage/workflowStore.js';
+export type WorkflowAssignmentServiceErrorCode = 'invalid_input' | 'task_not_found' | 'workflow_not_found' | 'workflow_retired' | 'version_not_found' | 'version_not_published' | 'version_mismatch' | 'active_execution_exists' | 'assignment_locked';
+export declare class WorkflowAssignmentServiceError extends Error {
+    readonly code: WorkflowAssignmentServiceErrorCode;
+    constructor(code: WorkflowAssignmentServiceErrorCode, message: string);
+}
+export interface WorkflowAssignmentDetails {
+    execution: WorkflowExecutionRecord;
+    template: WorkflowTemplateRecord;
+    version: WorkflowVersionRecord;
+    steps: WorkflowStepRecord[];
+    events: WorkflowExecutionEventRecord[];
+}
+export declare class WorkflowAssignmentService {
+    private readonly store;
+    constructor(store: WorkflowStore);
+    assignWorkflow(input: {
+        workspaceId: string;
+        taskId: string;
+        workflowTemplateId: string;
+        workflowVersionId: string;
+        actorId?: string | null;
+    }): WorkflowAssignmentDetails;
+    replacePendingWorkflow(input: {
+        workspaceId: string;
+        taskId: string;
+        workflowTemplateId: string;
+        workflowVersionId: string;
+        actorId: string;
+    }): WorkflowAssignmentDetails;
+    removePendingWorkflow(input: {
+        workspaceId: string;
+        taskId: string;
+        actorId: string;
+    }): void;
+    getActiveAssignment(workspaceIdRaw: string, taskIdRaw: string): WorkflowAssignmentDetails | null;
+    getLatestAssignment(workspaceIdRaw: string, taskIdRaw: string): WorkflowAssignmentDetails | null;
+    private hydrateAssignment;
+    private resolvePublishedSelection;
+}

package/dist/core/WorkflowAssignmentService.js

@@ -0,0 +1,158 @@
+export class WorkflowAssignmentServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkflowAssignmentServiceError';
+    }
+}
+function requireValue(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowAssignmentServiceError('invalid_input', `${field} is required.`);
+    }
+    return value.trim();
+}
+function translateStoreError(error) {
+    if (error instanceof WorkflowAssignmentServiceError)
+        throw error;
+    const message = String(error?.message || error);
+    if (message.includes('Task not found')) {
+        throw new WorkflowAssignmentServiceError('task_not_found', 'Task not found.');
+    }
+    if (message.includes('Retired workflows cannot be assigned')) {
+        throw new WorkflowAssignmentServiceError('workflow_retired', 'Retired workflows cannot be assigned to tasks.');
+    }
+    if (message.includes('already has an active workflow execution')
+        || message.includes('idx_workflow_executions_one_active_per_task')
+        || message.includes('workflow_executions.tenant_id, workflow_executions.workspace_id, workflow_executions.task_id')) {
+        throw new WorkflowAssignmentServiceError('active_execution_exists', 'This task already has an active workflow execution.');
+    }
+    if (message.includes('Only a pending workflow assignment can be')) {
+        throw new WorkflowAssignmentServiceError('assignment_locked', 'A workflow can only be changed or removed while its execution is pending.');
+    }
+    throw error;
+}
+export class WorkflowAssignmentService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    assignWorkflow(input) {
+        const selection = this.resolvePublishedSelection(input);
+        try {
+            const execution = this.store.createExecution({
+                workspaceId: selection.workspaceId,
+                taskId: selection.taskId,
+                workflowVersionId: selection.version.id,
+                actorId: input.actorId,
+            });
+            return {
+                execution,
+                template: selection.template,
+                version: selection.version,
+                steps: selection.steps,
+                events: this.store.listExecutionEvents(selection.workspaceId, execution.id),
+            };
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    replacePendingWorkflow(input) {
+        const selection = this.resolvePublishedSelection(input);
+        try {
+            const execution = this.store.replacePendingExecution({
+                workspaceId: selection.workspaceId,
+                taskId: selection.taskId,
+                workflowVersionId: selection.version.id,
+                actorId: requireValue(input.actorId, 'Workflow assignment actor'),
+            });
+            return {
+                execution,
+                template: selection.template,
+                version: selection.version,
+                steps: selection.steps,
+                events: this.store.listExecutionEvents(selection.workspaceId, execution.id),
+            };
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    removePendingWorkflow(input) {
+        try {
+            this.store.removePendingExecution({
+                workspaceId: requireValue(input.workspaceId, 'Workspace id'),
+                taskId: requireValue(input.taskId, 'Task id'),
+                actorId: requireValue(input.actorId, 'Workflow assignment actor'),
+            });
+        }
+        catch (error) {
+            translateStoreError(error);
+        }
+    }
+    getActiveAssignment(workspaceIdRaw, taskIdRaw) {
+        const workspaceId = requireValue(workspaceIdRaw, 'Workspace id');
+        const taskId = requireValue(taskIdRaw, 'Task id');
+        const execution = this.store.getActiveExecutionForTask(workspaceId, taskId);
+        if (!execution)
+            return null;
+        return this.hydrateAssignment(workspaceId, execution);
+    }
+    getLatestAssignment(workspaceIdRaw, taskIdRaw) {
+        const workspaceId = requireValue(workspaceIdRaw, 'Workspace id');
+        const taskId = requireValue(taskIdRaw, 'Task id');
+        const execution = this.store.getLatestExecutionForTask(workspaceId, taskId);
+        if (!execution)
+            return null;
+        return this.hydrateAssignment(workspaceId, execution);
+    }
+    hydrateAssignment(workspaceId, execution) {
+        const definition = this.store.getTemplateDefinition(workspaceId, execution.workflowTemplateId);
+        if (!definition) {
+            throw new WorkflowAssignmentServiceError('workflow_not_found', 'Workflow not found.');
+        }
+        const selected = definition.versions.find(({ version }) => version.id === execution.workflowVersionId);
+        if (!selected) {
+            throw new WorkflowAssignmentServiceError('version_not_found', 'Workflow version not found.');
+        }
+        return {
+            execution,
+            template: definition.template,
+            version: selected.version,
+            steps: selected.steps,
+            events: this.store.listExecutionEvents(workspaceId, execution.id),
+        };
+    }
+    resolvePublishedSelection(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const taskId = requireValue(input.taskId, 'Task id');
+        const templateId = requireValue(input.workflowTemplateId, 'Workflow template id');
+        const versionId = requireValue(input.workflowVersionId, 'Workflow version id');
+        const definition = this.store.getTemplateDefinition(workspaceId, templateId);
+        if (!definition) {
+            throw new WorkflowAssignmentServiceError('workflow_not_found', 'Workflow not found.');
+        }
+        if (definition.template.status === 'retired') {
+            throw new WorkflowAssignmentServiceError('workflow_retired', 'Retired workflows cannot be assigned to tasks.');
+        }
+        const selected = definition.versions.find(({ version }) => version.id === versionId);
+        if (!selected) {
+            const otherVersion = this.store.getVersion(workspaceId, versionId);
+            if (otherVersion) {
+                throw new WorkflowAssignmentServiceError('version_mismatch', 'The selected workflow version does not belong to this workflow.');
+            }
+            throw new WorkflowAssignmentServiceError('version_not_found', 'Workflow version not found.');
+        }
+        if (selected.version.status !== 'published') {
+            throw new WorkflowAssignmentServiceError('version_not_published', 'Only published workflow versions can be assigned to tasks.');
+        }
+        return {
+            workspaceId,
+            taskId,
+            template: definition.template,
+            version: selected.version,
+            steps: selected.steps,
+        };
+    }
+}

package/dist/core/WorkflowExecutionService.d.ts

@@ -0,0 +1,69 @@
+import { WorkflowStore, type WorkflowExecutionEventRecord, type WorkflowExecutionRecord, type WorkflowExecutionStatus, type WorkflowAssignmentSyncRecord, type WorkflowStepRecord } from '../storage/workflowStore.js';
+import type { TaskItem } from './Taskforce.js';
+import type { TaskActor } from '../types.js';
+export type WorkflowExecutionAction = 'start' | 'pause' | 'resume' | 'complete' | 'fail' | 'end';
+export type WorkflowExecutionServiceErrorCode = 'invalid_input' | 'execution_not_found' | 'invalid_transition' | 'idempotency_conflict' | 'current_step_missing' | 'current_step_mismatch' | 'step_owner_required' | 'step_owner_mismatch' | 'comment_evidence_required' | 'comment_evidence_invalid' | 'next_step_owner_invalid';
+export declare class WorkflowExecutionServiceError extends Error {
+    readonly code: WorkflowExecutionServiceErrorCode;
+    constructor(code: WorkflowExecutionServiceErrorCode, message: string);
+}
+export interface WorkflowExecutionState {
+    execution: WorkflowExecutionRecord;
+    events: WorkflowExecutionEventRecord[];
+}
+export interface WorkflowExecutionCommandResult extends WorkflowExecutionState {
+    event: WorkflowExecutionEventRecord;
+    replayed: boolean;
+}
+export interface WorkflowStepCompletionResult extends WorkflowExecutionState {
+    completedStep: WorkflowStepRecord;
+    nextStep: WorkflowStepRecord | null;
+    taskAssignee: string | null;
+    replayed: boolean;
+    assignmentSnapshot: WorkflowAssignmentSyncRecord;
+    taskSnapshot: TaskItem | null;
+}
+export type WorkflowStepCompletionActorType = 'user' | 'agent';
+type WorkflowExecutionServiceDependencies = {
+    listAssignableActors?: (workspaceId: string) => TaskActor[];
+    getTask?: (workspaceId: string, taskId: string) => TaskItem | null;
+    reassignTask?: (input: {
+        workspaceId: string;
+        taskId: string;
+        assigneeId: string;
+        actorId: string;
+        idempotencyKey: string;
+    }) => TaskItem;
+};
+export declare class WorkflowExecutionService {
+    private readonly store;
+    private readonly dependencies;
+    constructor(store: WorkflowStore, dependencies?: WorkflowExecutionServiceDependencies);
+    getExecutionState(workspaceIdRaw: string, executionIdRaw: string): WorkflowExecutionState;
+    transitionExecution(input: {
+        workspaceId: string;
+        executionId: string;
+        action: WorkflowExecutionAction;
+        expectedStatus?: WorkflowExecutionStatus;
+        actorId: string;
+        idempotencyKey: string;
+        details?: Record<string, unknown>;
+        eventId?: string;
+        occurredAt?: string;
+    }): WorkflowExecutionCommandResult;
+    completeCurrentStep(input: {
+        workspaceId: string;
+        executionId: string;
+        actorId: string;
+        actorType?: WorkflowStepCompletionActorType;
+        expectedStepId?: string;
+        evidenceCommentId?: string;
+        idempotencyKey: string;
+        eventIds?: {
+            stepCompleted: string;
+            terminal: string;
+        };
+        occurredAt?: string;
+    }): WorkflowStepCompletionResult;
+}
+export {};

package/dist/core/WorkflowExecutionService.js

@@ -0,0 +1,342 @@
+export class WorkflowExecutionServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkflowExecutionServiceError';
+    }
+}
+const TRANSITIONS = {
+    start: {
+        eventType: 'execution-started',
+        expectedFromStatuses: ['pending'],
+        toStatus: 'running',
+    },
+    pause: {
+        eventType: 'execution-paused',
+        expectedFromStatuses: ['running'],
+        toStatus: 'paused',
+    },
+    resume: {
+        eventType: 'execution-resumed',
+        expectedFromStatuses: ['paused'],
+        toStatus: 'running',
+    },
+    complete: {
+        eventType: 'execution-completed',
+        expectedFromStatuses: ['running'],
+        toStatus: 'completed',
+    },
+    fail: {
+        eventType: 'execution-failed',
+        expectedFromStatuses: ['pending', 'running', 'paused'],
+        toStatus: 'failed',
+    },
+    end: {
+        eventType: 'execution-ended',
+        expectedFromStatuses: ['pending', 'running', 'paused'],
+        toStatus: 'ended',
+    },
+};
+function requireValue(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowExecutionServiceError('invalid_input', `${field} is required.`);
+    }
+    return value.trim();
+}
+function normalizeDetails(value) {
+    if (value == null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkflowExecutionServiceError('invalid_input', 'Workflow command details must be an object.');
+    }
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        throw new WorkflowExecutionServiceError('invalid_input', 'Workflow command details must be JSON serializable.');
+    }
+}
+function translateStoreError(error) {
+    if (error instanceof WorkflowExecutionServiceError)
+        throw error;
+    const message = String(error?.message || error);
+    if (message.includes('Workflow execution not found')) {
+        throw new WorkflowExecutionServiceError('execution_not_found', 'Workflow execution not found.');
+    }
+    if (message.includes('cannot transition')) {
+        throw new WorkflowExecutionServiceError('invalid_transition', message);
+    }
+    if (message.includes('Idempotency key was already used')) {
+        throw new WorkflowExecutionServiceError('idempotency_conflict', 'This idempotency key was already used for a different workflow command.');
+    }
+    throw error;
+}
+export class WorkflowExecutionService {
+    store;
+    dependencies;
+    constructor(store, dependencies = {}) {
+        this.store = store;
+        this.dependencies = dependencies;
+    }
+    getExecutionState(workspaceIdRaw, executionIdRaw) {
+        const workspaceId = requireValue(workspaceIdRaw, 'Workspace id');
+        const executionId = requireValue(executionIdRaw, 'Workflow execution id');
+        const snapshot = this.store.getExecutionStateSnapshot(workspaceId, executionId);
+        if (!snapshot) {
+            throw new WorkflowExecutionServiceError('execution_not_found', 'Workflow execution not found.');
+        }
+        return snapshot;
+    }
+    transitionExecution(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const executionId = requireValue(input.executionId, 'Workflow execution id');
+        const actorId = requireValue(input.actorId, 'Workflow execution actor');
+        const idempotencyKey = requireValue(input.idempotencyKey, 'Idempotency key');
+        const action = typeof input.action === 'string' ? TRANSITIONS[input.action] : undefined;
+        if (!action) {
+            throw new WorkflowExecutionServiceError('invalid_input', 'Workflow execution action is invalid.');
+        }
+        if (input.expectedStatus && !action.expectedFromStatuses.includes(input.expectedStatus)) {
+            throw new WorkflowExecutionServiceError('invalid_input', 'Workflow execution expected status is invalid for this action.');
+        }
+        const details = normalizeDetails(input.details);
+        try {
+            const result = this.store.appendExecutionTransition({
+                workspaceId,
+                executionId,
+                eventType: action.eventType,
+                expectedFromStatuses: input.expectedStatus ? [input.expectedStatus] : action.expectedFromStatuses,
+                toStatus: action.toStatus,
+                actorId,
+                idempotencyKey,
+                details,
+                eventId: input.eventId,
+                occurredAt: input.occurredAt,
+            });
+            return {
+                execution: result.execution,
+                events: result.events,
+                event: result.event,
+                replayed: result.replayed,
+            };
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    completeCurrentStep(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const executionId = requireValue(input.executionId, 'Workflow execution id');
+        const actorId = requireValue(input.actorId, 'Workflow execution actor');
+        const actorType = input.actorType || 'user';
+        const expectedStepId = input.expectedStepId === undefined
+            ? null
+            : requireValue(input.expectedStepId, 'Expected workflow step id');
+        const evidenceCommentId = input.evidenceCommentId === undefined
+            ? null
+            : requireValue(input.evidenceCommentId, 'Evidence comment id');
+        const idempotencyKey = requireValue(input.idempotencyKey, 'Idempotency key');
+        try {
+            return this.store.transaction(() => {
+                const snapshot = this.store.getExecutionStateSnapshot(workspaceId, executionId, { forUpdate: true });
+                if (!snapshot) {
+                    throw new WorkflowExecutionServiceError('execution_not_found', 'Workflow execution not found.');
+                }
+                const completedReplay = snapshot.events.find((event) => (event.idempotencyKey === `${idempotencyKey}:step-completed`));
+                if (completedReplay) {
+                    if (completedReplay.actorId !== actorId) {
+                        throw new WorkflowExecutionServiceError('idempotency_conflict', 'This idempotency key was already used for a different workflow command.');
+                    }
+                    const terminalReplay = snapshot.events.find((event) => (event.idempotencyKey === `${idempotencyKey}:step-started`
+                        || event.idempotencyKey === `${idempotencyKey}:execution-completed`));
+                    if (!terminalReplay || terminalReplay.actorId !== actorId) {
+                        throw new WorkflowExecutionServiceError('idempotency_conflict', 'This workflow step command has an incomplete or conflicting event history.');
+                    }
+                    if ((input.eventIds && (completedReplay.id !== input.eventIds.stepCompleted
+                        || terminalReplay.id !== input.eventIds.terminal)) || (input.occurredAt && (completedReplay.createdAt !== input.occurredAt
+                        || terminalReplay.createdAt !== input.occurredAt))) {
+                        throw new WorkflowExecutionServiceError('idempotency_conflict', 'This idempotency key was already used for a different workflow command.');
+                    }
+                    const steps = this.store.listSteps(workspaceId, snapshot.execution.workflowVersionId);
+                    const completedStep = steps.find((step) => step.id === completedReplay.stepId);
+                    if (!completedStep) {
+                        throw new WorkflowExecutionServiceError('current_step_missing', 'The completed workflow step is no longer available.');
+                    }
+                    if (expectedStepId && completedStep.id !== expectedStepId) {
+                        throw new WorkflowExecutionServiceError('idempotency_conflict', 'This idempotency key was already used for a different workflow step.');
+                    }
+                    const replayEvidence = completedReplay.details.evidence;
+                    const replayCommentId = replayEvidence
+                        && typeof replayEvidence === 'object'
+                        && !Array.isArray(replayEvidence)
+                        && replayEvidence.type === 'comment'
+                        ? String(replayEvidence.commentId || '')
+                        : '';
+                    if ((evidenceCommentId || replayCommentId) && evidenceCommentId !== replayCommentId) {
+                        throw new WorkflowExecutionServiceError('idempotency_conflict', 'This idempotency key was already used with different workflow evidence.');
+                    }
+                    const nextStep = terminalReplay.eventType === 'step-started'
+                        ? steps.find((step) => step.id === terminalReplay.stepId) || null
+                        : null;
+                    return {
+                        ...snapshot,
+                        completedStep,
+                        nextStep,
+                        taskAssignee: nextStep?.ownerId || completedStep.ownerId || null,
+                        replayed: true,
+                        assignmentSnapshot: this.store.getAssignmentForExecutionSync(workspaceId, executionId),
+                        taskSnapshot: this.dependencies.getTask?.(workspaceId, snapshot.execution.taskId) || null,
+                    };
+                }
+                if (snapshot.execution.status !== 'running') {
+                    throw new WorkflowExecutionServiceError('invalid_transition', `Workflow execution cannot complete a step while ${snapshot.execution.status}.`);
+                }
+                const steps = this.store.listSteps(workspaceId, snapshot.execution.workflowVersionId);
+                const currentIndex = steps.findIndex((step) => step.id === snapshot.execution.currentStepId);
+                if (currentIndex < 0) {
+                    throw new WorkflowExecutionServiceError('current_step_missing', 'The running workflow does not have a valid current step.');
+                }
+                const completedStep = steps[currentIndex];
+                if (expectedStepId && completedStep.id !== expectedStepId) {
+                    throw new WorkflowExecutionServiceError('current_step_mismatch', 'The workflow has advanced to a different step. Read the task workflow before retrying.');
+                }
+                if (!completedStep.ownerId || !completedStep.ownerType) {
+                    throw new WorkflowExecutionServiceError('step_owner_required', 'Assign the current workflow step before completing it.');
+                }
+                if (completedStep.ownerType !== actorType) {
+                    throw new WorkflowExecutionServiceError('step_owner_mismatch', actorType === 'agent'
+                        ? 'Only an agent-owned workflow step can be completed from this action.'
+                        : 'Only a human-owned workflow step can be completed from this action.');
+                }
+                if (completedStep.ownerId !== actorId) {
+                    throw new WorkflowExecutionServiceError('step_owner_mismatch', 'Only the current workflow step owner can complete this step.');
+                }
+                const task = this.dependencies.getTask?.(workspaceId, snapshot.execution.taskId) || null;
+                let evidenceComment = null;
+                if (completedStep.requiresCommentEvidence || evidenceCommentId) {
+                    if (!evidenceCommentId) {
+                        throw new WorkflowExecutionServiceError('comment_evidence_required', 'Add a task comment, then complete the workflow step with that comment as evidence.');
+                    }
+                    evidenceComment = task?.comments?.find((comment) => comment.id === evidenceCommentId) || null;
+                    const evidenceAlreadyUsed = snapshot.events.some((event) => {
+                        const evidence = event.details.evidence;
+                        return event.eventType === 'step-completed'
+                            && evidence
+                            && typeof evidence === 'object'
+                            && !Array.isArray(evidence)
+                            && evidence.type === 'comment'
+                            && evidence.commentId === evidenceCommentId;
+                    });
+                    const currentStepStartedAt = [...snapshot.events]
+                        .reverse()
+                        .find((event) => event.eventType === 'step-started' && event.stepId === completedStep.id)
+                        ?.createdAt || snapshot.execution.startedAt || snapshot.execution.createdAt;
+                    if (!evidenceComment
+                        || !evidenceComment.text.trim()
+                        || evidenceComment.author !== actorId
+                        || Date.parse(evidenceComment.timestamp) < Date.parse(currentStepStartedAt)
+                        || evidenceAlreadyUsed) {
+                        throw new WorkflowExecutionServiceError('comment_evidence_invalid', 'Workflow comment evidence must be a current, unused task comment authored by the step owner.');
+                    }
+                }
+                const nextStep = steps[currentIndex + 1] || null;
+                let nextOwner = null;
+                if (nextStep) {
+                    if (!nextStep.ownerId || !nextStep.ownerType) {
+                        throw new WorkflowExecutionServiceError('next_step_owner_invalid', 'Assign the next workflow step before completing the current step.');
+                    }
+                    nextOwner = this.dependencies.listAssignableActors?.(workspaceId)
+                        .find((actor) => actor.id === nextStep.ownerId) || null;
+                    const ownerTypeMatches = nextStep.ownerType === 'agent'
+                        ? nextOwner?.kind === 'ai'
+                        : nextOwner?.kind === 'human';
+                    if (!nextOwner || nextOwner.meta?.unresolved === true || !ownerTypeMatches) {
+                        throw new WorkflowExecutionServiceError('next_step_owner_invalid', 'The next workflow step owner is not an active assignable workspace actor.');
+                    }
+                }
+                const completed = this.store.appendExecutionTransition({
+                    workspaceId,
+                    executionId,
+                    eventType: 'step-completed',
+                    expectedFromStatuses: ['running'],
+                    toStatus: 'running',
+                    actorId,
+                    idempotencyKey: `${idempotencyKey}:step-completed`,
+                    stepId: completedStep.id,
+                    details: {
+                        stepName: completedStep.name,
+                        ...(evidenceComment ? {
+                            evidence: {
+                                type: 'comment',
+                                commentId: evidenceComment.id,
+                            },
+                        } : {}),
+                    },
+                    eventId: input.eventIds?.stepCompleted,
+                    occurredAt: input.occurredAt,
+                });
+                const advanced = nextStep
+                    ? this.store.appendExecutionTransition({
+                        workspaceId,
+                        executionId,
+                        eventType: 'step-started',
+                        expectedFromStatuses: ['running'],
+                        toStatus: 'running',
+                        actorId,
+                        idempotencyKey: `${idempotencyKey}:step-started`,
+                        stepId: nextStep.id,
+                        details: {
+                            stepName: nextStep.name,
+                            ownerType: nextStep.ownerType,
+                            ownerId: nextStep.ownerId,
+                        },
+                        eventId: input.eventIds?.terminal,
+                        occurredAt: input.occurredAt,
+                    })
+                    : this.store.appendExecutionTransition({
+                        workspaceId,
+                        executionId,
+                        eventType: 'execution-completed',
+                        expectedFromStatuses: ['running'],
+                        toStatus: 'completed',
+                        actorId,
+                        idempotencyKey: `${idempotencyKey}:execution-completed`,
+                        stepId: completedStep.id,
+                        details: { finalStepId: completedStep.id },
+                        eventId: input.eventIds?.terminal,
+                        occurredAt: input.occurredAt,
+                    });
+                let taskSnapshot = null;
+                if (nextStep && nextOwner) {
+                    if (!this.dependencies.reassignTask) {
+                        throw new Error('Workflow task reassignment is unavailable.');
+                    }
+                    taskSnapshot = this.dependencies.reassignTask({
+                        workspaceId,
+                        taskId: snapshot.execution.taskId,
+                        assigneeId: nextOwner.id,
+                        actorId,
+                        idempotencyKey,
+                    }) || null;
+                }
+                const assignmentSnapshot = this.store.getAssignmentForExecutionSync(workspaceId, executionId);
+                if (!assignmentSnapshot)
+                    throw new Error('Workflow assignment snapshot is unavailable.');
+                return {
+                    execution: advanced.execution,
+                    events: advanced.events,
+                    completedStep,
+                    nextStep,
+                    taskAssignee: nextOwner?.id || completedStep.ownerId,
+                    replayed: completed.replayed && advanced.replayed,
+                    assignmentSnapshot,
+                    taskSnapshot,
+                };
+            });
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+}

package/dist/core/WorkflowTaskActivationService.d.ts

@@ -0,0 +1,32 @@
+import type { TaskActor } from '../types.js';
+import { WorkflowStore, type WorkflowExecutionRecord, type WorkflowStepRecord } from '../storage/workflowStore.js';
+export type WorkflowTaskActivationErrorCode = 'workflow_step_missing' | 'workflow_step_owner_invalid';
+export declare class WorkflowTaskActivationError extends Error {
+    readonly code: WorkflowTaskActivationErrorCode;
+    readonly statusCode = 409;
+    constructor(code: WorkflowTaskActivationErrorCode, message: string);
+}
+export interface PreparedWorkflowTaskActivation {
+    execution: WorkflowExecutionRecord;
+    step: WorkflowStepRecord;
+    ownerId: string | null;
+}
+export declare class WorkflowTaskActivationService {
+    private readonly store;
+    private readonly listAssignableActors;
+    constructor(store: WorkflowStore, listAssignableActors: (workspaceId: string) => TaskActor[]);
+    prepare(input: {
+        workspaceId: string;
+        taskId: string;
+        currentTaskStatus: string;
+        targetTaskStatus: string;
+    }): PreparedWorkflowTaskActivation | null;
+    start(input: {
+        workspaceId: string;
+        activation: PreparedWorkflowTaskActivation;
+        actorId: string;
+        taskEventId: string;
+        eventId?: string;
+        occurredAt?: string;
+    }): WorkflowExecutionRecord;
+}