@gobing-ai/ts-dual-workflow-engine 0.3.16 → 0.3.18

package/dist/persistence.js

@@ -11,17 +11,28 @@ export async function applyWorkflowEngineSchema(db) {
 /** SQLite/D1-compatible workflow persistence adapter backed by ts-db. */
 export class DbWorkflowPersistenceAdapter {
     db;
+    /** Memoized schema-ensure; the DDL runs at most once per adapter instance. */
+    schemaReady;
     constructor(db) {
         this.db = db;
     }
+    /**
+     * Apply the workflow-engine schema once per adapter, latching the in-flight
+     * promise so concurrent first calls share a single DDL pass. Every public
+     * read/write awaits this instead of re-running the idempotent DDL per call.
+     */
+    ensureSchema() {
+        this.schemaReady ??= applyWorkflowEngineSchema(this.db);
+        return this.schemaReady;
+    }
     /** Create a run row, rejecting duplicate run ids. */
     async createRun(record) {
         const existing = await this.loadRun(record.id);
         if (existing !== undefined)
             throw new RunCollisionError(record.id);
-        await applyWorkflowEngineSchema(this.db);
-        await this.db.run(`INSERT INTO runs (id, workflow_name, mode, status, started_at, completed_at, metadata_json, created_at, updated_at)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, record.id, record.workflow_name, record.mode, record.status, record.started_at, record.completed_at, record.metadata_json, Date.now(), Date.now());
+        await this.ensureSchema();
+        await this.db.run(`INSERT INTO runs (id, workflow_name, mode, status, external_key, started_at, completed_at, metadata_json, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, record.id, record.workflow_name, record.mode, record.status, record.external_key ?? null, record.started_at, record.completed_at, record.metadata_json, Date.now(), Date.now());
     }
     /** Finalize a run with terminal status and timestamp. */
     async finalizeRun(runId, status, completedAt) {
@@ -62,15 +73,71 @@ export class DbWorkflowPersistenceAdapter {
     }
     /** Load a single run by id. */
     async loadRun(runId) {
-        await applyWorkflowEngineSchema(this.db);
+        await this.ensureSchema();
         const row = await this.db.queryFirst('SELECT * FROM runs WHERE id = ?', runId);
         return row ?? undefined;
     }
     /** List persisted workflow runs. */
     async listRuns() {
-        await applyWorkflowEngineSchema(this.db);
+        await this.ensureSchema();
         return await this.db.queryAll('SELECT * FROM runs ORDER BY started_at DESC');
     }
+    /** Look up a run by its external key within a workflow definition. */
+    async findRunByKey(workflowName, externalKey) {
+        await this.ensureSchema();
+        const row = await this.db.queryFirst('SELECT * FROM runs WHERE workflow_name = ? AND external_key = ?', workflowName, externalKey);
+        return row ?? undefined;
+    }
+    /** Create a run or attach to an existing one by external key. */
+    async createOrAttachRun(record) {
+        await this.ensureSchema();
+        if (record.external_key) {
+            const existing = await this.findRunByKey(record.workflow_name, record.external_key);
+            if (existing)
+                return existing;
+        }
+        try {
+            await this.createRun(record);
+        }
+        catch (error) {
+            if (record.external_key) {
+                const existing = await this.findRunByKey(record.workflow_name, record.external_key);
+                if (existing)
+                    return existing;
+            }
+            throw error;
+        }
+        return { ...record };
+    }
+    /** Force-set the current state of a run (reseed). */
+    async reseedRun(runId, newState) {
+        const now = Date.now();
+        await this.ensureSchema();
+        const previous = await this.db.queryFirst('SELECT state FROM workflow_states WHERE run_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1', runId);
+        await this.saveWorkflowState(runId, newState, { reseeded: true, reseededAt: new Date(now).toISOString() });
+        await this.saveTransition(runId, previous?.state ?? '', newState, '__reseed__');
+        return { fromState: previous?.state ?? null, toState: newState };
+    }
+    /** Load the current state name for a run. */
+    async loadCurrentState(runId) {
+        await this.ensureSchema();
+        const row = await this.db.queryFirst('SELECT state FROM workflow_states WHERE run_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1', runId);
+        return row?.state;
+    }
+    /** List runs with status 'paused'. Ordered most-recent-first. */
+    async listPausedRuns(options) {
+        await this.ensureSchema();
+        const where = ["status = 'paused'"];
+        const params = [];
+        if (options?.workflowName !== undefined) {
+            where.push('workflow_name = ?');
+            params.push(options.workflowName);
+        }
+        const limit = options?.limit ?? 100;
+        const sql = `SELECT * FROM runs WHERE ${where.join(' AND ')} ORDER BY updated_at DESC, rowid DESC LIMIT ?`;
+        params.push(limit);
+        return await this.db.queryAll(sql, ...params);
+    }
 }
 /** In-memory persistence adapter for tests and embedding. */
 export class MemoryWorkflowPersistenceAdapter {
@@ -136,4 +203,44 @@ export class MemoryWorkflowPersistenceAdapter {
     async listRuns() {
         return [...this.runs.values()];
     }
+    /** Look up a run by its external key within a workflow definition. */
+    async findRunByKey(workflowName, externalKey) {
+        for (const run of this.runs.values()) {
+            if (run.workflow_name === workflowName && run.external_key === externalKey)
+                return run;
+        }
+        return undefined;
+    }
+    /** Create a run or attach to an existing one by external key. */
+    async createOrAttachRun(record) {
+        if (record.external_key) {
+            const existing = await this.findRunByKey(record.workflow_name, record.external_key);
+            if (existing)
+                return existing;
+        }
+        await this.createRun(record);
+        return { ...record };
+    }
+    /** Force-set the current state of a run (reseed). */
+    async reseedRun(runId, newState) {
+        const previous = this.states.findLast((state) => state.runId === runId);
+        await this.saveWorkflowState(runId, newState, { reseeded: true, reseededAt: new Date().toISOString() });
+        await this.saveTransition(runId, previous?.state ?? '', newState, '__reseed__');
+        return { fromState: previous?.state ?? null, toState: newState };
+    }
+    /** Load the current state name for a run. */
+    async loadCurrentState(runId) {
+        const last = this.states.findLast((s) => s.runId === runId);
+        return last?.state;
+    }
+    /** List runs with status 'paused'. Ordered most-recent-first. */
+    async listPausedRuns(options) {
+        let runs = [...this.runs.values()].filter((r) => r.status === 'paused');
+        if (options?.workflowName !== undefined) {
+            runs = runs.filter((r) => r.workflow_name === options.workflowName);
+        }
+        // Memory adapter has no updated_at tracking; use insertion order (reverse = most-recent-first).
+        runs.reverse();
+        return runs.slice(0, options?.limit ?? 100);
+    }
 }

package/dist/run-lifecycle.d.ts

@@ -27,17 +27,32 @@ export declare class RunLifecycle {
     private readonly workflowName;
     private readonly mode;
     readonly runId: string;
+    readonly externalKey?: string;
     private readonly persistence;
     private readonly events;
     private readonly logger;
-    private readonly startedAt;
     private constructor();
+    /**
+     * Build a lifecycle for an external, single-hop transition request — NOT a run.
+     * Unlike {@link run} / {@link resume} this opens no `workflow.run` span and
+     * creates no run record: an external transition is one guarded hop on an
+     * already-existing run, so it must not masquerade as a run in traces. It exists
+     * only to let {@link WorkflowService.requestTransition} reuse {@link recordTransition}
+     * and {@link guardEvaluated} so the transition persist+emit mechanics live in one
+     * place instead of being hand-rolled at the service layer.
+     */
+    static forExternalTransition(workflowName: string, runId: string, deps: RunLifecycleDeps, externalKey: string | undefined): RunLifecycle;
     /**
      * Create the run record and execute `loop` inside the run's OTel span. The
      * driver's control loop is the body; it receives this lifecycle to drive
      * per-step persistence and terminal results.
      */
     static run(workflowName: string, mode: WorkflowMode, deps: RunLifecycleDeps, options: WorkflowRunOptions, loop: (lifecycle: RunLifecycle) => Promise<WorkflowRunResult>): Promise<WorkflowRunResult>;
+    /**
+     * Resume an existing run without creating a new record. Used by driver resume paths.
+     * The caller is responsible for ensuring the run exists and emitting the resumed event.
+     */
+    static resume(workflowName: string, mode: WorkflowMode, deps: RunLifecycleDeps, runId: string, externalKey: string | undefined, loop: (lifecycle: RunLifecycle) => Promise<WorkflowRunResult>): Promise<WorkflowRunResult>;
     /** Persist the current state/node snapshot and mark its phase running. */
     enter(stateOrNodeId: string, transitionsTaken: number): Promise<void>;
     /** Persist a transition and emit its observability event. */
@@ -46,6 +61,10 @@ export declare class RunLifecycle {
     done(finalState: string, transitionsTaken: number): Promise<WorkflowRunResult>;
     /** Finalize the run as failed and return its result. */
     fail(finalState: string, transitionsTaken: number, reason?: string): Promise<WorkflowRunResult>;
+    /** Finalize the run as paused and return its result. */
+    pause(stateOrNodeId: string, transitionsTaken: number): Promise<WorkflowRunResult>;
+    /** Emit the resumed event (called by WorkflowService after re-creating a lifecycle for resume). */
+    emitResumed(node: string): void;
     /** Emit action-level observability before a host action is invoked. */
     actionStart(stateOrNodeId: string, kind: string): void;
     /** Emit action-level observability after a host action settles. */
@@ -59,6 +78,6 @@ export declare class RunLifecycle {
     /** Emit when an interactive HITL prompt resolves. */
     hitlResponse(node: string, ok: boolean): void;
     private result;
-    private runRecord;
+    private static runRecord;
 }
 //# sourceMappingURL=run-lifecycle.d.ts.map

package/dist/run-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-lifecycle.d.ts","sourceRoot":"","sources":["../src/run-lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-lifecycle.d.ts","sourceRoot":"","sources":["../src/run-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/run-lifecycle.js

@@ -38,44 +38,76 @@ export class RunLifecycle {
     workflowName;
     mode;
     runId;
+    externalKey;
     persistence;
     events;
     logger;
-    startedAt;
-    constructor(runId, workflowName, mode, deps) {
+    constructor(runId, workflowName, mode, deps, externalKey) {
         this.workflowName = workflowName;
         this.mode = mode;
         this.runId = runId;
+        this.externalKey = externalKey;
         this.persistence = deps.persistence;
         this.events = deps.events;
-        this.startedAt = new Date().toISOString();
         this.logger = (deps.logger ?? getLogger('workflow')).child({ runId, workflow: workflowName, mode });
     }
+    /**
+     * Build a lifecycle for an external, single-hop transition request — NOT a run.
+     * Unlike {@link run} / {@link resume} this opens no `workflow.run` span and
+     * creates no run record: an external transition is one guarded hop on an
+     * already-existing run, so it must not masquerade as a run in traces. It exists
+     * only to let {@link WorkflowService.requestTransition} reuse {@link recordTransition}
+     * and {@link guardEvaluated} so the transition persist+emit mechanics live in one
+     * place instead of being hand-rolled at the service layer.
+     */
+    static forExternalTransition(workflowName, runId, deps, externalKey) {
+        return new RunLifecycle(runId, workflowName, 'state-machine', deps, externalKey);
+    }
     /**
      * Create the run record and execute `loop` inside the run's OTel span. The
      * driver's control loop is the body; it receives this lifecycle to drive
      * per-step persistence and terminal results.
      */
     static async run(workflowName, mode, deps, options, loop) {
-        const runId = options.runId ?? crypto.randomUUID();
-        const lifecycle = new RunLifecycle(runId, workflowName, mode, deps);
         return await traceAsync('workflow.run', async () => {
-            await lifecycle.persistence.createRun(lifecycle.runRecord(options.metadata));
+            const startedAt = new Date().toISOString();
+            const proposed = RunLifecycle.runRecord(options.runId ?? crypto.randomUUID(), workflowName, mode, startedAt, options.metadata, options.externalKey);
+            let record = proposed;
+            if (options.externalKey === undefined) {
+                await deps.persistence.createRun(proposed);
+            }
+            else {
+                record = await deps.persistence.createOrAttachRun(proposed);
+            }
+            const extKey = record.external_key ?? undefined;
+            const lifecycle = new RunLifecycle(record.id, workflowName, mode, deps, extKey);
             lifecycle.logger.info('workflow run started');
             addSpanEvent('workflow.run.started', {
                 workflowName,
                 mode,
-                runId,
+                runId: lifecycle.runId,
                 dryRun: options.dryRun ?? false,
             });
             void lifecycle.events?.emit('workflow.run.started', {
                 workflowName,
                 mode,
-                runId,
+                runId: lifecycle.runId,
                 dryRun: options.dryRun ?? false,
+                externalKey: extKey,
             });
             return await loop(lifecycle);
-        }, { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode, 'workflow.run_id': runId } });
+        }, { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode } });
+    }
+    /**
+     * Resume an existing run without creating a new record. Used by driver resume paths.
+     * The caller is responsible for ensuring the run exists and emitting the resumed event.
+     */
+    static async resume(workflowName, mode, deps, runId, externalKey, loop) {
+        return await traceAsync('workflow.run', async () => {
+            const lifecycle = new RunLifecycle(runId, workflowName, mode, deps, externalKey);
+            lifecycle.logger.info('workflow run resumed');
+            return await loop(lifecycle);
+        }, { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode } });
     }
     /** Persist the current state/node snapshot and mark its phase running. */
     async enter(stateOrNodeId, transitionsTaken) {
@@ -106,6 +138,7 @@ export class RunLifecycle {
             from,
             to,
             trigger,
+            externalKey: this.externalKey,
         });
     }
     /** Finalize the run as succeeded and return its result. */
@@ -114,7 +147,12 @@ export class RunLifecycle {
         await this.persistence.finalizeRun(this.runId, 'done', new Date().toISOString());
         this.logger.info('workflow run done', { finalState, transitionsTaken });
         addSpanEvent('workflow.run.done', { runId: this.runId, finalState, transitionsTaken });
-        void this.events?.emit('workflow.run.done', { runId: this.runId, finalState, transitionsTaken });
+        void this.events?.emit('workflow.run.done', {
+            runId: this.runId,
+            finalState,
+            transitionsTaken,
+            externalKey: this.externalKey,
+        });
         return this.result('done', finalState, transitionsTaken);
     }
     /** Finalize the run as failed and return its result. */
@@ -122,10 +160,34 @@ export class RunLifecycle {
         await this.persistence.savePhase(this.runId, finalState, 'failed');
         await this.persistence.finalizeRun(this.runId, 'failed', new Date().toISOString());
         addSpanEvent('workflow.run.failed', { runId: this.runId, finalState, reason });
-        void this.events?.emit('workflow.run.failed', { runId: this.runId, finalState, reason });
+        void this.events?.emit('workflow.run.failed', {
+            runId: this.runId,
+            finalState,
+            reason,
+            externalKey: this.externalKey,
+        });
         this.logger.warn('workflow run failed', { finalState, transitionsTaken, reason });
         return this.result('failed', finalState, transitionsTaken, reason);
     }
+    /** Finalize the run as paused and return its result. */
+    async pause(stateOrNodeId, transitionsTaken) {
+        await this.persistence.savePhase(this.runId, stateOrNodeId, 'paused');
+        await this.persistence.finalizeRun(this.runId, 'paused', new Date().toISOString());
+        this.logger.info('workflow run paused', { stateOrNodeId, transitionsTaken });
+        addSpanEvent('workflow.run.paused', { runId: this.runId, node: stateOrNodeId, transitionsTaken });
+        void this.events?.emit('workflow.run.paused', {
+            runId: this.runId,
+            node: stateOrNodeId,
+            transitionsTaken,
+            externalKey: this.externalKey,
+        });
+        return this.result('paused', stateOrNodeId, transitionsTaken);
+    }
+    /** Emit the resumed event (called by WorkflowService after re-creating a lifecycle for resume). */
+    emitResumed(node) {
+        addSpanEvent('workflow.run.resumed', { runId: this.runId, node });
+        void this.events?.emit('workflow.run.resumed', { runId: this.runId, node, externalKey: this.externalKey });
+    }
     /** Emit action-level observability before a host action is invoked. */
     actionStart(stateOrNodeId, kind) {
         addSpanEvent('workflow.action.start', { runId: this.runId, node: stateOrNodeId, kind });
@@ -166,6 +228,7 @@ export class RunLifecycle {
             to,
             kind,
             passed,
+            externalKey: this.externalKey,
         });
     }
     /** Emit when an interactive HITL prompt is presented. */
@@ -187,15 +250,16 @@ export class RunLifecycle {
             ...(reason === undefined ? {} : { reason }),
         };
     }
