@mantajs/core 0.1.7 → 0.2.0-beta.0

package/dist/workflows/define-workflow.js

@@ -0,0 +1,72 @@
+// defineWorkflow — Intra-module workflow definition.
+//
+// A workflow orchestrates multiple services WITHIN a module.
+// It has compensation (like defineCommand) but NO auth context — it's pure business logic.
+// It receives typed input via Zod and a scoped step proxy (only module entities).
+//
+// Called from commands via step.workflow.MODULE.NAME(input).
+//
+// Usage:
+//   // src/modules/customer/workflows/update-customer-with-address.ts
+//   export default defineWorkflow({
+//     name: 'update-customer-with-address',
+//     description: 'Update customer and their default address',
+//     input: z.object({
+//       id: z.string(),
+//       first_name: z.string().optional(),
+//       address: z.object({ city: z.string(), country: z.string() }).optional(),
+//     }),
+//     handler: async (input, { step }) => {
+//       if (input.first_name) {
+//         await step.service.customer.update(input.id, { first_name: input.first_name })
+//       }
+//       if (input.address) {
+//         await step.service.customerAddress.create({ customer_id: input.id, ...input.address })
+//       }
+//     },
+//   })
+import { MantaError } from '../errors/manta-error';
+/**
+ * Define an intra-module workflow — orchestrates multiple entity services within a module.
+ *
+ * Workflows have compensation (via step proxy) but NO auth context.
+ * They are called from commands via `step.workflow.MODULE.NAME(input)`.
+ *
+ * @example
+ * ```typescript
+ * // src/modules/customer/workflows/merge-customers.ts
+ * export default defineWorkflow({
+ *   name: 'merge-customers',
+ *   description: 'Merge two customer records into one',
+ *   input: z.object({ sourceId: z.string(), targetId: z.string() }),
+ *   handler: async (input, { step }) => {
+ *     // Move addresses from source to target
+ *     const addresses = await step.service.customerAddress.find({ customer_id: input.sourceId })
+ *     for (const addr of addresses) {
+ *       await step.service.customerAddress.update(addr.id, { customer_id: input.targetId })
+ *     }
+ *     // Delete source customer
+ *     await step.service.customer.delete(input.sourceId)
+ *     return { mergedInto: input.targetId }
+ *   },
+ * })
+ * ```
+ */
+export function defineWorkflow(config) {
+    if (!config.name)
+        throw new MantaError('INVALID_DATA', 'Workflow name is required');
+    if (!config.description)
+        throw new MantaError('INVALID_DATA', `Workflow "${config.name}" requires a description`);
+    if (!config.input)
+        throw new MantaError('INVALID_DATA', `Workflow "${config.name}" requires an input Zod schema`);
+    if (typeof config.handler !== 'function')
+        throw new MantaError('INVALID_DATA', `Workflow "${config.name}" handler must be a function`);
+    return {
+        __type: 'workflow',
+        name: config.name,
+        description: config.description,
+        input: config.input,
+        handler: config.handler,
+    };
+}
+//# sourceMappingURL=define-workflow.js.map

package/dist/workflows/define-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-workflow.js","sourceRoot":"","sources":["../../src/workflows/define-workflow.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,6DAA6D;AAC7D,2FAA2F;AAC3F,kFAAkF;AAClF,EAAE;AACF,6DAA6D;AAC7D,EAAE;AACF,SAAS;AACT,sEAAsE;AACtE,oCAAoC;AACpC,4CAA4C;AAC5C,gEAAgE;AAChE,wBAAwB;AACxB,wBAAwB;AACxB,2CAA2C;AAC3C,iFAAiF;AACjF,UAAU;AACV,4CAA4C;AAC5C,gCAAgC;AAChC,yFAAyF;AACzF,UAAU;AACV,6BAA6B;AAC7B,iGAAiG;AACjG,UAAU;AACV,SAAS;AACT,OAAO;AAGP,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAyBlD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,cAAc,CAAkB,MAK/C;IACC,IAAI,CAAC,MAAM,CAAC,IAAI;QAAE,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,2BAA2B,CAAC,CAAA;IACnF,IAAI,CAAC,MAAM,CAAC,WAAW;QAAE,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,aAAa,MAAM,CAAC,IAAI,0BAA0B,CAAC,CAAA;IACjH,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,aAAa,MAAM,CAAC,IAAI,gCAAgC,CAAC,CAAA;IACjH,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU;QACtC,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,aAAa,MAAM,CAAC,IAAI,8BAA8B,CAAC,CAAA;IAE9F,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAA;AACH,CAAC"}

package/dist/workflows/emit-event-step.d.ts

