@bratsos/workflow-engine 0.0.11 → 0.2.0

package/dist/plugins-BCnDUwIc.d.ts

@@ -0,0 +1,415 @@
+import { z } from 'zod';
+import { S as Stage } from './stage-BPw7m9Wx.js';
+import { P as Persistence, B as BlobStore, J as JobTransport, E as EventSink, S as Scheduler, C as Clock, a as KernelEventType, K as KernelEvent } from './ports-tU3rzPXJ.js';
+
+/**
+ * Workflow Builder - Fluent API for composing type-safe workflows
+ *
+ * Workflows are composed of stages that are executed sequentially or in parallel.
+ * The builder ensures type safety: output of one stage matches input of next stage.
+ *
+ * ## Type System Features
+ *
+ * ### Automatic Context Inference
+ * The workflow context type is automatically accumulated as you pipe stages.
+ * Use `InferWorkflowContext<typeof workflow>` to extract the context type.
+ *
+ * ```typescript
+ * const workflow = new WorkflowBuilder(...)
+ *   .pipe(stage1)
+ *   .pipe(stage2)
+ *   .build();
+ *
+ * // Auto-generated type
+ * type MyContext = InferWorkflowContext<typeof workflow>;
+ * // = { "stage-1": Stage1Output, "stage-2": Stage2Output }
+ * ```
+ *
+ * ### Stage ID Constants
+ * Use `workflow.stageIds` for type-safe stage ID references.
+ */
+
+interface StageNode {
+    stage: Stage<any, any, any>;
+    executionGroup: number;
+}
+declare class Workflow<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, TContext extends Record<string, unknown> = {}> {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TInput;
+    readonly outputSchema: TOutput;
+    private readonly stages;
+    readonly contextType?: TContext | undefined;
+    constructor(id: string, name: string, description: string, inputSchema: TInput, outputSchema: TOutput, stages: StageNode[], contextType?: TContext | undefined);
+    /**
+     * Get execution plan as groups of stages
+     * Stages in the same group can be executed in parallel
+     */
+    getExecutionPlan(): StageNode[][];
+    /**
+     * Get a specific stage by ID
+     */
+    getStage(stageId: string): Stage<any, any, any> | undefined;
+    /**
+     * Get all stages in order
+     */
+    getAllStages(): StageNode[];
+    /**
+     * Get a visual representation of the workflow execution order
+     */
+    getExecutionOrder(): string;
+    /**
+     * Get all stage IDs in execution order
+     *
+     * @returns Array of stage IDs
+     *
+     * @example
+     * ```typescript
+     * const ids = workflow.getStageIds();
+     * // ["data-extraction", "guidelines", "generator"]
+     * ```
+     */
+    getStageIds(): string[];
+    /**
+     * Check if a stage ID exists in this workflow
+     *
+     * @param stageId - The stage ID to check
+     * @returns true if the stage exists
+     */
+    hasStage(stageId: string): boolean;
+    /**
+     * Validate workflow configuration before execution
+     * Checks that all stage configs match their schemas
+     *
+     * @param config - Configuration object with keys matching stage IDs
+     * @returns Validation result with any errors
+     */
+    validateConfig(config: Record<string, unknown>): {
+        valid: boolean;
+        errors: Array<{
+            stageId: string;
+            error: string;
+        }>;
+    };
+    /**
+     * Estimate total cost for the workflow
+     */
+    estimateCost(input: z.infer<TInput>, config: Record<string, unknown>): number;
+    /**
+     * Get configuration schemas for all stages in this workflow
+     * Returns a map of stageId → { schema, defaults, name, description }
+     */
+    getStageConfigs(): Record<string, {
+        schema: z.ZodTypeAny;
+        defaults: Record<string, unknown>;
+        name: string;
+        description?: string;
+    }>;
+    /**
+     * Generate default configuration object for all stages
+     * Automatically discovers all stage configs - add/remove stages and this updates automatically
+     */
+    getDefaultConfig(): Record<string, Record<string, unknown>>;
+    /**
+     * Get all stages in a specific execution group
+     */
+    getStagesInExecutionGroup(groupIndex: number): Stage<any, any, any>[];
+    /**
+     * Get the sequential index of a stage (0-based)
+     */
+    getStageIndex(stageId: string): number;
+    /**
+     * Get the execution group index for a stage
+     */
+    getExecutionGroupIndex(stageId: string): number;
+    /**
+     * Get the ID of the stage immediately preceding the given stage
+     */
+    getPreviousStageId(stageId: string): string | undefined;
+}
+declare class WorkflowBuilder<TInput extends z.ZodTypeAny, TCurrentOutput extends z.ZodTypeAny, TContext extends Record<string, unknown> = {}> {
+    private id;
+    private name;
+    private description;
+    private inputSchema;
+    private currentOutputSchema;
+    private stages;
+    private currentExecutionGroup;
+    constructor(id: string, name: string, description: string, inputSchema: TInput, currentOutputSchema: TCurrentOutput);
+    /**
+     * Add a stage to the workflow (sequential execution)
+     *
+     * Automatically accumulates the stage's output in the context under its stage ID.
+     * This provides type-safe access to all previous stage outputs.
+     *
+     * Note: This accepts any stage regardless of strict input type matching.
+     * This is necessary because stages using passthrough() can accept objects
+     * with additional fields beyond what's declared in their input schema.
+     * Runtime validation via Zod ensures type safety at execution time.
+     *
+     * Validates that all declared dependencies exist in the workflow.
+     */
+    pipe<TStageInput extends z.ZodTypeAny, TStageOutput extends z.ZodTypeAny, TStageConfig extends z.ZodTypeAny, TStageContext extends Record<string, unknown>>(stage: Stage<TStageInput, TStageOutput, TStageConfig, TStageContext>): WorkflowBuilder<TInput, TStageOutput, TContext & {
+        [x: string]: z.infer<TStageOutput>;
+    }>;
+    /**
+     * Add a stage with strict input type checking
+     *
+     * Note: pipeStrict() and pipeLoose() have been removed as they were
+     * just aliases for pipe(). Use pipe() for all stage chaining.
+     */
+    /**
+     * Add multiple stages that execute in parallel
+     *
+     * All stages receive the same input (current output)
+     * Their outputs are merged into an object by index AND accumulated in context by stage ID.
+     *
+     * Note: This accepts stages regardless of strict input type matching.
+     * This is necessary because stages using passthrough() can accept objects
+     * with additional fields. Runtime validation via Zod ensures type safety.
+     *
+     * Validates that all declared dependencies exist in the workflow.
+     */
+    parallel<TStages extends {
+        id: string;
+        outputSchema: z.ZodTypeAny;
+        dependencies?: string[];
+    }[]>(stages: [...TStages]): WorkflowBuilder<TInput, z.ZodTypeAny, TContext & {
+        [K in TStages[number]["id"]]: TStages[number] extends {
+            outputSchema: infer O;
+        } ? O extends z.ZodTypeAny ? z.infer<O> : never : never;
+    }>;
+    /**
+     * Build the final workflow
+     */
+    build(): Workflow<TInput, TCurrentOutput, TContext>;
+    /**
+     * Get current stage count
+     */
+    getStageCount(): number;
+    /**
+     * Get execution group count
+     */
+    getExecutionGroupCount(): number;
+}
+/**
+ * Extract stage IDs as a union type from a Workflow instance
+ *
+ * Useful for creating type-safe stage ID references.
+ *
+ * @example
+ * ```typescript
+ * type StageId = InferWorkflowStageIds<typeof myWorkflow>;
+ * // = "data-extraction" | "guidelines" | "generator"
+ *
+ * function getStageOutput(stageId: StageId) { ... }
+ * ```
+ */
+type InferWorkflowStageIds<W> = W extends Workflow<any, any, infer C> ? keyof C & string : never;
+
+/**
+ * Kernel Command Types
+ *
+ * Discriminated union of commands accepted by the kernel's dispatch
+ * interface, together with a conditional `CommandResult` type that maps
+ * each command to its corresponding result.
+ *
+ * This file contains ONLY types -- no runtime code.
+ */
+/** Creates a new workflow run. */
+interface RunCreateCommand {
+    readonly type: "run.create";
+    readonly idempotencyKey: string;
+    readonly workflowId: string;
+    readonly input: Record<string, unknown>;
+    readonly config?: Record<string, unknown>;
+    readonly priority?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Result of a `run.create` command. */
+interface RunCreateResult {
+    readonly workflowRunId: string;
+    readonly status: "PENDING";
+}
+/** Claims pending runs and enqueues first-stage jobs. */
+interface RunClaimPendingCommand {
+    readonly type: "run.claimPending";
+    readonly workerId: string;
+    readonly maxClaims?: number;
+}
+/** Result of a `run.claimPending` command. */
+interface RunClaimPendingResult {
+    readonly claimed: ReadonlyArray<{
+        readonly workflowRunId: string;
+        readonly workflowId: string;
+        readonly jobIds: string[];
+    }>;
+}
+/** Advances a workflow to the next stage group or completes it. */
+interface RunTransitionCommand {
+    readonly type: "run.transition";
+    readonly workflowRunId: string;
+}
+/** Result of a `run.transition` command. */
+interface RunTransitionResult {
+    readonly action: "advanced" | "completed" | "failed" | "noop";
+    readonly nextGroup?: number;
+}
+/** Cancels a running workflow. */
+interface RunCancelCommand {
+    readonly type: "run.cancel";
+    readonly workflowRunId: string;
+    readonly reason?: string;
+}
+/** Result of a `run.cancel` command. */
+interface RunCancelResult {
+    readonly cancelled: boolean;
+}
+/** Reruns a workflow from a specific stage, deleting stages at/after that point. */
+interface RunRerunFromCommand {
+    readonly type: "run.rerunFrom";
+    readonly workflowRunId: string;
+    readonly fromStageId: string;
+}
+/** Result of a `run.rerunFrom` command. */
+interface RunRerunFromResult {
+    readonly workflowRunId: string;
+    readonly fromStageId: string;
+    readonly deletedStages: string[];
+}
+/** Executes a single stage within a workflow run. */
+interface JobExecuteCommand {
+    readonly type: "job.execute";
+    readonly idempotencyKey?: string;
+    readonly workflowRunId: string;
+    readonly workflowId: string;
+    readonly stageId: string;
+    readonly config: Record<string, unknown>;
+}
+/** Result of a `job.execute` command. */
+interface JobExecuteResult {
+    readonly outcome: "completed" | "suspended" | "failed";
+    readonly output?: unknown;
+    readonly error?: string;
+    readonly nextPollAt?: Date;
+}
+/** Polls suspended stages to check if they can be resumed. */
+interface StagePollSuspendedCommand {
+    readonly type: "stage.pollSuspended";
+    readonly maxChecks?: number;
+}
+/** Result of a `stage.pollSuspended` command. */
+interface StagePollSuspendedResult {
+    readonly checked: number;
+    readonly resumed: number;
+    readonly failed: number;
+    readonly resumedWorkflowRunIds: string[];
+}
+/** Releases stale job leases that have exceeded the threshold. */
+interface LeaseReapStaleCommand {
+    readonly type: "lease.reapStale";
+    readonly staleThresholdMs: number;
+}
+/** Result of a `lease.reapStale` command. */
+interface LeaseReapStaleResult {
+    readonly released: number;
+}
+/** Publishes pending outbox events through EventSink. */
+interface OutboxFlushCommand {
+    readonly type: "outbox.flush";
+    readonly maxEvents?: number;
+}
+/** Result of an `outbox.flush` command. */
+interface OutboxFlushResult {
+    readonly published: number;
+}
+/** Replays DLQ outbox events for reprocessing. */
+interface PluginReplayDLQCommand {
+    readonly type: "plugin.replayDLQ";
+    readonly maxEvents?: number;
+}
+/** Result of a `plugin.replayDLQ` command. */
+interface PluginReplayDLQResult {
+    readonly replayed: number;
+}
+/** Discriminated union of every kernel command. */
+type KernelCommand = RunCreateCommand | RunClaimPendingCommand | RunTransitionCommand | RunCancelCommand | RunRerunFromCommand | JobExecuteCommand | StagePollSuspendedCommand | LeaseReapStaleCommand | OutboxFlushCommand | PluginReplayDLQCommand;
+/** String literal union of all kernel command type discriminants. */
+type KernelCommandType = KernelCommand["type"];
+/** Maps a `KernelCommand` to its corresponding result type. */
+type CommandResult<T extends KernelCommand> = T extends RunCreateCommand ? RunCreateResult : T extends RunClaimPendingCommand ? RunClaimPendingResult : T extends RunTransitionCommand ? RunTransitionResult : T extends RunCancelCommand ? RunCancelResult : T extends RunRerunFromCommand ? RunRerunFromResult : T extends JobExecuteCommand ? JobExecuteResult : T extends StagePollSuspendedCommand ? StagePollSuspendedResult : T extends LeaseReapStaleCommand ? LeaseReapStaleResult : T extends OutboxFlushCommand ? OutboxFlushResult : T extends PluginReplayDLQCommand ? PluginReplayDLQResult : never;
+
+declare class IdempotencyInProgressError extends Error {
+    readonly key: string;
+    readonly commandType: string;
+    constructor(key: string, commandType: string);
+}
+
+/**
+ * Kernel Factory
+ *
+ * Creates a Kernel instance with a typed `dispatch` method that routes
+ * commands to their corresponding handlers. Events are written to a
+ * transactional outbox (not emitted directly). Use the `outbox.flush`
+ * command to publish pending outbox events through EventSink.
+ *
+ * Commands with idempotency keys are deduplicated: a replay returns the
+ * cached result without re-executing the handler.
+ */
+
+interface WorkflowRegistry {
+    getWorkflow(id: string): Workflow<any, any> | undefined;
+}
+interface KernelConfig {
+    persistence: Persistence;
+    blobStore: BlobStore;
+    jobTransport: JobTransport;
+    eventSink: EventSink;
+    scheduler: Scheduler;
+    clock: Clock;
+    registry: WorkflowRegistry;
+}
+interface Kernel {
+    dispatch<T extends KernelCommand>(command: T): Promise<CommandResult<T>>;
+}
+interface KernelDeps {
+    persistence: Persistence;
+    blobStore: BlobStore;
+    jobTransport: JobTransport;
+    eventSink: EventSink;
+    scheduler: Scheduler;
+    clock: Clock;
+    registry: WorkflowRegistry;
+}
+declare function createKernel(config: KernelConfig): Kernel;
+
+/**
+ * Plugin Runner
+ *
+ * A concrete EventSink implementation that routes kernel events
+ * to registered plugin handlers. Used as the eventSink when the
+ * consumer wants domain side-effects on workflow events.
+ */
+
+interface PluginDefinition<T extends KernelEventType = KernelEventType> {
+    readonly id: string;
+    readonly name: string;
+    readonly on: readonly T[];
+    handle(event: Extract<KernelEvent, {
+        type: T;
+    }>): Promise<void>;
+}
+interface PluginRunnerConfig {
+    plugins: PluginDefinition[];
+    /** Max retries before an event moves to DLQ (default: 3). */
+    maxRetries?: number;
+}
+interface PluginRunner extends EventSink {
+    /** Max retries before DLQ. Exposed so outbox.flush can read it. */
+    readonly maxRetries: number;
+}
+declare function definePlugin<T extends KernelEventType>(definition: PluginDefinition<T>): PluginDefinition<T>;
+declare function createPluginRunner(config: PluginRunnerConfig): PluginRunner;
+
+export { WorkflowBuilder as A, type CommandResult as C, IdempotencyInProgressError as I, type JobExecuteCommand as J, type KernelDeps as K, type LeaseReapStaleCommand as L, type OutboxFlushCommand as O, type PluginDefinition as P, type RunCancelCommand as R, type StagePollSuspendedCommand as S, type WorkflowRegistry as W, type JobExecuteResult as a, type Kernel as b, type KernelCommand as c, type KernelCommandType as d, type KernelConfig as e, type LeaseReapStaleResult as f, type OutboxFlushResult as g, type PluginReplayDLQCommand as h, type PluginReplayDLQResult as i, type PluginRunner as j, type PluginRunnerConfig as k, type RunCancelResult as l, type RunClaimPendingCommand as m, type RunClaimPendingResult as n, type RunCreateCommand as o, type RunCreateResult as p, type RunRerunFromCommand as q, type RunRerunFromResult as r, type RunTransitionCommand as s, type RunTransitionResult as t, type StagePollSuspendedResult as u, createKernel as v, createPluginRunner as w, definePlugin as x, type InferWorkflowStageIds as y, Workflow as z };

package/dist/ports-tU3rzPXJ.d.ts

@@ -0,0 +1,245 @@
+import { E as EnqueueJobInput, D as DequeueResult, a as CreateRunInput, W as WorkflowRunRecord, U as UpdateRunInput, S as Status, b as CreateStageInput, c as WorkflowStageRecord, d as UpsertStageInput, e as UpdateStageInput, f as CreateLogInput, C as CreateOutboxEventInput, O as OutboxRecord } from './interface-MMqhfQQK.js';
+
+/**
+ * Kernel Event Types
+ *
+ * Discriminated union of all events emitted by the workflow kernel.
+ * Each event carries a string literal `type` discriminant, a `timestamp`,
+ * and a `workflowRunId` that scopes the event to a specific run.
+ *
+ * This file contains ONLY types -- no runtime code.
+ */
+/** Emitted when a new workflow run record is created. */
+interface WorkflowCreatedEvent {
+    readonly type: "workflow:created";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly workflowId: string;
+}
+/** Emitted when a workflow run begins execution. */
+interface WorkflowStartedEvent {
+    readonly type: "workflow:started";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+}
+/** Emitted when a workflow run finishes successfully. */
+interface WorkflowCompletedEvent {
+    readonly type: "workflow:completed";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly duration?: number;
+    readonly totalCost?: number;
+    readonly totalTokens?: number;
+    readonly output?: unknown;
+}
+/** Emitted when a workflow run terminates due to an unrecoverable error. */
+interface WorkflowFailedEvent {
+    readonly type: "workflow:failed";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly error: string;
+}
+/** Emitted when a workflow run is cancelled by an external request. */
+interface WorkflowCancelledEvent {
+    readonly type: "workflow:cancelled";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly reason?: string;
+}
+/** Emitted when a workflow run suspends, waiting on an external signal. */
+interface WorkflowSuspendedEvent {
+    readonly type: "workflow:suspended";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly stageId: string;
+}
+/** Emitted when a stage begins execution. */
+interface StageStartedEvent {
+    readonly type: "stage:started";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly stageId: string;
+    readonly stageName: string;
+    readonly stageNumber: number;
+}
+/** Emitted when a stage completes successfully. */
+interface StageCompletedEvent {
+    readonly type: "stage:completed";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly stageId: string;
+    readonly stageName: string;
+    readonly duration: number;
+}
+/** Emitted when a stage suspends, awaiting a future poll. */
+interface StageSuspendedEvent {
+    readonly type: "stage:suspended";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly stageId: string;
+    readonly stageName: string;
+    readonly nextPollAt: Date;
+}
+/** Emitted when a stage fails with an error. */
+interface StageFailedEvent {
+    readonly type: "stage:failed";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly stageId: string;
+    readonly stageName: string;
+    readonly error: string;
+}
+/** Emitted to report incremental progress within a stage. */
+interface StageProgressEvent {
+    readonly type: "stage:progress";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly stageId: string;
+    readonly progress: number;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+}
+/** Discriminated union of every kernel event. */
+type KernelEvent = WorkflowCreatedEvent | WorkflowStartedEvent | WorkflowCompletedEvent | WorkflowFailedEvent | WorkflowCancelledEvent | WorkflowSuspendedEvent | StageStartedEvent | StageCompletedEvent | StageSuspendedEvent | StageFailedEvent | StageProgressEvent;
+/** String literal union of all kernel event type discriminants. */
+type KernelEventType = KernelEvent["type"];
+
+/**
+ * Kernel Port Interfaces
+ *
+ * These interfaces define the dependency-inversion boundary for the workflow
+ * kernel. Every external capability the kernel needs is expressed as a port
+ * interface here. Concrete implementations are injected at composition time,
+ * making the kernel fully testable with in-memory fakes.
+ *
+ * Ports:
+ *  - Clock          – injectable time source
+ *  - Persistence    – metadata storage (runs, stages, logs, artifacts)
+ *  - BlobStore      – large payload storage
+ *  - JobTransport   – job queue abstraction
+ *  - EventSink      – event publishing
+ *  - Scheduler      – deferred command triggers
+ */
+
+/** Injectable time source. */
+interface Clock {
+    now(): Date;
+}
+/**
+ * Metadata storage port.
+ *
+ * Run, stage, and log CRUD operations. Artifact payloads are handled
+ * by the BlobStore port.
+ */
+interface Persistence {
+    /** Execute operations within a transaction boundary. */
+    withTransaction<T>(fn: (tx: Persistence) => Promise<T>): Promise<T>;
+    createRun(data: CreateRunInput): Promise<WorkflowRunRecord>;
+    updateRun(id: string, data: UpdateRunInput): Promise<void>;
+    getRun(id: string): Promise<WorkflowRunRecord | null>;
+    getRunStatus(id: string): Promise<Status | null>;
+    getRunsByStatus(status: Status): Promise<WorkflowRunRecord[]>;
+    /**
+     * Atomically claim a pending workflow run for processing.
+     * Uses atomic update with WHERE status = 'PENDING' to prevent race conditions.
+     */
+    claimPendingRun(id: string): Promise<boolean>;
+    /**
+     * Atomically find and claim the next pending workflow run.
+     * Uses FOR UPDATE SKIP LOCKED pattern (in Postgres) to prevent race conditions
+     * when multiple workers try to claim workflows simultaneously.
+     *
+     * Priority ordering: higher priority first, then oldest (FIFO within same priority).
+     */
+    claimNextPendingRun(): Promise<WorkflowRunRecord | null>;
+    createStage(data: CreateStageInput): Promise<WorkflowStageRecord>;
+    upsertStage(data: UpsertStageInput): Promise<WorkflowStageRecord>;
+    updateStage(id: string, data: UpdateStageInput): Promise<void>;
+    updateStageByRunAndStageId(workflowRunId: string, stageId: string, data: UpdateStageInput): Promise<void>;
+    getStage(runId: string, stageId: string): Promise<WorkflowStageRecord | null>;
+    getStageById(id: string): Promise<WorkflowStageRecord | null>;
+    getStagesByRun(runId: string, options?: {
+        status?: Status;
+        orderBy?: "asc" | "desc";
+    }): Promise<WorkflowStageRecord[]>;
+    getSuspendedStages(beforeDate: Date): Promise<WorkflowStageRecord[]>;
+    getFirstSuspendedStageReadyToResume(runId: string): Promise<WorkflowStageRecord | null>;
+    getFirstFailedStage(runId: string): Promise<WorkflowStageRecord | null>;
+    getLastCompletedStage(runId: string): Promise<WorkflowStageRecord | null>;
+    getLastCompletedStageBefore(runId: string, executionGroup: number): Promise<WorkflowStageRecord | null>;
+    deleteStage(id: string): Promise<void>;
+    createLog(data: CreateLogInput): Promise<void>;
+    /** Write events to the outbox. Sequences are auto-assigned per workflowRunId. */
+    appendOutboxEvents(events: CreateOutboxEventInput[]): Promise<void>;
+    /** Read unpublished events ordered by (workflowRunId, sequence). */
+    getUnpublishedOutboxEvents(limit?: number): Promise<OutboxRecord[]>;
+    /** Mark events as published. */
+    markOutboxEventsPublished(ids: string[]): Promise<void>;
+    /** Increment retry count for a failed outbox event. Returns new count. */
+    incrementOutboxRetryCount(id: string): Promise<number>;
+    /** Move an outbox event to DLQ (sets dlqAt). */
+    moveOutboxEventToDLQ(id: string): Promise<void>;
+    /** Reset DLQ events so they can be reprocessed by outbox.flush. Returns count reset. */
+    replayDLQEvents(maxEvents: number): Promise<number>;
+    /** Atomically acquire an idempotency key for command execution. */
+    acquireIdempotencyKey(key: string, commandType: string): Promise<{
+        status: "acquired";
+    } | {
+        status: "replay";
+        result: unknown;
+    } | {
+        status: "in_progress";
+    }>;
+    /** Mark an idempotency key as completed and cache the command result. */
+    completeIdempotencyKey(key: string, commandType: string, result: unknown): Promise<void>;
+    /** Release an in-progress idempotency key after command failure. */
+    releaseIdempotencyKey(key: string, commandType: string): Promise<void>;
+}
+/** Large payload storage. */
+interface BlobStore {
+    put(key: string, data: unknown): Promise<void>;
+    get(key: string): Promise<unknown>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+/**
+ * Job queue abstraction.
+ *
+ * Same shape as the existing `JobQueue` interface so that current
+ * implementations (`InMemoryJobQueue`, `PrismaJobQueue`) structurally satisfy
+ * this port without adapters.
+ */
+interface JobTransport {
+    /** Add a new job to the queue. */
+    enqueue(options: EnqueueJobInput): Promise<string>;
+    /** Enqueue multiple stages in parallel (same execution group). */
+    enqueueParallel(jobs: EnqueueJobInput[]): Promise<string[]>;
+    /** Atomically dequeue the next available job. */
+    dequeue(): Promise<DequeueResult | null>;
+    /** Mark job as completed. */
+    complete(jobId: string): Promise<void>;
+    /** Mark job as suspended (for async-batch). */
+    suspend(jobId: string, nextPollAt: Date): Promise<void>;
+    /** Mark job as failed. */
+    fail(jobId: string, error: string, shouldRetry?: boolean): Promise<void>;
+    /** Get suspended jobs that are ready to be checked. */
+    getSuspendedJobsReadyToPoll(): Promise<Array<{
+        jobId: string;
+        stageId: string;
+        workflowRunId: string;
+    }>>;
+    /** Release stale locks (for crashed workers). */
+    releaseStaleJobs(staleThresholdMs?: number): Promise<number>;
+}
+/** Event publishing (replaces global EventBus). */
+interface EventSink {
+    emit(event: KernelEvent): Promise<void>;
+}
+/** Deferred command triggers (minimal in Phase 1). */
+interface Scheduler {
+    schedule(commandType: string, payload: unknown, runAt: Date): Promise<void>;
+    cancel(commandType: string, correlationId: string): Promise<void>;
+}
+
+export type { BlobStore as B, Clock as C, EventSink as E, JobTransport as J, KernelEvent as K, Persistence as P, Scheduler as S, WorkflowCancelledEvent as W, KernelEventType as a, StageCompletedEvent as b, StageFailedEvent as c, StageProgressEvent as d, StageStartedEvent as e, StageSuspendedEvent as f, WorkflowCompletedEvent as g, WorkflowCreatedEvent as h, WorkflowFailedEvent as i, WorkflowStartedEvent as j, WorkflowSuspendedEvent as k };