-    runRecord(metadata) {
+    static runRecord(runId, workflowName, mode, startedAt, metadata, externalKey) {
         return {
-            id: this.runId,
-            workflow_name: this.workflowName,
-            mode: this.mode,
+            id: runId,
+            workflow_name: workflowName,
+            mode,
             status: 'running',
-            started_at: this.startedAt,
+            started_at: startedAt,
             metadata_json: JSON.stringify(metadata ?? {}),
             completed_at: null,
+            external_key: externalKey ?? null,
         };
     }
 }

package/dist/schema-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-sql.d.ts","sourceRoot":"","sources":["../src/schema-sql.ts"],"names":[],"mappings":"AAAA,6IAA6I;AAC7I,eAAO,MAAM,0BAA0B,QA8D/B,CAAC"}
+{"version":3,"file":"schema-sql.d.ts","sourceRoot":"","sources":["../src/schema-sql.ts"],"names":[],"mappings":"AAAA,6IAA6I;AAC7I,eAAO,MAAM,0BAA0B,QAmE/B,CAAC"}

package/dist/schema-sql.js

@@ -6,6 +6,7 @@ CREATE TABLE IF NOT EXISTS runs (
     mode TEXT,
     status TEXT NOT NULL,
     agent TEXT,
+    external_key TEXT,
     started_at TEXT NOT NULL,
     completed_at TEXT,
     metadata_json TEXT NOT NULL DEFAULT '{}',
@@ -13,6 +14,10 @@ CREATE TABLE IF NOT EXISTS runs (
     updated_at INTEGER NOT NULL DEFAULT 0
 );
 
+CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_external_key
+    ON runs (workflow_name, external_key)
+    WHERE external_key IS NOT NULL;
+
 CREATE TABLE IF NOT EXISTS phase_runs (
     id TEXT PRIMARY KEY,
     run_id TEXT NOT NULL,

package/dist/schema.d.ts

@@ -50,6 +50,7 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strip>>>;
+        pause: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     transitions: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -97,6 +98,7 @@ export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strip>>;
+        pause: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     edges: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -145,6 +147,7 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strip>>>;
+        pause: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     transitions: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -190,6 +193,7 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strip>>;
+        pause: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     edges: z.ZodArray<z.ZodObject<{
         from: z.ZodString;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;;;;;iBAI1B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoC7B,CAAC;AAEd,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmC/B,CAAC;AAEd,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAA4E,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;;;;;iBAI1B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsC7B,CAAC;AAEd,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqC/B,CAAC;AAEd,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAA4E,CAAC"}

package/dist/schema.js

@@ -50,6 +50,8 @@ export const StateMachineWorkflowDefSchema = z
         description: z.string().optional(),
         onEnter: z.array(ActionDefSchema).optional(),
         onExit: z.array(ActionDefSchema).optional(),
+        /** When true, the engine pauses the run at this state instead of auto-advancing. */
+        pause: z.boolean().optional(),
     })
         .strict()),
     transitions: z.array(z
@@ -84,6 +86,8 @@ export const TransitionFlowWorkflowDefSchema = z
         description: z.string().optional(),
         type: z.enum(['action', 'gate', 'parallel', 'decision']).optional(),
         action: ActionDefSchema.optional(),
+        /** When true, the engine pauses the run at this node instead of auto-advancing. */
+        pause: z.boolean().optional(),
     })
         .strict()),
     edges: z.array(z

package/dist/service.d.ts

@@ -1,9 +1,11 @@
 import type { WorkflowEngineHost } from './host';
-import type { WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } from './types';
+import type { StateMachineWorkflowDef, TransitionRequestResult, WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunRecord, WorkflowRunResult } from './types';
 /** High-level workflow service for loading, running, and listing persisted workflow runs. */
 export declare class WorkflowService {
     private readonly host;
     private readonly persistence;
+    /** Per-run serialization: ensures concurrent requestTransition calls serialize. */
+    private readonly runLocks;
     constructor(host: WorkflowEngineHost, persistence: WorkflowPersistenceAdapter);
     /** Load a workflow file and validate it. */
     load(path: string): Promise<WorkflowDef>;
@@ -12,6 +14,38 @@ export declare class WorkflowService {
     /** Load and run a workflow file. */
     runFile(path: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
     /** List persisted workflow runs. */
-    listRuns(): Promise<readonly import("./types").WorkflowRunRecord[]>;
+    listRuns(): Promise<readonly WorkflowRunRecord[]>;
+    /** Find a run by its external key within a workflow definition. */
+    findRunByKey(workflowName: string, externalKey: string): Promise<WorkflowRunRecord | undefined>;
+    /** Create a new run or attach to an existing one identified by external key. */
+    createOrAttachRun(record: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+    /** Force-set the current state of a run (consumer-side authority reconciliation). */
+    reseedRun(workflow: WorkflowDef, runId: string, newState: string, options?: WorkflowRunOptions): Promise<void>;
+    reseedRun(runId: string, newState: string, options?: WorkflowRunOptions): Promise<void>;
+    /** Reject a reseed target the workflow definition does not allow (state-machine states only). */
+    private assertReseedTargetDeclared;
+    /** Persist the reseed and emit the corrective event with the run's external key. */
+    private commitReseed;
+    /** Resume a paused run, continuing execution from where it stopped. */
+    resumeRun(workflow: WorkflowDef, runId: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    /** List runs currently paused. Optional filters and ordering. */
+    listPausedRuns(options?: {
+        workflowName?: string;
+        limit?: number;
+    }): Promise<readonly WorkflowRunRecord[]>;
+    /**
+     * Request an external state transition on a run. Evaluates whether the
+     * transition exists and its guard passes; commits or denies atomically.
+     * Concurrent requests on the same run serialize — the loser re-evaluates
+     * against the new state.
+     */
+    requestTransition(workflow: StateMachineWorkflowDef, runId: string, toState: string, options?: WorkflowRunOptions): Promise<TransitionRequestResult>;
+    private evaluateAndCommit;
+    /**
+     * Build a `TransitionDenied` result and emit its `workflow.transition.denied`
+     * event in one place — the single denial seam for the external-transition path,
+     * so the event payload and the returned reason can never drift apart.
+     */
+    private denyTransition;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE9G,6FAA6F;AAC7F,qBAAa,eAAe;IAEpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,IAAI,EAAE,kBAAkB,EACxB,WAAW,EAAE,0BAA0B;IAG5D,4CAA4C;IACtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9C,iDAAiD;IAC3C,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAU9F,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzF,oCAAoC;IAC9B,QAAQ;CAGjB"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAIjD,OAAO,KAAK,EACR,uBAAuB,EAEvB,uBAAuB,EACvB,WAAW,EACX,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAEjB,6FAA6F;AAC7F,qBAAa,eAAe;IAKpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IALhC,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;gBAGxC,IAAI,EAAE,kBAAkB,EACxB,WAAW,EAAE,0BAA0B;IAG5D,4CAA4C;IACtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9C,iDAAiD;IAC3C,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAU9F,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzF,oCAAoC;IAC9B,QAAQ;IAId,mEAAmE;IAC7D,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIrG,gFAAgF;IAC1E,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI9E,qFAAqF;IAC/E,SAAS,CACX,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,IAAI,CAAC;IACV,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B7F,iGAAiG;IACjG,OAAO,CAAC,0BAA0B;IASlC,oFAAoF;YACtE,YAAY;IAY1B,uEAAuE;IACjE,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAgC/G,iEAAiE;IAC3D,cAAc,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC;IAIhH;;;;;OAKG;IACG,iBAAiB,CACnB,QAAQ,EAAE,uBAAuB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,uBAAuB,CAAC;YAsBrB,iBAAiB;IA4E/B;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAiBzB"}