@@ -0,0 +1,17 @@
+import type { StepDefinition } from './types';
+export interface EmitEventStepInput {
+    eventName: string;
+    data: unknown | unknown[];
+    options?: {
+        priority?: number;
+    };
+}
+/**
+ * A workflow step that buffers events for emission after workflow success.
+ * Compatible with Medusa's emitEventStep API.
+ *
+ * Events are buffered via the workflow's event group (IEventBusPort grouped events).
+ * WorkflowManager releases the group on success, clears it on failure.
+ */
+export declare function emitEventStep(input: EmitEventStepInput): StepDefinition;
+//# sourceMappingURL=emit-event-step.d.ts.map

package/dist/workflows/emit-event-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-event-step.d.ts","sourceRoot":"","sources":["../../src/workflows/emit-event-step.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAsB,MAAM,SAAS,CAAA;AAEjE,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAAA;IACzB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,CAAA;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,cAAc,CA4BvE"}

package/dist/workflows/emit-event-step.js

@@ -0,0 +1,46 @@
+// SPEC-034 — emitEventStep: Medusa-compatible buffered event emission
+//
+// The event is only emitted after the workflow has finished successfully.
+// If the workflow fails, the event is NOT emitted at all.
+//
+// Uses IEventBusPort grouped events internally — events are buffered in the
+// event bus (Redis in prod) and released by WorkflowManager on success.
+//
+// Usage (same as Medusa):
+//   emitEventStep({ eventName: 'order.created', data: { id: '123' } })
+//
+// For immediate emission (not buffered), use:
+//   app.infra.eventBus.emit(event)  // direct
+/**
+ * A workflow step that buffers events for emission after workflow success.
+ * Compatible with Medusa's emitEventStep API.
+ *
+ * Events are buffered via the workflow's event group (IEventBusPort grouped events).
+ * WorkflowManager releases the group on success, clears it on failure.
+ */
+export function emitEventStep(input) {
+    const stepName = `emit-event:${input.eventName}`;
+    return {
+        name: stepName,
+        handler: async (ctx) => {
+            const dataArray = Array.isArray(input.data) ? input.data : [input.data];
+            for (const data of dataArray) {
+                const message = {
+                    eventName: input.eventName,
+                    data,
+                    metadata: {
+                        timestamp: Date.now(),
+                        source: 'workflow',
+                        idempotencyKey: `${ctx.context?.transactionId ?? 'unknown'}:emit:${input.eventName}`,
+                    },
+                };
+                // Buffer via __bufferEvent (WorkflowManager stores in grouped events)
+                if (ctx.context._bufferEvent) {
+                    ctx.context._bufferEvent(message);
+                }
+            }
+            return { eventName: input.eventName, buffered: dataArray.length };
+        },
+    };
+}
+//# sourceMappingURL=emit-event-step.js.map

package/dist/workflows/emit-event-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-event-step.js","sourceRoot":"","sources":["../../src/workflows/emit-event-step.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,0DAA0D;AAC1D,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,EAAE;AACF,0BAA0B;AAC1B,uEAAuE;AACvE,EAAE;AACF,8CAA8C;AAC9C,8CAA8C;AAa9C;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,QAAQ,GAAG,cAAc,KAAK,CAAC,SAAS,EAAE,CAAA;IAEhD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,KAAK,EAAE,GAAuB,EAAoB,EAAE;YAC3D,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAEvE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,MAAM,OAAO,GAAY;oBACvB,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,IAAI;oBACJ,QAAQ,EAAE;wBACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;wBACrB,MAAM,EAAE,UAAU;wBAClB,cAAc,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,aAAa,IAAI,SAAS,SAAS,KAAK,CAAC,SAAS,EAAE;qBACrF;iBACF,CAAA;gBAED,sEAAsE;gBACtE,IAAI,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;oBAC7B,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;gBACnC,CAAC;YACH,CAAC;YAED,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,CAAA;QACnE,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/workflows/for-each.d.ts

@@ -0,0 +1,6 @@
+import type { StepContext, WorkflowContext } from './types';
+/**
+ * Build a `ctx.forEach` function bound to a specific workflow run.
+ */
+export declare function createForEach(wfCtx: WorkflowContext): NonNullable<StepContext['forEach']>;
+//# sourceMappingURL=for-each.d.ts.map

package/dist/workflows/for-each.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"for-each.d.ts","sourceRoot":"","sources":["../../src/workflows/for-each.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAe,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAExE;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAyDzF"}

package/dist/workflows/for-each.js

