@weave-kit/engine 0.5.0 → 0.6.0

package/dist/runtime/data-access/workflow.js

@@ -0,0 +1,636 @@
+import { randomUUID } from 'node:crypto';
+import { SchemaError, WEAVE_STATUS, WORKFLOW_START_NODE, parseDuration, } from '../../core/index.js';
+import { SYSTEM_TABLES } from '../../core/storage/system-tables.js';
+import { upsertRecordMeta } from '../record-meta/index.js';
+const q = (id) => `"${id}"`;
+const T = SYSTEM_TABLES;
+const USER_TABLE = 'weavekit_user';
+/** the workflow action set (single source of truth) */
+export const WORKFLOW_ACTIONS = {
+    SUBMIT: 'submit',
+    APPROVE: 'approve',
+    REJECT: 'reject',
+    WITHDRAW: 'withdraw',
+    CANCEL: 'cancel',
+    FORWARD: 'forward',
+    REACTIVATE: 'reactivate',
+};
+/** role name that may run admin-only actions (reactivate / future override) */
+export const WORKFLOW_ADMIN_ROLE = 'admin';
+/** true when the subject holds an admin role */
+export function isWorkflowAdmin(subject) {
+    return subject !== undefined && subject.roles.includes(WORKFLOW_ADMIN_ROLE);
+}
+/** side-table `status` mirror values (map instance state → record status) */
+const SIDE_STATUS = {
+    running: WEAVE_STATUS.RUNNING,
+    finished: WEAVE_STATUS.EFFECTIVE,
+    canceled: WEAVE_STATUS.CANCELED,
+};
+/** load (and row-lock) the single instance for a record, if any */
+async function loadInstance(client, object, recordKey) {
+    const res = await client.query(`SELECT state, workflow_hash, current_step_id, originator, originator_parent
+       FROM ${q(T.WORKFLOW_INSTANCES)} WHERE object = $1 AND record_key = $2 FOR UPDATE`, [object, recordKey]);
+    return res.rows[0];
+}
+/** the current active step of an instance (row-locked) */
+async function loadActiveStep(client, stepId) {
+    if (stepId === null)
+        return undefined;
+    const res = await client.query(`SELECT id, node_id, kind, ordinal, state FROM ${q(T.WORKFLOW_STEPS)} WHERE id = $1 FOR UPDATE`, [stepId]);
+    return res.rows[0];
+}
+/** open (active) workitems of a step (row-locked) */
+async function loadOpenWorkitems(client, stepId) {
+    const res = await client.query(`SELECT id, step_id, node_id, kind, participant, state
+       FROM ${q(T.WORKFLOW_WORKITEMS)} WHERE step_id = $1 AND state = 'active' FOR UPDATE`, [stepId]);
+    return res.rows;
+}
+async function nextOrdinal(client, object, recordKey) {
+    const res = await client.query(`SELECT COALESCE(MAX(ordinal), 0) + 1 AS n FROM ${q(T.WORKFLOW_STEPS)} WHERE object = $1 AND record_key = $2`, [object, recordKey]);
+    return Number(res.rows[0].n);
+}
+/** resolve node roles to internal user ids (`weavekit_user.roles` jsonb containment) */
+async function resolveAssignees(client, roles) {
+    if (roles.length === 0)
+        return [];
+    const res = await client.query(`SELECT id::text AS id FROM ${q(USER_TABLE)} WHERE enabled IS NOT FALSE AND roles ?| $1::text[]`, [roles]);
+    return res.rows.map((r) => r.id);
+}
+/** resolve the definition an instance is pinned to (registry fast-path, else the registry table) */
+async function resolveDefinition(client, def, hash, locale) {
+    if (def.workflow !== undefined && def.workflowHash === hash)
+        return def.workflow;
+    const res = await client.query(`SELECT definition FROM ${q(T.WORKFLOW_DEFINITIONS)} WHERE object = $1 AND hash = $2`, [def.name, hash]);
+    const row = res.rows[0];
+    if (row === undefined) {
+        throw new SchemaError('workflow.definition.missing', { object: def.name }, locale);
+    }
+    return row.definition;
+}
+/** content-address the current definition (idempotent, append-only) */
+async function registerDefinition(client, object, hash, workflow) {
+    await client.query(`INSERT INTO ${q(T.WORKFLOW_DEFINITIONS)} (object, hash, version_seq, definition)
+     VALUES ($1, $2, (SELECT COALESCE(MAX(version_seq), 0) + 1 FROM ${q(T.WORKFLOW_DEFINITIONS)} WHERE object = $1), $3::jsonb)
+     ON CONFLICT (object, hash) DO NOTHING`, [object, hash, JSON.stringify(workflow)]);
+}
+async function createStep(client, object, recordKey, nodeId, kind, prevStepId, now) {
+    const stepId = randomUUID();
+    const ordinal = await nextOrdinal(client, object, recordKey);
+    await client.query(`INSERT INTO ${q(T.WORKFLOW_STEPS)} (id, object, record_key, node_id, kind, ordinal, state, prev_step_id, entered_at)
+     VALUES ($1, $2, $3, $4, $5, $6, 'active', $7, $8)`, [stepId, object, recordKey, nodeId, kind, ordinal, prevStepId, now]);
+    return stepId;
+}
+async function insertWorkitem(client, w) {
+    const id = randomUUID();
+    await client.query(`INSERT INTO ${q(T.WORKFLOW_WORKITEMS)}
+       (id, object, record_key, step_id, node_id, kind, participant, state, approval, action,
+        finisher, delegant, receiptor, comment, received_at, finished_at, allowed_at)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14, now(), $15, $16)`, [
+        id,
+        w.object,
+        w.recordKey,
+        w.stepId,
+        w.nodeId,
+        w.kind,
+        w.participant,
+        w.state,
+        w.approval ?? null,
+        w.action ?? null,
+        w.finisher ?? null,
+        w.delegant ?? null,
+        w.receiptor ?? null,
+        w.comment ?? null,
+        w.finishedAt ?? null,
+        w.allowedAt ?? null,
+    ]);
+    return id;
+}
+async function closeWorkitem(client, id, fields, now) {
+    await client.query(`UPDATE ${q(T.WORKFLOW_WORKITEMS)}
+       SET state = $2, approval = $3, action = $4, finisher = $5, comment = $6, finished_at = $7
+     WHERE id = $1`, [id, fields.state, fields.approval ?? null, fields.action ?? null, fields.finisher ?? null, fields.comment ?? null, now]);
+}
+async function cancelOpenWorkitems(client, stepId, now) {
+    await client.query(`UPDATE ${q(T.WORKFLOW_WORKITEMS)} SET state = 'canceled', finished_at = $2 WHERE step_id = $1 AND state = 'active'`, [stepId, now]);
+}
+async function closeStep(client, id, state, approval, now) {
+    await client.query(`UPDATE ${q(T.WORKFLOW_STEPS)} SET state = $2, approval = $3, finished_at = $4 WHERE id = $1`, [
+        id,
+        state,
+        approval,
+        now,
+    ]);
+}
+async function updateInstance(client, object, recordKey, sets) {
+    const cols = Object.keys(sets);
+    if (cols.length === 0)
+        return;
+    const setSql = cols.map((c, i) => `${q(c)} = $${i + 3}`).join(', ');
+    await client.query(`UPDATE ${q(T.WORKFLOW_INSTANCES)} SET ${setSql} WHERE object = $1 AND record_key = $2`, [object, recordKey, ...cols.map((c) => sets[c])]);
+}
+async function mirrorSide(client, object, recordKey, state, actor, now) {
+    await upsertRecordMeta(client, object, recordKey, {
+        status: SIDE_STATUS[state] ?? WEAVE_STATUS.RUNNING,
+        workflowInstanceId: recordKey,
+        modifiedBy: actor,
+        modifiedTime: now,
+    });
+}
+/** create a node's step + workitems; `notify` nodes auto-advance. Returns the active step or `finished` */
+async function enterNode(client, ctx, nodeIndex) {
+    if (nodeIndex >= ctx.wf.nodes.length)
+        return { finished: true };
+    const node = ctx.wf.nodes[nodeIndex];
+    const kind = node.kind ?? 'approve';
+    const stepId = await createStep(client, ctx.def.name, ctx.recordKey, node.id, kind, ctx.prevStepId, ctx.now);
+    ctx.prevStepId = stepId;
+    const users = await resolveAssignees(client, node.assign.roles);
+    if (kind === 'notify') {
+        for (const participant of users) {
+            await insertWorkitem(client, {
+                object: ctx.def.name,
+                recordKey: ctx.recordKey,
+                stepId,
+                nodeId: node.id,
+                kind: 'cc',
+                participant,
+                state: 'done',
+                action: 'notify',
+                finishedAt: ctx.now,
+            });
+        }
+        await closeStep(client, stepId, 'finished', null, ctx.now);
+        return enterNode(client, ctx, nodeIndex + 1);
+    }
+    if (users.length === 0) {
+        throw new SchemaError('workflow.assignee.none', { object: ctx.def.name, node: node.id }, ctx.locale);
+    }
+    const timeoutMs = node.onTimeout === undefined ? undefined : parseDuration(node.onTimeout.after);
+    const allowedAt = timeoutMs === undefined || timeoutMs <= 0 ? null : new Date(ctx.now.getTime() + timeoutMs);
+    for (const participant of users) {
+        await insertWorkitem(client, {
+            object: ctx.def.name,
+            recordKey: ctx.recordKey,
+            stepId,
+            nodeId: node.id,
+            kind: 'approve',
+            participant,
+            state: 'active',
+            allowedAt,
+        });
+    }
+    return { stepId, nodeId: node.id };
+}
+/** create the implicit start node's step (originator acts via `submit`) */
+async function enterStart(client, ctx) {
+    const stepId = await createStep(client, ctx.def.name, ctx.recordKey, WORKFLOW_START_NODE, 'start', ctx.prevStepId, ctx.now);
+    ctx.prevStepId = stepId;
+    return stepId;
+}
+function nodeIndexOf(wf, nodeId) {
+    return wf.nodes.findIndex((n) => n.id === nodeId);
+}
+/** cancel/withdraw/cancel guard: nobody else may be actively viewing the record */
+async function assertNoForeignLock(client, object, recordKey, requester, locale) {
+    const res = await client.query(`SELECT holder FROM ${q(T.WORKFLOW_LOCKS)}
+      WHERE object = $1 AND record_key = $2 AND expires_at > now() AND holder <> $3 LIMIT 1`, [object, recordKey, requester]);
+    const row = res.rows[0];
+    if (row !== undefined) {
+        throw new SchemaError('workflow.withdraw.locked', { object, holder: row.holder }, locale);
+    }
+}
+/** find the caller's open workitem (or undefined) */
+function findMyWorkitem(items, subject) {
+    if (subject === undefined)
+        return undefined;
+    return items.find((w) => w.kind === 'approve' && w.participant === subject.id);
+}
+/**
+ * Run one workflow action within the caller's transaction. The instance row is
+ * locked; steps/workitems are opened/closed accordingly. The side-table status
+ * mirror is updated in the same transaction.
+ */
+export async function runWorkflowTransition(client, def, recordKey, action, subject, payload, locale) {
+    const now = new Date();
+    const actor = subject?.id ?? 'system';
+    const inst = await loadInstance(client, def.name, recordKey);
+    if (action === WORKFLOW_ACTIONS.SUBMIT) {
+        const hash = def.workflowHash;
+        if (def.workflow === undefined || def.workflow.nodes.length === 0 || hash === undefined) {
+            throw new SchemaError('workflow.transition.unknown', { object: def.name, action }, locale);
+        }
+        let prevStepId = null;
+        if (inst !== undefined && inst.state === 'running') {
+            const step = await loadActiveStep(client, inst.current_step_id);
+            if (step === undefined || step.node_id !== WORKFLOW_START_NODE) {
+                throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action }, locale);
+            }
+            await closeStep(client, step.id, 'finished', null, now);
+            prevStepId = step.id;
+        }
+        await registerDefinition(client, def.name, hash, def.workflow);
+        if (inst === undefined) {
+            await client.query(`INSERT INTO ${q(T.WORKFLOW_INSTANCES)}
+           (object, record_key, workflow_hash, state, current_step_id, originator, originator_parent, approval, created_at, started_at, activated_at)
+         VALUES ($1,$2,$3,'running',NULL,$4,$5,NULL,$6,$6,$6)`, [def.name, recordKey, hash, actor, subject?.departmentId ?? null, now]);
+        }
+        else {
+            await updateInstance(client, def.name, recordKey, {
+                state: 'running',
+                workflow_hash: hash,
+                approval: null,
+                started_at: inst.state === 'running' ? undefined : now,
+                activated_at: now,
+                finished_at: null,
+            });
+        }
+        const ctx = { def, recordKey, wf: def.workflow, now, locale, prevStepId };
+        const entered = await enterNode(client, ctx, 0);
+        if ('finished' in entered) {
+            await updateInstance(client, def.name, recordKey, { state: 'finished', approval: 'approved', finished_at: now, current_step_id: null });
+            await mirrorSide(client, def.name, recordKey, 'finished', actor, now);
+            return { state: 'finished', fromNodeId: WORKFLOW_START_NODE };
+        }
+        await updateInstance(client, def.name, recordKey, { current_step_id: entered.stepId });
+        await mirrorSide(client, def.name, recordKey, 'running', actor, now);
+        return { state: 'running', nodeId: entered.nodeId, toNodeId: entered.nodeId, fromNodeId: WORKFLOW_START_NODE };
+    }
+    if (action === WORKFLOW_ACTIONS.REACTIVATE) {
+        if (!isWorkflowAdmin(subject)) {
+            throw new SchemaError('workflow.transition.denied', { object: def.name, role: subject?.roles.join(',') ?? '', action }, locale);
+        }
+        if (inst === undefined || inst.state === 'running') {
+            throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action }, locale);
+        }
+        const wf = await resolveDefinition(client, def, inst.workflow_hash, locale);
+        const nodeId = payload?.node;
+        const idx = typeof nodeId === 'string' ? wf.nodes.findIndex((n) => n.id === nodeId) : -1;
+        if (typeof nodeId !== 'string' || idx < 0) {
+            throw new SchemaError('workflow.node.unknown', { object: def.name, node: String(nodeId ?? '') }, locale);
+        }
+        const ctx = { def, recordKey, wf, now, locale, prevStepId: null };
+        const entered = await enterNode(client, ctx, idx);
+        if ('finished' in entered) {
+            await updateInstance(client, def.name, recordKey, {
+                state: 'finished',
+                approval: 'approved',
+                finished_at: now,
+                current_step_id: null,
+                activated_at: now,
+            });
+            await mirrorSide(client, def.name, recordKey, 'finished', actor, now);
+            return { state: 'finished' };
+        }
+        await updateInstance(client, def.name, recordKey, {
+            state: 'running',
+            current_step_id: entered.stepId,
+            approval: null,
+            finished_at: null,
+            activated_at: now,
+        });
+        await mirrorSide(client, def.name, recordKey, 'running', actor, now);
+        return { state: 'running', nodeId: entered.nodeId, toNodeId: entered.nodeId };
+    }
+    if (inst === undefined || inst.state !== 'running') {
+        throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action }, locale);
+    }
+    const wf = await resolveDefinition(client, def, inst.workflow_hash, locale);
+    const step = await loadActiveStep(client, inst.current_step_id);
+    if (step === undefined) {
+        throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action }, locale);
+    }
+    const node = wf.nodes.find((n) => n.id === step.node_id);
+    const items = await loadOpenWorkitems(client, step.id);
+    const mine = findMyWorkitem(items, subject);
+    const isOriginator = subject !== undefined && subject.id === inst.originator;
+    const enterCtx = { def, recordKey, wf, now, locale, prevStepId: step.id };
+    if (action === WORKFLOW_ACTIONS.APPROVE || action === WORKFLOW_ACTIONS.REJECT || action === WORKFLOW_ACTIONS.FORWARD) {
+        if (subject !== undefined && mine === undefined) {
+            throw new SchemaError('workflow.transition.denied', { object: def.name, role: subject.roles.join(','), action }, locale);
+        }
+        if (action === WORKFLOW_ACTIONS.FORWARD) {
+            const to = payload?.to?.userId;
+            if (typeof to !== 'string' || to.length === 0 || mine === undefined) {
+                throw new SchemaError('workflow.transition.unknown', { object: def.name, action }, locale);
+            }
+            await client.query(`UPDATE ${q(T.WORKFLOW_WORKITEMS)}
+           SET state = 'transferred', action = 'forward', finisher = $2, delegant = $2, receiptor = $3, comment = $4, finished_at = $5
+         WHERE id = $1`, [mine.id, actor, to, commentOf(payload), now]);
+            const alreadyOpen = await client.query(`SELECT 1 FROM ${q(T.WORKFLOW_WORKITEMS)}
+          WHERE step_id = $1 AND participant = $2 AND kind = 'approve' AND state = 'active' LIMIT 1`, [step.id, to]);
+            if ((alreadyOpen.rowCount ?? 0) === 0) {
+                await insertWorkitem(client, {
+                    object: def.name,
+                    recordKey,
+                    stepId: step.id,
+                    nodeId: step.node_id,
+                    kind: 'approve',
+                    participant: to,
+                    state: 'active',
+                    delegant: actor,
+                });
+            }
+            return { state: 'running', nodeId: step.node_id, fromNodeId: step.node_id, toNodeId: step.node_id };
+        }
+        const approval = action === WORKFLOW_ACTIONS.APPROVE ? 'approved' : 'rejected';
+        if (mine !== undefined) {
+            await closeWorkitem(client, mine.id, { state: 'done', approval, action, finisher: actor, comment: commentOf(payload) }, now);
+        }
+        if (action === WORKFLOW_ACTIONS.REJECT) {
+            await cancelOpenWorkitems(client, step.id, now);
+            await closeStep(client, step.id, 'finished', 'rejected', now);
+            return rollbackTo(client, enterCtx, node, step.id, WORKFLOW_ACTIONS.REJECT, actor, now);
+        }
+        // approve: evaluate the node quorum
+        const mode = node?.assign.mode ?? 'any';
+        const remaining = (await loadOpenWorkitems(client, step.id)).filter((w) => w.kind === 'approve');
+        const quorumMet = mode === 'all' ? remaining.length === 0 : true;
+        if (!quorumMet) {
+            return { state: 'running', nodeId: step.node_id, fromNodeId: step.node_id, toNodeId: step.node_id };
+        }
+        await cancelOpenWorkitems(client, step.id, now);
+        await closeStep(client, step.id, 'finished', 'approved', now);
+        const idx = node === undefined ? wf.nodes.length : nodeIndexOf(wf, node.id);
+        const entered = await enterNode(client, enterCtx, idx + 1);
+        if ('finished' in entered) {
+            await updateInstance(client, def.name, recordKey, { state: 'finished', approval: 'approved', finished_at: now, current_step_id: null });
+            await mirrorSide(client, def.name, recordKey, 'finished', actor, now);
+            return { state: 'finished', fromNodeId: step.node_id };
+        }
+        await updateInstance(client, def.name, recordKey, { current_step_id: entered.stepId });
+        await mirrorSide(client, def.name, recordKey, 'running', actor, now);
+        return { state: 'running', nodeId: entered.nodeId, fromNodeId: step.node_id, toNodeId: entered.nodeId };
+    }
+    if (action === WORKFLOW_ACTIONS.WITHDRAW || action === WORKFLOW_ACTIONS.CANCEL) {
+        if (subject !== undefined && !isOriginator && mine === undefined) {
+            throw new SchemaError('workflow.transition.denied', { object: def.name, role: subject.roles.join(','), action }, locale);
+        }
+        await assertNoForeignLock(client, def.name, recordKey, actor, locale);
+        if (action === WORKFLOW_ACTIONS.CANCEL) {
+            await cancelOpenWorkitems(client, step.id, now);
+            await closeStep(client, step.id, 'canceled', 'canceled', now);
+            await updateInstance(client, def.name, recordKey, { state: 'canceled', approval: 'rejected', finished_at: now, current_step_id: null });
+            await mirrorSide(client, def.name, recordKey, 'canceled', actor, now);
+            return { state: 'canceled', fromNodeId: step.node_id };
+        }
+        await cancelOpenWorkitems(client, step.id, now);
+        await closeStep(client, step.id, 'finished', 'withdrawn', now);
+        return rollbackTo(client, enterCtx, node, step.id, WORKFLOW_ACTIONS.WITHDRAW, actor, now);
+    }
+    throw new SchemaError('workflow.transition.unknown', { object: def.name, action }, locale);
+}
+/** roll back to a node (or the start node) after reject/withdraw */
+async function rollbackTo(client, ctx, node, fromStepId, action, actor, now) {
+    const targetId = (action === WORKFLOW_ACTIONS.REJECT ? node?.onReject : node?.onWithdraw) ?? undefined;
+    if (targetId === undefined) {
+        const stepId = await enterStart(client, ctx);
+        await updateInstance(client, ctx.def.name, ctx.recordKey, { current_step_id: stepId, state: 'running' });
+        await mirrorSide(client, ctx.def.name, ctx.recordKey, 'running', actor, now);
+        return { state: 'running', nodeId: WORKFLOW_START_NODE, fromNodeId: node?.id, toNodeId: WORKFLOW_START_NODE };
+    }
+    const idx = nodeIndexOf(ctx.wf, targetId);
+    const entered = await enterNode(client, ctx, idx);
+    if ('finished' in entered) {
+        await updateInstance(client, ctx.def.name, ctx.recordKey, { state: 'finished', finished_at: now, current_step_id: null });
+        await mirrorSide(client, ctx.def.name, ctx.recordKey, 'finished', actor, now);
+        return { state: 'finished', fromNodeId: node?.id };
+    }
+    await updateInstance(client, ctx.def.name, ctx.recordKey, { current_step_id: entered.stepId, state: 'running' });
+    await mirrorSide(client, ctx.def.name, ctx.recordKey, 'running', actor, now);
+    return { state: 'running', nodeId: entered.nodeId, fromNodeId: node?.id, toNodeId: entered.nodeId };
+}
+function commentOf(payload) {
+    const comment = payload?.comment;
+    return typeof comment === 'string' && comment.length > 0 ? comment : null;
+}
+/** presence-lock TTL (seconds) — matches the frontend heartbeat convention */
+export const WORKFLOW_LOCK_TTL_SECONDS = 60;
+/**
+ * Read a record's workflow status (no locking): instance state, current node
+ * and the actions available to `subject`. Used by the REST/MCP read surface.
+ */
+export async function getWorkflowStatus(client, def, recordKey, subject) {
+    const instRes = await client.query(`SELECT state, approval, current_step_id, originator FROM ${q(T.WORKFLOW_INSTANCES)}
+      WHERE object = $1 AND record_key = $2`, [def.name, recordKey]);
+    const inst = instRes.rows[0];
+    if (inst === undefined) {
+        return { state: 'draft', actions: subject === undefined ? [] : [WORKFLOW_ACTIONS.SUBMIT], workitems: [] };
+    }
+    if (inst.state !== 'running') {
+        return {
+            state: inst.state,
+            approval: inst.approval,
+            actions: [],
+            workitems: [],
+        };
+    }
+    const stepRes = await client.query(`SELECT node_id, kind FROM ${q(T.WORKFLOW_STEPS)} WHERE id = $1`, [inst.current_step_id]);
+    const step = stepRes.rows[0];
+    const openRes = await client.query(`SELECT id, node_id, kind, state, participant FROM ${q(T.WORKFLOW_WORKITEMS)}
+      WHERE step_id = $1 AND kind = 'approve' AND state = 'active'`, [inst.current_step_id]);
+    const open = openRes.rows;
+    const mine = subject === undefined ? [] : open.filter((w) => w.participant === subject.id);
+    const isOriginator = subject !== undefined && subject.id === inst.originator;
+    const actions = [];
+    if (subject !== undefined) {
+        if (step?.node_id === WORKFLOW_START_NODE) {
+            actions.push(WORKFLOW_ACTIONS.SUBMIT);
+        }
+        else {
+            if (mine.length > 0)
+                actions.push(WORKFLOW_ACTIONS.APPROVE, WORKFLOW_ACTIONS.REJECT, WORKFLOW_ACTIONS.FORWARD);
+            if (mine.length > 0 || isOriginator)
+                actions.push(WORKFLOW_ACTIONS.WITHDRAW);
+        }
+        if (isOriginator)
+            actions.push(WORKFLOW_ACTIONS.CANCEL);
+    }
+    return {
+        state: 'running',
+        ...(step === undefined ? {} : { node: step.node_id }),
+        approval: inst.approval,
+        actions,
+        workitems: mine,
+    };
+}
+/** acquire/renew the caller's presence lock on the current step (TTL lease) */
+export async function acquireWorkflowLock(client, def, recordKey, subject, locale) {
+    if (subject === undefined) {
+        throw new SchemaError('workflow.transition.denied', { object: def.name, role: '', action: 'lock' }, locale);
+    }
+    const instRes = await client.query(`SELECT current_step_id FROM ${q(T.WORKFLOW_INSTANCES)} WHERE object = $1 AND record_key = $2 AND state = 'running'`, [def.name, recordKey]);
+    const stepId = instRes.rows[0]?.current_step_id ?? null;
+    if (stepId === null) {
+        throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action: 'lock' }, locale);
+    }
+    const wi = await client.query(`SELECT id FROM ${q(T.WORKFLOW_WORKITEMS)}
+      WHERE step_id = $1 AND participant = $2 AND kind = 'approve' AND state = 'active' LIMIT 1`, [stepId, subject.id]);
+    const workitemId = wi.rows[0]?.id;
+    if (workitemId === undefined) {
+        throw new SchemaError('workflow.transition.denied', { object: def.name, role: subject.roles.join(','), action: 'lock' }, locale);
+    }
+    const res = await client.query(`INSERT INTO ${q(T.WORKFLOW_LOCKS)} (workitem_id, object, record_key, holder, acquired_at, expires_at)
+     VALUES ($1, $2, $3, $4, now(), now() + ($5 || ' seconds')::interval)
+     ON CONFLICT (workitem_id) DO UPDATE SET holder = EXCLUDED.holder, acquired_at = now(), expires_at = EXCLUDED.expires_at
+     RETURNING expires_at`, [workitemId, def.name, recordKey, subject.id, String(WORKFLOW_LOCK_TTL_SECONDS)]);
+    return { expiresAt: res.rows[0].expires_at };
+}
+/** release the caller's presence lock (and drop any expired locks for the record) */
+export async function releaseWorkflowLock(client, def, recordKey, subject) {
+    await client.query(`DELETE FROM ${q(T.WORKFLOW_LOCKS)} WHERE object = $1 AND record_key = $2 AND (holder = $3 OR expires_at <= now())`, [
+        def.name,
+        recordKey,
+        subject?.id ?? '',
+    ]);
+}
+/** read a record's workflow history (steps + workitems), oldest first */
+export async function getWorkflowHistory(client, def, recordKey) {
+    const inst = await client.query(`SELECT state, approval FROM ${q(T.WORKFLOW_INSTANCES)} WHERE object = $1 AND record_key = $2`, [def.name, recordKey]);
+    const instRow = inst.rows[0];
+    const steps = await client.query(`SELECT id, node_id, kind, ordinal, state, approval, entered_at, finished_at
+       FROM ${q(T.WORKFLOW_STEPS)} WHERE object = $1 AND record_key = $2 ORDER BY ordinal`, [def.name, recordKey]);
+    const items = await client.query(`SELECT id, step_id, node_id, kind, participant, state, approval, action, finisher, delegant, receiptor, comment, received_at, finished_at, allowed_at
+       FROM ${q(T.WORKFLOW_WORKITEMS)} WHERE object = $1 AND record_key = $2 ORDER BY received_at`, [def.name, recordKey]);
+    return {
+        state: instRow?.state ?? 'draft',
+        approval: instRow?.approval ?? null,
+        steps: steps.rows.map((r) => ({
+            id: String(r.id),
+            nodeId: String(r.node_id),
+            kind: String(r.kind),
+            ordinal: Number(r.ordinal),
+            state: String(r.state),
+            approval: r.approval ?? null,
+            enteredAt: r.entered_at,
+            finishedAt: r.finished_at ?? null,
+        })),
+        workitems: items.rows.map((r) => ({
+            id: String(r.id),
+            stepId: String(r.step_id),
+            nodeId: String(r.node_id),
+            kind: String(r.kind),
+            participant: String(r.participant),
+            state: String(r.state),
+            approval: r.approval ?? null,
+            action: r.action ?? null,
+            finisher: r.finisher ?? null,
+            delegant: r.delegant ?? null,
+            receiptor: r.receiptor ?? null,
+            comment: r.comment ?? null,
+            receivedAt: r.received_at,
+            finishedAt: r.finished_at ?? null,
+            allowedAt: r.allowed_at ?? null,
+        })),
+    };
+}
+/** the subject's pending workitems across all objects (`approve` items awaiting action) */
+export async function getWorkflowTodos(client, subject) {
+    if (subject === undefined)
+        return [];
+    const res = await client.query(`SELECT object, record_key, id, node_id, kind, state
+       FROM ${q(T.WORKFLOW_WORKITEMS)}
+      WHERE participant = $1 AND kind = 'approve' AND state = 'active'
+      ORDER BY received_at`, [subject.id]);
+    return res.rows.map((r) => ({
+        object: String(r.object),
+        recordKey: String(r.record_key),
+        workitemId: String(r.id),
+        nodeId: String(r.node_id),
+        kind: String(r.kind),
+        state: String(r.state),
+    }));
+}
+/**
+ * Fire a node's `onTimeout` action (system actor): approve advances, reject
+ * rolls back. Stale timers (the record already left the node) are ignored.
+ * Returns the node the record is now at so the caller can re-arm the timer.
+ */
+export async function advanceOnTimeout(client, def, recordKey, nodeId, action, locale) {
+    const now = new Date();
+    const inst = await loadInstance(client, def.name, recordKey);
+    if (inst === undefined || inst.state !== 'running')
+        return { state: 'running' };
+    const step = await loadActiveStep(client, inst.current_step_id);
+    if (step === undefined || step.node_id !== nodeId)
+        return { state: 'running' };
+    const wf = await resolveDefinition(client, def, inst.workflow_hash, locale);
+    const node = wf.nodes.find((n) => n.id === step.node_id);
+    const ctx = { def, recordKey, wf, now, locale, prevStepId: step.id };
+    if (action === 'reject') {
+        await cancelOpenWorkitems(client, step.id, now);
+        await closeStep(client, step.id, 'finished', 'rejected', now);
+        const outcome = await rollbackTo(client, ctx, node, step.id, WORKFLOW_ACTIONS.REJECT, 'system', now);
+        return { state: 'running', ...(outcome.nodeId === undefined ? {} : { nodeId: outcome.nodeId }) };
+    }
+    await cancelOpenWorkitems(client, step.id, now);
+    await closeStep(client, step.id, 'finished', 'approved', now);
+    const idx = node === undefined ? wf.nodes.length : nodeIndexOf(wf, node.id);
+    const entered = await enterNode(client, ctx, idx + 1);
+    if ('finished' in entered) {
+        await updateInstance(client, def.name, recordKey, {
+            state: 'finished',
+            approval: 'approved',
+            finished_at: now,
+            current_step_id: null,
+        });
+        await mirrorSide(client, def.name, recordKey, 'finished', 'system', now);
+        return { state: 'finished' };
+    }
+    await updateInstance(client, def.name, recordKey, { current_step_id: entered.stepId, state: 'running' });
+    await mirrorSide(client, def.name, recordKey, 'running', 'system', now);
+    return { state: 'running', nodeId: entered.nodeId };
+}
+/**
+ * Admin override: jump a record to a node, or terminate it. Admin-only
+ * (`WORKFLOW_ADMIN_ROLE`); unlike `reactivate` it also applies to a running
+ * instance.
+ */
+export async function overrideWorkflow(client, def, recordKey, patch, subject, locale) {
+    if (!isWorkflowAdmin(subject)) {
+        throw new SchemaError('workflow.transition.denied', { object: def.name, role: subject?.roles.join(',') ?? '', action: 'override' }, locale);
+    }
+    const now = new Date();
+    const actor = subject?.id ?? 'system';
+    const inst = await loadInstance(client, def.name, recordKey);
+    if (inst === undefined) {
+        throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action: 'override' }, locale);
+    }
+    const wf = await resolveDefinition(client, def, inst.workflow_hash, locale);
+    const step = await loadActiveStep(client, inst.current_step_id);
+    const ctx = { def, recordKey, wf, now, locale, prevStepId: step?.id ?? null };
+    if (patch.node !== undefined) {
+        const idx = wf.nodes.findIndex((n) => n.id === patch.node);
+        if (idx < 0)
+            throw new SchemaError('workflow.node.unknown', { object: def.name, node: patch.node }, locale);
+        if (step !== undefined) {
+            await cancelOpenWorkitems(client, step.id, now);
+            await closeStep(client, step.id, 'finished', null, now);
+        }
+        const entered = await enterNode(client, ctx, idx);
+        if ('finished' in entered) {
+            await updateInstance(client, def.name, recordKey, { state: 'finished', approval: 'approved', finished_at: now, current_step_id: null });
+            await mirrorSide(client, def.name, recordKey, 'finished', actor, now);
+            return { state: 'finished' };
+        }
+        await updateInstance(client, def.name, recordKey, { state: 'running', current_step_id: entered.stepId, approval: null, finished_at: null });
+        await mirrorSide(client, def.name, recordKey, 'running', actor, now);
+        return { state: 'running', nodeId: entered.nodeId };
+    }
+    if (patch.state === 'canceled' || patch.state === 'finished') {
+        if (step !== undefined) {
+            await cancelOpenWorkitems(client, step.id, now);
+            await closeStep(client, step.id, patch.state === 'canceled' ? 'canceled' : 'finished', patch.state === 'canceled' ? 'canceled' : 'approved', now);
+        }
+        await updateInstance(client, def.name, recordKey, {
+            state: patch.state,
+            approval: patch.state === 'finished' ? 'approved' : 'rejected',
+            finished_at: now,
+            current_step_id: null,
+        });
+        await mirrorSide(client, def.name, recordKey, patch.state, actor, now);
+        return { state: patch.state };
+    }
+    throw new SchemaError('workflow.transition.notAllowed', { object: def.name, action: 'override' }, locale);
+}
+//# sourceMappingURL=workflow.js.map