@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/storage/workflowStore.js

@@ -0,0 +1,1032 @@
+import { randomUUID } from 'crypto';
+export class WorkflowAssignmentSyncConflictError extends Error {
+    code = 'WORKFLOW_ASSIGNMENT_SYNC_CONFLICT';
+    statusCode = 409;
+    constructor(message) {
+        super(message);
+        this.name = 'WorkflowAssignmentSyncConflictError';
+    }
+}
+function normalizeWorkspaceId(value) {
+    return String(value || '').trim() || 'default';
+}
+function requireText(value, field) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`${field} is required.`);
+    return normalized;
+}
+function optionalText(value) {
+    return String(value || '').trim() || null;
+}
+function normalizeWorkflowStepInputs(steps) {
+    return steps.map((step) => {
+        const ownerType = step.ownerType || null;
+        const ownerId = optionalText(step.ownerId);
+        if ((ownerType && !ownerId) || (!ownerType && ownerId)) {
+            throw new Error('Workflow step owner type and owner id must be provided together.');
+        }
+        return {
+            name: requireText(step.name, 'Workflow step name'),
+            instructions: String(step.instructions || '').trim(),
+            ownerType,
+            ownerId,
+            expectedArtifact: optionalText(step.expectedArtifact),
+            requiresCommentEvidence: step.requiresCommentEvidence === true,
+            isRequired: step.isRequired !== false,
+        };
+    });
+}
+function canonicalJson(value) {
+    const normalize = (entry) => {
+        if (Array.isArray(entry))
+            return entry.map(normalize);
+        if (entry && typeof entry === 'object') {
+            return Object.fromEntries(Object.entries(entry)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, item]) => [key, normalize(item)]));
+        }
+        return entry;
+    };
+    return JSON.stringify(normalize(value)) || '{}';
+}
+function mapTemplate(row) {
+    return {
+        id: String(row.id),
+        tenantId: String(row.tenant_id),
+        workspaceId: String(row.workspace_id),
+        name: String(row.name),
+        description: String(row.description || ''),
+        status: row.status === 'retired' ? 'retired' : 'active',
+        createdByActorId: optionalText(row.created_by_actor_id),
+        updatedByActorId: optionalText(row.updated_by_actor_id),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        deletedAt: optionalText(row.deleted_at),
+    };
+}
+function mapVersion(row) {
+    return {
+        id: String(row.id),
+        tenantId: String(row.tenant_id),
+        workspaceId: String(row.workspace_id),
+        workflowTemplateId: String(row.workflow_template_id),
+        versionNumber: row.version_number == null ? null : Number(row.version_number),
+        status: row.status === 'published' ? 'published' : 'draft',
+        name: String(row.name),
+        description: String(row.description || ''),
+        createdByActorId: optionalText(row.created_by_actor_id),
+        updatedByActorId: optionalText(row.updated_by_actor_id),
+        publishedByActorId: optionalText(row.published_by_actor_id),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        publishedAt: optionalText(row.published_at),
+        deletedAt: optionalText(row.deleted_at),
+    };
+}
+function mapStep(row) {
+    return {
+        id: String(row.id),
+        tenantId: String(row.tenant_id),
+        workspaceId: String(row.workspace_id),
+        workflowVersionId: String(row.workflow_version_id),
+        position: Number(row.position),
+        name: String(row.name),
+        instructions: String(row.instructions || ''),
+        ownerType: row.owner_type === 'user' || row.owner_type === 'agent' ? row.owner_type : null,
+        ownerId: optionalText(row.owner_id),
+        expectedArtifact: optionalText(row.expected_artifact),
+        requiresCommentEvidence: Number(row.requires_comment_evidence) === 1,
+        isRequired: Number(row.is_required) !== 0,
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
+function mapExecution(row) {
+    return {
+        id: String(row.id),
+        tenantId: String(row.tenant_id),
+        workspaceId: String(row.workspace_id),
+        taskId: String(row.task_id),
+        workflowTemplateId: String(row.workflow_template_id),
+        workflowVersionId: String(row.workflow_version_id),
+        status: row.status,
+        currentStepId: optionalText(row.current_step_id),
+        createdByActorId: optionalText(row.created_by_actor_id),
+        updatedByActorId: optionalText(row.updated_by_actor_id),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        startedAt: optionalText(row.started_at),
+        completedAt: optionalText(row.completed_at),
+        endedAt: optionalText(row.ended_at),
+        deletedAt: optionalText(row.deleted_at),
+    };
+}
+function mapExecutionEvent(row) {
+    let details = {};
+    try {
+        const parsed = JSON.parse(String(row.details_json || '{}'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            details = parsed;
+    }
+    catch {
+        details = {};
+    }
+    return {
+        id: String(row.id),
+        tenantId: String(row.tenant_id),
+        workspaceId: String(row.workspace_id),
+        workflowExecutionId: String(row.workflow_execution_id),
+        sequenceNumber: Number(row.sequence_number),
+        eventType: row.event_type,
+        fromStatus: row.from_status ? row.from_status : null,
+        toStatus: row.to_status,
+        stepId: optionalText(row.step_id),
+        actorId: String(row.actor_id),
+        idempotencyKey: optionalText(row.idempotency_key),
+        details,
+        createdAt: String(row.created_at),
+    };
+}
+export function projectWorkflowExecutionEvents(events) {
+    if (events.length === 0)
+        throw new Error('Workflow execution has no history.');
+    let status = null;
+    let currentStepId = null;
+    let startedAt = null;
+    let completedAt = null;
+    let endedAt = null;
+    const validTransition = (event) => {
+        if (event.eventType === 'execution-created')
+            return event.fromStatus === null && event.toStatus === 'pending';
+        if (event.eventType === 'execution-started')
+            return event.fromStatus === 'pending' && event.toStatus === 'running';
+        if (event.eventType === 'step-completed' || event.eventType === 'step-started') {
+            return event.fromStatus === 'running' && event.toStatus === 'running' && Boolean(event.stepId);
+        }
+        if (event.eventType === 'execution-paused')
+            return event.fromStatus === 'running' && event.toStatus === 'paused';
+        if (event.eventType === 'execution-resumed')
+            return event.fromStatus === 'paused' && event.toStatus === 'running';
+        if (event.eventType === 'execution-completed')
+            return event.fromStatus === 'running' && event.toStatus === 'completed';
+        if (event.eventType === 'execution-failed') {
+            return event.toStatus === 'failed' && ['pending', 'running', 'paused'].includes(String(event.fromStatus));
+        }
+        return event.eventType === 'execution-ended'
+            && event.toStatus === 'ended'
+            && ['pending', 'running', 'paused'].includes(String(event.fromStatus));
+    };
+    for (const [index, event] of events.entries()) {
+        if (event.sequenceNumber !== index || !validTransition(event)) {
+            throw new Error('Workflow execution history is inconsistent.');
+        }
+        if (status === null && event.fromStatus !== null) {
+            throw new Error('Workflow execution history is inconsistent.');
+        }
+        if (status !== null && event.fromStatus !== status) {
+            throw new Error('Workflow execution history is inconsistent.');
+        }
+        status = event.toStatus;
+        if (event.stepId && (event.eventType === 'execution-started' || event.eventType === 'step-started')) {
+            currentStepId = event.stepId;
+        }
+        if (event.eventType === 'execution-started' && !startedAt)
+            startedAt = event.createdAt;
+        if (event.eventType === 'execution-completed')
+            completedAt = event.createdAt;
+        if (event.eventType === 'execution-failed' || event.eventType === 'execution-ended')
+            endedAt = event.createdAt;
+    }
+    const lastEvent = events[events.length - 1];
+    return {
+        status: status,
+        currentStepId,
+        startedAt,
+        completedAt,
+        endedAt,
+        updatedAt: lastEvent.createdAt,
+        lastEventId: lastEvent.id,
+    };
+}
+function applyExecutionProjection(execution, projection) {
+    return {
+        ...execution,
+        status: projection.status,
+        currentStepId: projection.currentStepId,
+        startedAt: projection.startedAt,
+        completedAt: projection.completedAt,
+        endedAt: projection.endedAt,
+        updatedAt: projection.updatedAt,
+    };
+}
+export class WorkflowStore {
+    db;
+    tenantId;
+    constructor(db, tenantId) {
+        this.db = db;
+        this.tenantId = tenantId;
+    }
+    transaction(callback) {
+        return this.db.transaction(callback)();
+    }
+    createTemplate(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const name = requireText(input.name, 'Workflow name');
+        const description = String(input.description || '').trim();
+        const actorId = optionalText(input.actorId);
+        const steps = normalizeWorkflowStepInputs(input.steps || []);
+        const now = new Date().toISOString();
+        const templateId = `workflow-template-${randomUUID()}`;
+        const versionId = `workflow-version-${randomUUID()}`;
+        this.db.transaction(() => {
+            this.db.prepare(`
+                INSERT INTO workflow_templates (
+                    id, tenant_id, workspace_id, name, description, status,
+                    created_by_actor_id, updated_by_actor_id, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)
+            `).run(templateId, this.tenantId, workspaceId, name, description, actorId, actorId, now, now);
+            this.db.prepare(`
+                INSERT INTO workflow_versions (
+                    id, tenant_id, workspace_id, workflow_template_id, version_number,
+                    status, name, description, created_by_actor_id, updated_by_actor_id,
+                    created_at, updated_at
+                ) VALUES (?, ?, ?, ?, NULL, 'draft', ?, ?, ?, ?, ?, ?)
+            `).run(versionId, this.tenantId, workspaceId, templateId, name, description, actorId, actorId, now, now);
+            this.writeDraftSteps(workspaceId, versionId, steps, now);
+        })();
+        return {
+            template: this.getTemplate(workspaceId, templateId),
+            draftVersion: this.getVersion(workspaceId, versionId),
+        };
+    }
+    listTemplates(workspaceIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        return this.db.prepare(`
+            SELECT * FROM workflow_templates
+            WHERE tenant_id = ? AND workspace_id = ? AND deleted_at IS NULL
+            ORDER BY updated_at DESC, name ASC
+        `).all(this.tenantId, workspaceId).map(mapTemplate);
+    }
+    getTemplate(workspaceIdRaw, templateIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const templateId = String(templateIdRaw || '').trim();
+        if (!templateId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT * FROM workflow_templates
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+            LIMIT 1
+        `).get(this.tenantId, workspaceId, templateId);
+        return row ? mapTemplate(row) : null;
+    }
+    getTemplateDefinition(workspaceIdRaw, templateIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const templateId = String(templateIdRaw || '').trim();
+        if (!templateId)
+            return null;
+        return this.db.transaction(() => {
+            const versionRows = this.db.prepare(`
+                SELECT * FROM workflow_versions
+                WHERE tenant_id = ? AND workspace_id = ? AND workflow_template_id = ? AND deleted_at IS NULL
+                ORDER BY CASE WHEN status = 'draft' THEN 0 ELSE 1 END ASC, version_number DESC
+                ${this.db.provider === 'postgres' ? 'FOR SHARE' : ''}
+            `).all(this.tenantId, workspaceId, templateId);
+            const templateRow = this.db.prepare(`
+                SELECT * FROM workflow_templates
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR SHARE' : ''}
+            `).get(this.tenantId, workspaceId, templateId);
+            if (!templateRow)
+                return null;
+            return {
+                template: mapTemplate(templateRow),
+                versions: versionRows.map((row) => {
+                    const version = mapVersion(row);
+                    return {
+                        version,
+                        steps: this.listSteps(workspaceId, version.id),
+                    };
+                }),
+            };
+        })();
+    }
+    listVersions(workspaceIdRaw, templateIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const templateId = String(templateIdRaw || '').trim();
+        return this.db.prepare(`
+            SELECT * FROM workflow_versions
+            WHERE tenant_id = ? AND workspace_id = ? AND workflow_template_id = ? AND deleted_at IS NULL
+            ORDER BY CASE WHEN status = 'draft' THEN 0 ELSE 1 END ASC, version_number DESC
+        `).all(this.tenantId, workspaceId, templateId).map(mapVersion);
+    }
+    getVersion(workspaceIdRaw, versionIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const versionId = String(versionIdRaw || '').trim();
+        if (!versionId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT * FROM workflow_versions
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+            LIMIT 1
+        `).get(this.tenantId, workspaceId, versionId);
+        return row ? mapVersion(row) : null;
+    }
+    createDraftVersion(workspaceIdRaw, templateIdRaw, actorId) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const templateId = String(templateIdRaw || '').trim();
+        const id = `workflow-version-${randomUUID()}`;
+        const now = new Date().toISOString();
+        const normalizedActorId = optionalText(actorId);
+        return this.db.transaction(() => {
+            const templateRow = this.db.prepare(`
+                SELECT * FROM workflow_templates
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(this.tenantId, workspaceId, templateId);
+            if (!templateRow)
+                throw new Error('Workflow template not found.');
+            const template = mapTemplate(templateRow);
+            const locked = this.db.prepare(`
+                UPDATE workflow_templates
+                SET updated_at = updated_at
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+            `).run(this.tenantId, workspaceId, template.id);
+            if (Number(locked?.changes || 0) !== 1)
+                throw new Error('Workflow template not found.');
+            const versions = this.listVersions(workspaceId, template.id);
+            const existingDraft = versions.find((version) => version.status === 'draft');
+            if (existingDraft)
+                throw new Error('Workflow template already has a draft version.');
+            const latestPublished = versions.find((version) => version.status === 'published');
+            const source = latestPublished || template;
+            this.db.prepare(`
+                INSERT INTO workflow_versions (
+                    id, tenant_id, workspace_id, workflow_template_id, version_number,
+                    status, name, description, created_by_actor_id, updated_by_actor_id,
+                    created_at, updated_at
+                ) VALUES (?, ?, ?, ?, NULL, 'draft', ?, ?, ?, ?, ?, ?)
+            `).run(id, this.tenantId, workspaceId, template.id, source.name, source.description, normalizedActorId, normalizedActorId, now, now);
+            if (latestPublished) {
+                const insert = this.db.prepare(`
+                    INSERT INTO workflow_steps (
+                        id, tenant_id, workspace_id, workflow_version_id, position,
+                        name, instructions, owner_type, owner_id, expected_artifact,
+                        requires_comment_evidence, is_required, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `);
+                this.listSteps(workspaceId, latestPublished.id).forEach((step) => {
+                    insert.run(`workflow-step-${randomUUID()}`, this.tenantId, workspaceId, id, step.position, step.name, step.instructions, step.ownerType || null, step.ownerId || null, step.expectedArtifact || null, step.requiresCommentEvidence ? 1 : 0, step.isRequired ? 1 : 0, now, now);
+                });
+            }
+            return this.getVersion(workspaceId, id);
+        })();
+    }
+    updateDraftVersion(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const name = requireText(input.name, 'Workflow name');
+        const description = String(input.description || '').trim();
+        const now = new Date().toISOString();
+        const actorId = optionalText(input.actorId);
+        return this.db.transaction(() => {
+            const version = this.guardDraftVersionForMutation(workspaceId, input.versionId);
+            return this.writeDraftMetadata(workspaceId, version, name, description, actorId, now);
+        })();
+    }
+    replaceDraftSteps(workspaceIdRaw, versionIdRaw, steps) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const normalizedSteps = normalizeWorkflowStepInputs(steps);
+        const now = new Date().toISOString();
+        return this.db.transaction(() => {
+            const version = this.guardDraftVersionForMutation(workspaceId, versionIdRaw);
+            this.writeDraftSteps(workspaceId, version.id, normalizedSteps, now);
+            return this.listSteps(workspaceId, version.id);
+        })();
+    }
+    saveDraft(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const name = requireText(input.name, 'Workflow name');
+        const description = String(input.description || '').trim();
+        const actorId = optionalText(input.actorId);
+        const normalizedSteps = normalizeWorkflowStepInputs(input.steps);
+        const now = new Date().toISOString();
+        return this.db.transaction(() => {
+            const version = this.guardDraftVersionForMutation(workspaceId, input.versionId);
+            this.writeDraftMetadata(workspaceId, version, name, description, actorId, now);
+            this.writeDraftSteps(workspaceId, version.id, normalizedSteps, now);
+            return {
+                version: this.getVersion(workspaceId, version.id),
+                steps: this.listSteps(workspaceId, version.id),
+            };
+        })();
+    }
+    writeDraftMetadata(workspaceId, version, name, description, actorId, now) {
+        const updated = this.db.prepare(`
+            UPDATE workflow_versions
+            SET name = ?, description = ?, updated_by_actor_id = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND status = 'draft' AND deleted_at IS NULL
+        `).run(name, description, actorId, now, this.tenantId, workspaceId, version.id);
+        if (Number(updated?.changes || 0) !== 1)
+            throw new Error('Published workflow versions are immutable.');
+        this.db.prepare(`
+            UPDATE workflow_templates
+            SET name = ?, description = ?, updated_by_actor_id = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+        `).run(name, description, actorId, now, this.tenantId, workspaceId, version.workflowTemplateId);
+        return this.getVersion(workspaceId, version.id);
+    }
+    writeDraftSteps(workspaceId, versionId, steps, now) {
+        this.db.prepare(`
+            DELETE FROM workflow_steps
+            WHERE tenant_id = ? AND workspace_id = ? AND workflow_version_id = ?
+        `).run(this.tenantId, workspaceId, versionId);
+        const insert = this.db.prepare(`
+            INSERT INTO workflow_steps (
+                id, tenant_id, workspace_id, workflow_version_id, position,
+                name, instructions, owner_type, owner_id, expected_artifact,
+                requires_comment_evidence, is_required, created_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `);
+        steps.forEach((step, position) => {
+            insert.run(`workflow-step-${randomUUID()}`, this.tenantId, workspaceId, versionId, position, step.name, step.instructions, step.ownerType, step.ownerId, step.expectedArtifact, step.requiresCommentEvidence ? 1 : 0, step.isRequired ? 1 : 0, now, now);
+        });
+    }
+    listSteps(workspaceIdRaw, versionIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const versionId = String(versionIdRaw || '').trim();
+        return this.db.prepare(`
+            SELECT * FROM workflow_steps
+            WHERE tenant_id = ? AND workspace_id = ? AND workflow_version_id = ?
+            ORDER BY position ASC
+        `).all(this.tenantId, workspaceId, versionId).map(mapStep);
+    }
+    publishVersion(workspaceIdRaw, versionIdRaw, actorId) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const actor = optionalText(actorId);
+        const now = new Date().toISOString();
+        return this.db.transaction(() => {
+            const version = this.guardDraftVersionForMutation(workspaceId, versionIdRaw);
+            if (this.listSteps(workspaceId, version.id).length === 0) {
+                throw new Error('Workflow version must have at least one step before publishing.');
+            }
+            const row = this.db.prepare(`
+                SELECT MAX(version_number) AS max_version
+                FROM workflow_versions
+                WHERE tenant_id = ? AND workspace_id = ? AND workflow_template_id = ?
+                    AND status = 'published' AND deleted_at IS NULL
+            `).get(this.tenantId, workspaceId, version.workflowTemplateId);
+            const versionNumber = Number(row?.max_version || 0) + 1;
+            const result = this.db.prepare(`
+                UPDATE workflow_versions
+                SET version_number = ?, status = 'published', published_by_actor_id = ?,
+                    updated_by_actor_id = ?, published_at = ?, updated_at = ?
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND status = 'draft' AND deleted_at IS NULL
+            `).run(versionNumber, actor, actor, now, now, this.tenantId, workspaceId, version.id);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new Error('Published workflow versions are immutable.');
+            }
+            return this.getVersion(workspaceId, version.id);
+        })();
+    }
+    createExecution(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const taskId = requireText(input.taskId, 'Task id');
+        const id = `workflow-execution-${randomUUID()}`;
+        const actor = optionalText(input.actorId);
+        const now = new Date().toISOString();
+        return this.db.transaction(() => {
+            const versionRow = this.db.prepare(`
+                SELECT * FROM workflow_versions
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR SHARE' : ''}
+            `).get(this.tenantId, workspaceId, input.workflowVersionId);
+            const version = versionRow ? mapVersion(versionRow) : null;
+            if (!version || version.status !== 'published') {
+                throw new Error('A published workflow version is required.');
+            }
+            const templateRow = this.db.prepare(`
+                SELECT status FROM workflow_templates
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(this.tenantId, workspaceId, version.workflowTemplateId);
+            if (!templateRow)
+                throw new Error('Workflow template not found.');
+            if (templateRow.status === 'retired')
+                throw new Error('Retired workflows cannot be assigned.');
+            if (this.db.provider === 'sqlite') {
+                const templateLock = this.db.prepare(`
+                    UPDATE workflow_templates
+                    SET updated_at = updated_at
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND status = 'active' AND deleted_at IS NULL
+                `).run(this.tenantId, workspaceId, version.workflowTemplateId);
+                if (Number(templateLock?.changes || 0) !== 1)
+                    throw new Error('Retired workflows cannot be assigned.');
+            }
+            const task = this.db.prepare(`
+                SELECT id FROM tasks
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR SHARE' : ''}
+            `).get(this.tenantId, workspaceId, taskId);
+            if (!task)
+                throw new Error('Task not found.');
+            const active = this.getActiveExecutionForTask(workspaceId, taskId);
+            if (active)
+                throw new Error('Task already has an active workflow execution.');
+            this.db.prepare(`
+                INSERT INTO workflow_executions (
+                    id, tenant_id, workspace_id, task_id, workflow_template_id,
+                    workflow_version_id, status, current_step_id, created_by_actor_id,
+                    updated_by_actor_id, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, ?, ?, ?, ?)
+            `).run(id, this.tenantId, workspaceId, taskId, version.workflowTemplateId, version.id, actor, actor, now, now);
+            this.db.prepare(`
+                INSERT INTO workflow_execution_events (
+                    id, tenant_id, workspace_id, workflow_execution_id, sequence_number, event_type,
+                    from_status, to_status, step_id, actor_id, idempotency_key,
+                    details_json, created_at
+                ) VALUES (?, ?, ?, ?, 0, 'execution-created', NULL, 'pending', NULL, ?, NULL, '{}', ?)
+            `).run(`workflow-execution-event-${randomUUID()}`, this.tenantId, workspaceId, id, actor || 'system', now);
+            return this.getProjectedExecution(workspaceId, id);
+        })();
+    }
+    replacePendingExecution(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const taskId = requireText(input.taskId, 'Task id');
+        const actorId = requireText(input.actorId, 'Workflow execution actor');
+        return this.db.transaction(() => {
+            const active = this.getActiveExecutionForTask(workspaceId, taskId);
+            if (!active) {
+                return this.createExecution({ ...input, workspaceId, taskId, actorId });
+            }
+            if (active.status !== 'pending') {
+                throw new Error('Only a pending workflow assignment can be replaced.');
+            }
+            if (active.workflowVersionId === input.workflowVersionId)
+                return active;
+            this.appendExecutionTransition({
+                workspaceId,
+                executionId: active.id,
+                eventType: 'execution-ended',
+                expectedFromStatuses: ['pending'],
+                toStatus: 'ended',
+                actorId,
+                idempotencyKey: `pending-workflow-replaced-${randomUUID()}`,
+                details: {
+                    reason: 'workflow-replaced',
+                    replacementWorkflowVersionId: input.workflowVersionId,
+                },
+            });
+            return this.createExecution({ ...input, workspaceId, taskId, actorId });
+        })();
+    }
+    removePendingExecution(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const taskId = requireText(input.taskId, 'Task id');
+        const actorId = requireText(input.actorId, 'Workflow execution actor');
+        return this.db.transaction(() => {
+            const active = this.getActiveExecutionForTask(workspaceId, taskId);
+            if (!active)
+                return null;
+            if (active.status !== 'pending') {
+                throw new Error('Only a pending workflow assignment can be removed.');
+            }
+            return this.appendExecutionTransition({
+                workspaceId,
+                executionId: active.id,
+                eventType: 'execution-ended',
+                expectedFromStatuses: ['pending'],
+                toStatus: 'ended',
+                actorId,
+                idempotencyKey: `pending-workflow-removed-${randomUUID()}`,
+                details: { reason: 'workflow-removed' },
+            }).execution;
+        })();
+    }
+    getExecution(workspaceIdRaw, executionIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const executionId = String(executionIdRaw || '').trim();
+        if (!executionId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT * FROM workflow_executions
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+            LIMIT 1
+        `).get(this.tenantId, workspaceId, executionId);
+        return row ? mapExecution(row) : null;
+    }
+    getActiveExecutionForTask(workspaceIdRaw, taskIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const taskId = String(taskIdRaw || '').trim();
+        if (!taskId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT * FROM workflow_executions
+            WHERE tenant_id = ? AND workspace_id = ? AND task_id = ?
+                AND status IN ('pending', 'running', 'paused') AND deleted_at IS NULL
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get(this.tenantId, workspaceId, taskId);
+        return row ? mapExecution(row) : null;
+    }
+    getLatestExecutionForTask(workspaceIdRaw, taskIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const taskId = String(taskIdRaw || '').trim();
+        if (!taskId)
+            return null;
+        const active = this.getActiveExecutionForTask(workspaceId, taskId);
+        if (active)
+            return active;
+        const row = this.db.prepare(`
+            SELECT * FROM workflow_executions
+            WHERE tenant_id = ? AND workspace_id = ? AND task_id = ? AND deleted_at IS NULL
+                AND status IN ('completed', 'failed', 'ended')
+            ORDER BY created_at DESC, id DESC
+            LIMIT 1
+        `).get(this.tenantId, workspaceId, taskId);
+        return row ? mapExecution(row) : null;
+    }
+    listExecutions(workspaceIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        return this.db.prepare(`
+            SELECT * FROM workflow_executions
+            WHERE tenant_id = ? AND workspace_id = ? AND deleted_at IS NULL
+            ORDER BY created_at ASC, id ASC
+        `).all(this.tenantId, workspaceId).map(mapExecution);
+    }
+    listExecutionEvents(workspaceIdRaw, executionIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const executionId = String(executionIdRaw || '').trim();
+        if (!executionId)
+            return [];
+        return this.db.prepare(`
+            SELECT * FROM workflow_execution_events
+            WHERE tenant_id = ? AND workspace_id = ? AND workflow_execution_id = ?
+            ORDER BY sequence_number ASC
+        `).all(this.tenantId, workspaceId, executionId).map(mapExecutionEvent);
+    }
+    getProjectedExecution(workspaceIdRaw, executionIdRaw) {
+        return this.getExecutionStateSnapshot(workspaceIdRaw, executionIdRaw)?.execution || null;
+    }
+    getExecutionStateSnapshot(workspaceIdRaw, executionIdRaw, options = {}) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const executionId = String(executionIdRaw || '').trim();
+        if (!executionId)
+            return null;
+        return this.db.transaction(() => {
+            const executionRow = this.db.prepare(`
+                SELECT * FROM workflow_executions
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? (options.forUpdate ? 'FOR UPDATE' : 'FOR SHARE') : ''}
+            `).get(this.tenantId, workspaceId, executionId);
+            if (!executionRow)
+                return null;
+            if (options.forUpdate && this.db.provider === 'sqlite') {
+                this.db.prepare(`
+                    UPDATE workflow_executions SET updated_at = updated_at
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                `).run(this.tenantId, workspaceId, executionId);
+            }
+            const events = this.listExecutionEvents(workspaceId, executionId);
+            const projection = projectWorkflowExecutionEvents(events);
+            return {
+                execution: applyExecutionProjection(mapExecution(executionRow), projection),
+                events,
+            };
+        })();
+    }
+    getAssignmentForTaskSync(workspaceIdRaw, taskIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const execution = this.getActiveExecutionForTask(workspaceId, taskIdRaw);
+        return execution ? this.getAssignmentForExecutionSync(workspaceId, execution.id) : null;
+    }
+    getAssignmentForExecutionSync(workspaceIdRaw, executionIdRaw) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        const execution = this.getProjectedExecution(workspaceId, executionIdRaw);
+        if (!execution)
+            return null;
+        const template = this.getTemplate(workspaceId, execution.workflowTemplateId);
+        const version = this.getVersion(workspaceId, execution.workflowVersionId);
+        if (!template || !version)
+            return null;
+        return {
+            template,
+            version,
+            steps: this.listSteps(workspaceId, version.id),
+            execution,
+            events: this.listExecutionEvents(workspaceId, execution.id),
+        };
+    }
+    installAssignmentForSync(workspaceIdRaw, snapshot, options) {
+        const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
+        if (snapshot.execution.taskId !== options.expectedTaskId
+            || snapshot.template.workspaceId !== workspaceId
+            || snapshot.version.workspaceId !== workspaceId
+            || snapshot.execution.workspaceId !== workspaceId
+            || snapshot.version.workflowTemplateId !== snapshot.template.id
+            || snapshot.execution.workflowTemplateId !== snapshot.template.id
+            || snapshot.execution.workflowVersionId !== snapshot.version.id
+            || snapshot.steps.some((step) => step.workspaceId !== workspaceId || step.workflowVersionId !== snapshot.version.id)
+            || snapshot.events.some((event) => event.workspaceId !== workspaceId || event.workflowExecutionId !== snapshot.execution.id)) {
+            throw new WorkflowAssignmentSyncConflictError('Workflow assignment sync identity is invalid.');
+        }
+        if (snapshot.version.status !== 'published') {
+            throw new WorkflowAssignmentSyncConflictError('Workflow assignment sync requires a published version.');
+        }
+        if (options.authority === 'pending-intent'
+            && (snapshot.execution.status !== 'pending'
+                || snapshot.events.length !== 1
+                || snapshot.events[0]?.eventType !== 'execution-created')) {
+            throw new WorkflowAssignmentSyncConflictError('Only a pending workflow assignment can be sent to cloud execution.');
+        }
+        let snapshotProjection;
+        try {
+            snapshotProjection = projectWorkflowExecutionEvents(snapshot.events);
+        }
+        catch {
+            throw new WorkflowAssignmentSyncConflictError('Workflow assignment event history is invalid.');
+        }
+        if (snapshot.execution.status !== snapshotProjection.status
+            || (snapshot.execution.currentStepId || null) !== (snapshotProjection.currentStepId || null)
+            || (snapshot.execution.startedAt || null) !== (snapshotProjection.startedAt || null)
+            || (snapshot.execution.completedAt || null) !== (snapshotProjection.completedAt || null)
+            || (snapshot.execution.endedAt || null) !== (snapshotProjection.endedAt || null)
+            || snapshot.execution.updatedAt !== snapshotProjection.updatedAt) {
+            throw new WorkflowAssignmentSyncConflictError('Workflow assignment execution does not match its event history.');
+        }
+        return this.db.transaction(() => {
+            const existingForTask = this.getActiveExecutionForTask(workspaceId, snapshot.execution.taskId);
+            if (existingForTask && existingForTask.id !== snapshot.execution.id) {
+                throw new WorkflowAssignmentSyncConflictError('Task already has a different active workflow execution.');
+            }
+            const existingTemplate = this.getTemplate(workspaceId, snapshot.template.id);
+            if (options.authority === 'pending-intent'
+                && (snapshot.template.status !== 'active' || existingTemplate?.status === 'retired')) {
+                throw new WorkflowAssignmentSyncConflictError('Retired workflows cannot be started.');
+            }
+            if (!existingTemplate) {
+                this.db.prepare(`
+                    INSERT INTO workflow_templates (
+                        id, tenant_id, workspace_id, name, description, status,
+                        created_by_actor_id, updated_by_actor_id, created_at, updated_at, deleted_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(snapshot.template.id, this.tenantId, workspaceId, snapshot.template.name, snapshot.template.description, snapshot.template.status, snapshot.template.createdByActorId || null, snapshot.template.updatedByActorId || null, snapshot.template.createdAt, snapshot.template.updatedAt, snapshot.template.deletedAt || null);
+            }
+            const existingVersion = this.getVersion(workspaceId, snapshot.version.id);
+            if (existingVersion && canonicalJson({
+                workflowTemplateId: existingVersion.workflowTemplateId,
+                versionNumber: existingVersion.versionNumber,
+                status: existingVersion.status,
+                name: existingVersion.name,
+                description: existingVersion.description,
+            }) !== canonicalJson({
+                workflowTemplateId: snapshot.version.workflowTemplateId,
+                versionNumber: snapshot.version.versionNumber,
+                status: snapshot.version.status,
+                name: snapshot.version.name,
+                description: snapshot.version.description,
+            })) {
+                throw new WorkflowAssignmentSyncConflictError('Workflow assignment published version conflicts with canonical storage.');
+            }
+            if (!existingVersion) {
+                this.db.prepare(`
+                    INSERT INTO workflow_versions (
+                        id, tenant_id, workspace_id, workflow_template_id, version_number,
+                        status, name, description, created_by_actor_id, updated_by_actor_id,
+                        published_by_actor_id, created_at, updated_at, published_at, deleted_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(snapshot.version.id, this.tenantId, workspaceId, snapshot.template.id, snapshot.version.versionNumber ?? null, snapshot.version.status, snapshot.version.name, snapshot.version.description, snapshot.version.createdByActorId || null, snapshot.version.updatedByActorId || null, snapshot.version.publishedByActorId || null, snapshot.version.createdAt, snapshot.version.updatedAt, snapshot.version.publishedAt || null, snapshot.version.deletedAt || null);
+                const insertStep = this.db.prepare(`
+                    INSERT INTO workflow_steps (
+                        id, tenant_id, workspace_id, workflow_version_id, position,
+                        name, instructions, owner_type, owner_id, expected_artifact,
+                        requires_comment_evidence, is_required, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `);
+                for (const step of snapshot.steps) {
+                    insertStep.run(step.id, this.tenantId, workspaceId, snapshot.version.id, step.position, step.name, step.instructions, step.ownerType || null, step.ownerId || null, step.expectedArtifact || null, step.requiresCommentEvidence ? 1 : 0, step.isRequired ? 1 : 0, step.createdAt, step.updatedAt);
+                }
+            }
+            else {
+                const comparableStep = (step) => ({
+                    id: step.id,
+                    position: step.position,
+                    name: step.name,
+                    instructions: step.instructions,
+                    ownerType: step.ownerType || null,
+                    ownerId: step.ownerId || null,
+                    expectedArtifact: step.expectedArtifact || null,
+                    requiresCommentEvidence: step.requiresCommentEvidence,
+                    isRequired: step.isRequired,
+                });
+                if (canonicalJson(this.listSteps(workspaceId, existingVersion.id).map(comparableStep))
+                    !== canonicalJson(snapshot.steps.map(comparableStep))) {
+                    throw new WorkflowAssignmentSyncConflictError('Workflow assignment published steps conflict with canonical storage.');
+                }
+            }
+            const existingExecution = this.getExecution(workspaceId, snapshot.execution.id);
+            const comparableExecutionIdentity = (execution) => ({
+                taskId: execution.taskId,
+                workflowTemplateId: execution.workflowTemplateId,
+                workflowVersionId: execution.workflowVersionId,
+                createdByActorId: execution.createdByActorId || null,
+                createdAt: execution.createdAt,
+            });
+            if (existingExecution
+                && canonicalJson(comparableExecutionIdentity(existingExecution))
+                    !== canonicalJson(comparableExecutionIdentity(snapshot.execution))) {
+                throw new WorkflowAssignmentSyncConflictError('Workflow assignment execution conflicts with canonical storage.');
+            }
+            if (!existingExecution) {
+                this.db.prepare(`
+                    INSERT INTO workflow_executions (
+                        id, tenant_id, workspace_id, task_id, workflow_template_id,
+                        workflow_version_id, status, current_step_id, created_by_actor_id,
+                        updated_by_actor_id, created_at, updated_at, started_at,
+                        completed_at, ended_at, deleted_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(snapshot.execution.id, this.tenantId, workspaceId, snapshot.execution.taskId, snapshot.template.id, snapshot.version.id, snapshot.execution.status, snapshot.execution.currentStepId || null, snapshot.execution.createdByActorId || null, snapshot.execution.updatedByActorId || null, snapshot.execution.createdAt, snapshot.execution.updatedAt, snapshot.execution.startedAt || null, snapshot.execution.completedAt || null, snapshot.execution.endedAt || null, snapshot.execution.deletedAt || null);
+            }
+            const canonicalEvents = this.listExecutionEvents(workspaceId, snapshot.execution.id);
+            const authoritativeHistoryIsExactPrefix = options.authority === 'cloud-execution'
+                && snapshot.events.length < canonicalEvents.length
+                && snapshot.events.every((event, index) => canonicalJson(event) === canonicalJson(canonicalEvents[index]));
+            if (authoritativeHistoryIsExactPrefix) {
+                return this.getExecutionStateSnapshot(workspaceId, snapshot.execution.id);
+            }
+            if (canonicalEvents.length > snapshot.events.length
+                || canonicalEvents.some((event, index) => canonicalJson(event) !== canonicalJson(snapshot.events[index]))) {
+                throw new WorkflowAssignmentSyncConflictError('Workflow assignment history conflicts with canonical storage.');
+            }
+            const existingEvents = new Map(canonicalEvents.map((event) => [event.id, event]));
+            const existingEventsBySequence = new Map(canonicalEvents.map((event) => [event.sequenceNumber, event]));
+            const existingEventsByIdempotencyKey = new Map(canonicalEvents
+                .filter((event) => event.idempotencyKey)
+                .map((event) => [event.idempotencyKey, event]));
+            const insertEvent = this.db.prepare(`
+                INSERT INTO workflow_execution_events (
+                    id, tenant_id, workspace_id, workflow_execution_id, sequence_number,
+                    event_type, from_status, to_status, step_id, actor_id,
+                    idempotency_key, details_json, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `);
+            for (const event of snapshot.events) {
+                const existingEvent = existingEvents.get(event.id);
+                if (existingEvent) {
+                    if (canonicalJson(existingEvent) !== canonicalJson(event)) {
+                        throw new WorkflowAssignmentSyncConflictError('Workflow assignment event conflicts with canonical storage.');
+                    }
+                    continue;
+                }
+                const reboundEvent = this.db.prepare(`
+                    SELECT * FROM workflow_execution_events
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                    LIMIT 1
+                `).get(this.tenantId, workspaceId, event.id);
+                if (reboundEvent
+                    || existingEventsBySequence.has(event.sequenceNumber)
+                    || (event.idempotencyKey && existingEventsByIdempotencyKey.has(event.idempotencyKey))) {
+                    throw new WorkflowAssignmentSyncConflictError('Workflow assignment event conflicts with canonical storage.');
+                }
+                insertEvent.run(event.id, this.tenantId, workspaceId, snapshot.execution.id, event.sequenceNumber, event.eventType, event.fromStatus || null, event.toStatus, event.stepId || null, event.actorId, event.idempotencyKey || null, canonicalJson(event.details), event.createdAt);
+                existingEvents.set(event.id, event);
+                existingEventsBySequence.set(event.sequenceNumber, event);
+                if (event.idempotencyKey)
+                    existingEventsByIdempotencyKey.set(event.idempotencyKey, event);
+            }
+            if (options.authority === 'cloud-execution') {
+                this.db.prepare(`
+                    UPDATE workflow_executions
+                    SET status = ?, current_step_id = ?, updated_by_actor_id = ?, updated_at = ?,
+                        started_at = ?, completed_at = ?, ended_at = ?, deleted_at = ?
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                `).run(snapshotProjection.status, snapshotProjection.currentStepId || null, snapshot.execution.updatedByActorId || null, snapshotProjection.updatedAt, snapshotProjection.startedAt || null, snapshotProjection.completedAt || null, snapshotProjection.endedAt || null, snapshot.execution.deletedAt || null, this.tenantId, workspaceId, snapshot.execution.id);
+            }
+            return this.getExecutionStateSnapshot(workspaceId, snapshot.execution.id);
+        })();
+    }
+    appendExecutionTransition(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const executionId = String(input.executionId || '').trim();
+        const actorId = requireText(input.actorId, 'Workflow execution actor');
+        const idempotencyKey = requireText(input.idempotencyKey, 'Workflow execution idempotency key');
+        const requestedEventId = input.eventId
+            ? requireText(input.eventId, 'Workflow execution event id')
+            : null;
+        const requestedOccurredAt = input.occurredAt
+            ? requireText(input.occurredAt, 'Workflow execution event timestamp')
+            : null;
+        if (requestedOccurredAt
+            && (!Number.isFinite(Date.parse(requestedOccurredAt))
+                || new Date(requestedOccurredAt).toISOString() !== requestedOccurredAt)) {
+            throw new Error('Workflow execution event timestamp must be canonical.');
+        }
+        return this.db.transaction(() => {
+            const executionRow = this.db.prepare(`
+                SELECT * FROM workflow_executions
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(this.tenantId, workspaceId, executionId);
+            if (!executionRow)
+                throw new Error('Workflow execution not found.');
+            if (this.db.provider === 'sqlite') {
+                this.db.prepare(`
+                    UPDATE workflow_executions SET updated_at = updated_at
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+                `).run(this.tenantId, workspaceId, executionId);
+            }
+            const baseExecution = mapExecution(executionRow);
+            const events = this.listExecutionEvents(workspaceId, executionId);
+            const existingRow = this.db.prepare(`
+                SELECT * FROM workflow_execution_events
+                WHERE tenant_id = ? AND workspace_id = ? AND workflow_execution_id = ? AND idempotency_key = ?
+                LIMIT 1
+            `).get(this.tenantId, workspaceId, executionId, idempotencyKey);
+            if (existingRow) {
+                const event = mapExecutionEvent(existingRow);
+                if (event.eventType !== input.eventType
+                    || event.toStatus !== input.toStatus
+                    || event.actorId !== actorId
+                    || optionalText(event.stepId) !== optionalText(input.stepId)
+                    || canonicalJson(event.details) !== canonicalJson(input.details || {})
+                    || (requestedEventId !== null && event.id !== requestedEventId)
+                    || (requestedOccurredAt !== null && event.createdAt !== requestedOccurredAt)) {
+                    throw new Error('Idempotency key was already used for a different workflow command.');
+                }
+                const projection = projectWorkflowExecutionEvents(events);
+                return {
+                    execution: applyExecutionProjection(baseExecution, projection),
+                    events,
+                    event,
+                    replayed: true,
+                };
+            }
+            const current = projectWorkflowExecutionEvents(events);
+            if (!input.expectedFromStatuses.includes(current.status)) {
+                throw new Error(`Workflow execution cannot transition from ${current.status} using ${input.eventType}.`);
+            }
+            const eventId = requestedEventId || `workflow-execution-event-${randomUUID()}`;
+            const createdAt = requestedOccurredAt || new Date().toISOString();
+            const sequenceNumber = events.length === 0 ? 0 : events[events.length - 1].sequenceNumber + 1;
+            this.db.prepare(`
+                INSERT INTO workflow_execution_events (
+                    id, tenant_id, workspace_id, workflow_execution_id, sequence_number, event_type,
+                    from_status, to_status, step_id, actor_id, idempotency_key,
+                    details_json, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(eventId, this.tenantId, workspaceId, executionId, sequenceNumber, input.eventType, current.status, input.toStatus, optionalText(input.stepId), actorId, idempotencyKey, canonicalJson(input.details || {}), createdAt);
+            const eventRow = this.db.prepare(`
+                SELECT * FROM workflow_execution_events
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                LIMIT 1
+            `).get(this.tenantId, workspaceId, eventId);
+            const event = mapExecutionEvent(eventRow);
+            const nextEvents = [...events, event];
+            const next = projectWorkflowExecutionEvents(nextEvents);
+            this.db.prepare(`
+                UPDATE workflow_executions
+                SET status = ?, current_step_id = ?, updated_by_actor_id = ?, updated_at = ?,
+                    started_at = ?, completed_at = ?, ended_at = ?
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+            `).run(next.status, next.currentStepId || null, actorId, next.updatedAt, next.startedAt || null, next.completedAt || null, next.endedAt || null, this.tenantId, workspaceId, executionId);
+            return {
+                execution: {
+                    ...applyExecutionProjection(baseExecution, next),
+                    updatedByActorId: actorId,
+                },
+                events: nextEvents,
+                event,
+                replayed: false,
+            };
+        })();
+    }
+    guardDraftVersionForMutation(workspaceId, versionIdRaw) {
+        const versionId = String(versionIdRaw || '').trim();
+        const row = this.db.prepare(`
+            SELECT * FROM workflow_versions
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND deleted_at IS NULL
+            LIMIT 1
+            ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+        `).get(this.tenantId, workspaceId, versionId);
+        const version = row ? mapVersion(row) : null;
+        if (!version)
+            throw new Error('Workflow version not found.');
+        if (version.status !== 'draft')
+            throw new Error('Published workflow versions are immutable.');
+        const result = this.db.prepare(`
+            UPDATE workflow_versions
+            SET updated_at = updated_at
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND status = 'draft' AND deleted_at IS NULL
+        `).run(this.tenantId, workspaceId, version.id);
+        if (Number(result?.changes || 0) !== 1) {
+            throw new Error('Published workflow versions are immutable.');
+        }
+        return version;
+    }
+}