@@ -0,0 +1,79 @@
+// ctx.forEach — ergonomic batching + progress + cancel for iterative steps.
+// See WORKFLOW_PROGRESS.md §6.4.
+//
+// Combines three concerns into one idiom:
+// 1. Batch items (array or AsyncIterable) into chunks of `batchSize`.
+// 2. Emit a progress snapshot after each batch completes (fire-and-forget).
+// 3. Check `ctx.signal` between batches; throw CancelledError if aborted.
+import { CancelledError } from './progress-helper';
+/**
+ * Build a `ctx.forEach` function bound to a specific workflow run.
+ */
+export function createForEach(wfCtx) {
+    return async (items, opts, handler) => {
+        const isArray = Array.isArray(items);
+        const totalKnown = isArray ? items.length : null;
+        let done = 0;
+        let batchIndex = 0;
+        let buffer = [];
+        const flush = async () => {
+            if (buffer.length === 0)
+                return;
+            if (wfCtx.signal?.aborted)
+                throw new CancelledError();
+            const info = { done, total: totalKnown, batchIndex };
+            const batch = buffer;
+            buffer = [];
+            await handler(batch, info);
+            done += batch.length;
+            batchIndex += 1;
+            // Emit progress after the batch completes — fire-and-forget.
+            const channel = wfCtx.progressChannel;
+            if (channel) {
+                const stepName = wfCtx.stepName ?? 'unknown';
+                const message = opts.message ? safeFormat(opts.message, { done, total: totalKnown, batchIndex }) : undefined;
+                try {
+                    const p = channel.set(wfCtx.runId, { stepName, current: done, total: totalKnown, message, at: Date.now() });
+                    if (p && typeof p.catch === 'function') {
+                        ;
+                        p.catch(() => {
+                            /* swallow — progress is observability */
+                        });
+                    }
+                }
+                catch {
+                    /* `.set` is never-throws; belt-and-suspenders */
+                }
+            }
+        };
+        // Guard before the very first iteration: if the signal is already aborted,
+        // fail immediately without touching items.
+        if (wfCtx.signal?.aborted)
+            throw new CancelledError();
+        if (isArray) {
+            for (const item of items) {
+                buffer.push(item);
+                if (buffer.length >= opts.batchSize)
+                    await flush();
+            }
+            await flush();
+        }
+        else {
+            for await (const item of items) {
+                buffer.push(item);
+                if (buffer.length >= opts.batchSize)
+                    await flush();
+            }
+            await flush();
+        }
+    };
+}
+function safeFormat(fn, info) {
+    try {
+        return fn(info);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=for-each.js.map

package/dist/workflows/for-each.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"for-each.js","sourceRoot":"","sources":["../../src/workflows/for-each.ts"],"names":[],"mappings":"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"}

package/dist/workflows/index.d.ts

@@ -0,0 +1,15 @@
+export { createStep } from './create-step';
+export { createWorkflow } from './create-workflow';
+export type { ModuleWorkflowDefinition, WorkflowHandlerContext } from './define-workflow';
+export { defineWorkflow } from './define-workflow';
+export type { EmitEventStepInput } from './emit-event-step';
+export { emitEventStep } from './emit-event-step';
+export { createForEach } from './for-each';
+export { WorkflowManager, type WorkflowStorage, workflowContextStorage } from './manager';
+export { createOrphanReaperJob, DEFAULT_ORPHAN_REAP_LIMIT, DEFAULT_ORPHAN_THRESHOLD_MS, ORPHAN_REAPER_JOB_NAME, ORPHAN_REAPER_SCHEDULE, type OrphanReaperJobDescriptor, type OrphanReaperOptions, type OrphanReaperResult, WORKFLOW_ORPHANED_CODE, } from './orphan-reaper';
+export { CancelledError, createProgress } from './progress-helper';
+export type { ActionStepConfig, CrudStepConfig } from './step';
+/** @internal */ export { ENTITY_TAG, step } from './step';
+export type { CompletedStep, ForEachInfo, StepContext, StepDefinition, StepFn, StepHandlerContext, StepResolveContext, WorkflowContext, WorkflowDefinition, WorkflowResult, WorkflowRunOptions, WorkflowRunResult, } from './types';
+export { isWorkflowYield, WorkflowYield } from './yield';
+//# sourceMappingURL=index.d.ts.map

package/dist/workflows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,YAAY,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AACzF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACzF,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAC9D,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC1D,YAAY,EACV,aAAa,EACb,WAAW,EACX,WAAW,EACX,cAAc,EACd,MAAM,EACN,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA"}

package/dist/workflows/index.js

@@ -0,0 +1,12 @@
+// Workflow system — public API
+export { createStep } from './create-step';
+export { createWorkflow } from './create-workflow';
+export { defineWorkflow } from './define-workflow';
+export { emitEventStep } from './emit-event-step';
+export { createForEach } from './for-each';
+export { WorkflowManager, workflowContextStorage } from './manager';
+export { createOrphanReaperJob, DEFAULT_ORPHAN_REAP_LIMIT, DEFAULT_ORPHAN_THRESHOLD_MS, ORPHAN_REAPER_JOB_NAME, ORPHAN_REAPER_SCHEDULE, WORKFLOW_ORPHANED_CODE, } from './orphan-reaper';
+export { CancelledError, createProgress } from './progress-helper';
+/** @internal */ export { ENTITY_TAG, step } from './step';
+export { isWorkflowYield, WorkflowYield } from './yield';
+//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAwB,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACzF,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EAItB,sBAAsB,GACvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElE,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAe1D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA"}

package/dist/workflows/manager.d.ts

@@ -0,0 +1,99 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { MantaApp } from '../app';
+import type { IProgressChannelPort } from '../ports/progress-channel';
+import type { IQueuePort } from '../ports/queue';
+import type { IWorkflowStorePort, StepState } from '../ports/workflow-store';
+import type { WorkflowContext, WorkflowDefinition, WorkflowRunOptions, WorkflowRunResult } from './types';
+export declare const workflowContextStorage: AsyncLocalStorage<WorkflowContext>;
+export interface WorkflowStorage {
+    save(transactionId: string, stepId: string, data: unknown): Promise<void>;
+    list(transactionId: string): Promise<Array<{
+        stepId: string;
+        data: unknown;
+    }>>;
+    delete(transactionId: string): Promise<void>;
+    /** Track workflow execution start (optional) */
+    trackStart?(transactionId: string, workflowName: string, input: unknown): Promise<void>;
+    /** Track workflow execution completion (optional) */
+    trackComplete?(transactionId: string, result: unknown): Promise<void>;
+    /** Track workflow execution failure (optional) */
+    trackFailed?(transactionId: string, error: string): Promise<void>;
+}
+export interface WorkflowManagerOptions {
+    storage?: WorkflowStorage;
+    /**
+     * Durable workflow run store — feeds `/admin/_runs/:runId`, `useCommand`
+     * polling, and cancellation. See WORKFLOW_PROGRESS.md §5.1 / §9.1.
+     */
+    store?: IWorkflowStorePort;
+    /**
+     * Ephemeral progress channel — backs `ctx.progress` and `ctx.forEach`.
+     * See WORKFLOW_PROGRESS.md §5.2 / §9.2.
+     */
+    progressChannel?: IProgressChannelPort;
+    /**
+     * Queue adapter used to schedule serverless continuations after a step
+     * calls `ctx.yield(state)`. When absent, paused workflows stay paused
+     * until someone calls `manager.resume(runId)` manually (tests / CLI).
+     */
+    queue?: IQueuePort;
+    /**
+     * Builds the URL the queue should POST to resume a run. Typically wired
+     * in init-infra: `(runId) => \`${baseUrl}/api/${ctx}/_workflow/${runId}/resume\``.
+     * Called on every yield — cheap. When absent, queue.enqueue is skipped.
+     */
+    resumeEndpoint?: (runId: string) => string;
+    /**
+     * Wall-clock budget (ms) propagated to every step via `ctx.budgetMs`.
+     * On Vercel Hobby this should be ~7000 (10s cap − 3s safety). On
+     * long-running Node hosts leave `undefined` (treated as Infinity).
+     */
+    stepBudgetMs?: number;
+}
+/**
+ * WorkflowManager — registers and runs imperative workflows.
+ * Steps access the workflow context via AsyncLocalStorage.
+ */
+export declare class WorkflowManager {
+    private _workflows;
+    private _logger;
+    private _eventBus;
+    private _locking;
+    private _storage;
+    private _store;
+    private _progressChannel;
+    private _queue;
+    private _resumeEndpoint;
+    private _stepBudgetMs;
+    private _app;
+    /** Per-run AbortControllers. Keyed by transactionId / runId. */
+    private _controllers;
+    constructor(app: MantaApp, options?: WorkflowManagerOptions);
+    register(workflow: WorkflowDefinition<any, any>): void;
+    run(workflowId: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    /**
+     * Resume a paused workflow run. Invoked by the HTTP handler for
+     * `POST /api/<ctx>/_workflow/:runId/resume` when the queue adapter
+     * delivers a continuation.
+     *
+     * Loads the run's original `command_name` and `input` from the store, then
+     * re-enters `run()` with the same `transactionId`. The normal resume
+     * machinery picks up:
+     *  - completed steps (from workflow_checkpoints) — skipped at zero cost
+     *  - paused steps (from workflow_runs.steps[].resume_state) — re-invoked
+     *    with ctx.resumeState populated
+     *
+     * Idempotent: safe to call multiple times — if the run is already terminal,
+     * returns early without re-executing.
+     */
+    resume(runId: string): Promise<WorkflowRunResult>;
+    /**
+     * Execute a single attempt. Throws on failure — the retry loop in run() handles retries.
+     * On the final attempt, compensates before re-throwing.
+     */
+    private _execute;
+    private _compensate;
+    _reset(): void;
+}
+export type { StepState };
+//# sourceMappingURL=manager.d.ts.map

package/dist/workflows/manager.d.ts.map

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