octaflow 0.14.0

package/dist/index-D_fOYfmf.d.ts

@@ -0,0 +1,580 @@
+import { z } from "zod";
+//#region src/core/result.d.ts
+interface FlowErrorShape {
+  key: string;
+  message: string;
+}
+type Result<T = void, E extends FlowErrorShape = FlowErrorShape> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: E;
+};
+declare const ok: <T>(value: T) => Result<T, never>;
+declare const err: <E extends FlowErrorShape>(error: E) => Result<never, E>;
+//#endregion
+//#region src/core/types.d.ts
+/** Workflow / step identifiers. Numeric to match common bigserial-backed stores. */
+type WorkflowId = number;
+type StepId = number;
+type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'waiting' | 'mapping' | 'compensating' | 'compensated';
+/**
+ * Declarative workflow definition: a DAG of steps with dependencies.
+ * Steps without dependencies start immediately and in parallel; a step starts
+ * as soon as ALL of its dependencies have completed.
+ */
+interface WorkflowDefinition {
+  /** Workflow type identifier (e.g. 'document-enrichment'). */
+  type: string;
+  /** The steps. Order is irrelevant — execution order is derived from dependencies. */
+  steps: StepDefinition[];
+}
+interface StepDefinition {
+  /** Unique key within the workflow (e.g. 'analyze-images'). */
+  key: string;
+  /** Handler type — looked up in the StepHandlerRegistry. */
+  type: string;
+  /** Keys of steps this step depends on. All must complete before this step runs. */
+  dependencies?: string[];
+  /** Optional static input baked into the step at definition time. */
+  input?: Record<string, unknown>;
+}
+interface StartOptions {
+  /** Optional reference for efficient filtering/lookup (e.g. 'document:123'). */
+  entityRef?: string;
+  /**
+   * Opaque metadata persisted on the workflow row. Add-ons use this as an escape
+   * hatch (e.g. the AI add-on stamps `keySource`) without flow-core knowing the shape.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Dedup key (per partition). A start with a key that already exists returns the
+   * existing workflow instead of creating a duplicate — so a double-click, retried
+   * request, or overlapping cron tick can't start the same work twice.
+   */
+  idempotencyKey?: string;
+  /**
+   * Internal: set by a sub-workflow step to link a child workflow back to the
+   * parent workflow + step that started it, so the parent step resumes when the child ends.
+   */
+  parentWorkflowId?: WorkflowId;
+  parentStepId?: StepId;
+}
+interface WorkflowCreatedResult {
+  workflowId: WorkflowId;
+  totalSteps: number;
+  /** Keys of the steps that were immediately enqueued (the dependency-free roots). */
+  enqueuedSteps: string[];
+}
+/**
+ * Context passed to a step handler. `context` is the host-provided per-step value
+ * (a DI scope, an AI model, domain services) produced by the `buildStepContext`
+ * hook — flow-core treats it as opaque.
+ */
+interface StepExecutionContext<TContext = unknown> {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  stepKey: string;
+  partitionKey: string;
+  /** Workflow-level input. */
+  workflowInput: Record<string, unknown>;
+  /** Static step-level input from the definition. */
+  stepInput: Record<string, unknown>;
+  /** Outputs of completed dependency steps, keyed by step key. */
+  dependencyOutputs: Record<string, unknown>;
+  /** Cancellation signal. */
+  signal?: AbortSignal;
+  /** Host-provided per-step context. */
+  context: TContext;
+}
+interface StepError extends FlowErrorShape {
+  key: 'step_error';
+  message: string;
+  /** Whether the failure is transient and the step should be retried. */
+  retryable?: boolean;
+  /**
+   * How `retryable` was decided. `'heuristic'` means nothing authoritative said
+   * either way and the default classifier guessed from the error's shape/message —
+   * the engine's `defaultRetryable` may override those, and only those.
+   */
+  retryableFrom?: 'explicit' | 'predicate' | 'heuristic';
+}
+type StepHandler<TContext = unknown> = (ctx: StepExecutionContext<TContext>) => Promise<Result<Record<string, unknown>, StepError>>;
+/** Context for a step's compensation handler — the execution context plus the step's own output. */
+interface StepCompensationContext<TContext = unknown> extends StepExecutionContext<TContext> {
+  /** The output the step produced when it completed (what compensation undoes). */
+  output: Record<string, unknown>;
+}
+/**
+ * Optional rollback handler. On workflow failure the engine runs it once for each
+ * `completed` step, in reverse dependency order, to undo side effects. Best-effort: a throw is
+ * logged + surfaced on the step (not retried).
+ */
+type StepCompensateHandler<TContext = unknown> = (ctx: StepCompensationContext<TContext>) => Promise<void> | void;
+/** Per-step retry policy. Applied by the engine when a step fails retryably. */
+interface RetryPolicy {
+  /** Total attempts including the first (1 = no retry). */
+  maxAttempts: number;
+  /** Backoff curve between attempts. Default `'fixed'`. */
+  backoff?: 'fixed' | 'exponential';
+  /** Delay before the 2nd attempt, in ms. Default 1000. */
+  initialDelayMs?: number;
+  /** Cap on the computed backoff delay, in ms. Default 60000. */
+  maxDelayMs?: number;
+}
+/** A registered handler plus its optional retry/timeout/delay policy. */
+interface StepRegistration<TContext = unknown> {
+  handler: StepHandler<TContext>;
+  retry?: RetryPolicy;
+  /** Per-step wall-clock timeout in ms. On expiry the step is aborted + retried. */
+  timeoutMs?: number;
+  /**
+   * Durable start delay in ms: once the step becomes ready (all deps complete), its
+   * first dispatch is held for this long via the queue. A no-op handler with a delay
+   * is a durable "sleep" step. Does not affect retry backoff.
+   */
+  delayMs?: number;
+  /**
+   * When true, a ready step **suspends** (status `waiting`) instead of being dispatched,
+   * until `engine.resumeStep(workflowId, stepKey, payload)` delivers an external event.
+   * The handler never runs; the resume payload becomes the step's output.
+   */
+  waitForEvent?: boolean;
+  /**
+   * When true, this is a **map** parent: its handler returns `{ items: T[] }`;
+   * the engine spawns one child step (of `childType`) per item, suspends the parent as
+   * `mapping`, and completes it with `{ items: childOutputs[] }` once all children finish.
+   */
+  map?: boolean;
+  /** For a map parent: the step `type` registered for its per-item child steps. */
+  childType?: string;
+  /**
+   * When set, this is a **sub-workflow** step: its handler returns the child
+   * workflow's input; the engine starts a child workflow from this definition, suspends
+   * the parent step as `waiting`, and resumes it with the child's output once it terminates.
+   */
+  subWorkflowDefinition?: WorkflowDefinition;
+  /** Optional saga rollback handler: undoes this step's effects on workflow failure. */
+  compensate?: StepCompensateHandler<TContext>;
+}
+/** Registry mapping step `type` strings to handlers + their policies. */
+interface StepHandlerRegistry<TContext = unknown> {
+  register(type: string, handler: StepHandler<TContext>, options?: {
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+    delayMs?: number;
+    waitForEvent?: boolean;
+    map?: boolean;
+    childType?: string;
+    subWorkflowDefinition?: WorkflowDefinition;
+    compensate?: StepCompensateHandler<TContext>;
+  }): void;
+  get(type: string): StepHandler<TContext> | undefined;
+  getRegistration(type: string): StepRegistration<TContext> | undefined;
+  has(type: string): boolean;
+  types(): string[];
+}
+interface WorkflowRecord {
+  id: WorkflowId;
+  type: string;
+  status: WorkflowStatus;
+  partitionKey: string;
+  input: Record<string, unknown>;
+  output: Record<string, unknown> | null;
+  error: string | null;
+  entityRef: string | null;
+  idempotencyKey: string | null;
+  /** For a sub-workflow child: the parent workflow + step that started it. */
+  parentWorkflowId: WorkflowId | null;
+  parentStepId: StepId | null;
+  totalSteps: number;
+  completedSteps: number;
+  failedSteps: number;
+  metadata: Record<string, unknown> | null;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+interface StepRecord {
+  id: StepId;
+  workflowId: WorkflowId;
+  key: string;
+  type: string;
+  status: StepStatus;
+  dependencies: string[];
+  input: Record<string, unknown> | null;
+  output: Record<string, unknown> | null;
+  error: string | null;
+  metadata: Record<string, unknown> | null;
+  /** Number of execution attempts so far (incremented each time the step runs). */
+  attempts: number;
+  /** For a map child: the id of its map-parent step; null for normal/keyed steps. */
+  parentStepId: StepId | null;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+interface WorkflowWithSteps extends WorkflowRecord {
+  steps: StepRecord[];
+}
+interface WorkflowNotFoundError extends FlowErrorShape {
+  key: 'workflow_not_found';
+}
+interface InvalidWorkflowDefinitionError extends FlowErrorShape {
+  key: 'invalid_workflow_definition';
+}
+interface StepHandlerNotFoundError extends FlowErrorShape {
+  key: 'step_handler_not_found';
+  stepType: string;
+}
+/**
+ * Engine error type. The named members cover flow-core's own failures; the
+ * bare `FlowErrorShape` arm lets hooks (e.g. an AI quota guard in `onBeforeStart`)
+ * reject a start with a domain-specific error key the engine just passes through.
+ */
+type FlowError = WorkflowNotFoundError | InvalidWorkflowDefinitionError | StepHandlerNotFoundError | StepError | FlowErrorShape;
+//#endregion
+//#region src/core/defineStep.d.ts
+/**
+ * A type-safe step definition with Zod validation schemas, parameterized by the
+ * host `TContext`. Created by `defineStep()`, consumed by `buildWorkflow()`.
+ */
+interface TypedStep<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}, TContext = unknown> {
+  readonly type: string;
+  readonly workflowInputSchema: z.ZodType<TInput>;
+  readonly outputSchema: z.ZodType<TOutput>;
+  readonly dependencies: TDeps;
+  /** Untyped handler for registry compatibility. */
+  readonly handler: StepHandler<TContext>;
+  /** Optional retry policy for this step type. */
+  readonly retry?: RetryPolicy;
+  /** Optional per-step wall-clock timeout in ms. */
+  readonly timeoutMs?: number;
+  /** Optional durable start delay in ms (held in the queue once the step is ready). */
+  readonly delayMs?: number;
+  /** When true, the step suspends (waiting) until `engine.resumeStep` delivers an event. */
+  readonly waitForEvent?: boolean;
+  /** When true, this is a map parent — see `defineMapStep`. */
+  readonly map?: boolean;
+  /** For a map parent: the step type registered for per-item children. */
+  readonly childType?: string;
+  /** For a map parent: the child step's registration, registered alongside the parent. */
+  readonly childRegistration?: {
+    type: string;
+    handler: StepHandler<TContext>;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+  };
+  /** For a sub-workflow step: the child workflow definition the engine starts. */
+  readonly subWorkflowDefinition?: WorkflowDefinition;
+  /** For a sub-workflow step: registers the child workflow's step handlers alongside the parent. */
+  readonly subWorkflowRegister?: (registry: StepHandlerRegistry<TContext>) => void;
+  /** Untyped saga rollback handler, built from the typed `compensate` config. */
+  readonly compensate?: StepCompensateHandler<TContext>;
+}
+/** Extract the output type of a typed step. */
+type StepOutput<T> = T extends TypedStep<any, infer O, any, any> ? O : never;
+/** Derive the aggregated workflow output from a steps map: `{ [stepKey]: stepOutput }`. */
+type WorkflowOutput<TSteps extends Record<string, TypedStep<any, any, any, any>>> = { [K in keyof TSteps]: StepOutput<TSteps[K]>; };
+/**
+ * Typed execution context passed to step handlers. `workflowInput` is validated
+ * against the step's `workflowInputSchema`; each `deps` entry is validated against
+ * its dependency's `outputSchema`.
+ */
+interface TypedStepContext<TInput extends Record<string, unknown>, TDeps extends Record<string, TypedStep<any, any, any, TContext>>, TContext> {
+  workflowId: number;
+  stepId: number;
+  stepKey: string;
+  partitionKey: string;
+  workflowInput: TInput;
+  stepInput: Record<string, unknown>;
+  deps: { [K in keyof TDeps]: StepOutput<TDeps[K]>; };
+  signal?: AbortSignal;
+  context: TContext;
+}
+interface DefineStepConfig<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, TDeps extends Record<string, TypedStep<any, any, any, TContext>>, TContext> {
+  type: string;
+  workflowInputSchema: z.ZodType<TInput>;
+  outputSchema: z.ZodType<TOutput>;
+  dependencies?: TDeps;
+  handler: (ctx: TypedStepContext<TInput, TDeps, TContext>) => Promise<TOutput>;
+  /** Optional retry policy (max attempts, backoff). */
+  retry?: RetryPolicy;
+  /**
+   * Decide whether a thrown error is transient, replacing the default message
+   * heuristic ({@link isRetryableError}) for this step. An error carrying an
+   * explicit marker ({@link markRetryable}) still wins over this.
+   *
+   * ```ts
+   * isRetryable: (e) => e instanceof HttpError && e.status >= 500,
+   * ```
+   */
+  isRetryable?: (error: unknown) => boolean;
+  /** Optional per-step wall-clock timeout in ms. */
+  timeoutMs?: number;
+  /** Optional durable start delay in ms — held in the queue once the step is ready. */
+  delayMs?: number;
+  /** When true, the step suspends (waiting) until `engine.resumeStep` delivers an event. */
+  waitForEvent?: boolean;
+  /**
+   * Optional saga rollback handler: on workflow failure the engine runs it once for
+   * this step (if it completed), in reverse dependency order. Receives the typed context plus
+   * the step's own `output` (what to undo). Best-effort — a throw is logged + surfaced.
+   */
+  compensate?: (ctx: TypedStepContext<TInput, TDeps, TContext> & {
+    output: TOutput;
+  }) => Promise<void> | void;
+}
+/**
+ * Define a type-safe workflow step with Zod validation. Wraps a typed handler
+ * into an untyped `StepHandler` with a 5-phase pipeline:
+ *
+ *   1. Parse `workflowInput` against `workflowInputSchema`
+ *   2. Parse each dependency output against its `outputSchema`
+ *   3. Build the typed context
+ *   4. Call the handler
+ *   5. Parse the output against `outputSchema`
+ *
+ * Validation errors are non-retryable (a schema mismatch is a programming error).
+ */
+declare function defineStep<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: DefineStepConfig<TInput, TOutput, TDeps, TContext>): TypedStep<TInput, TOutput, TDeps, TContext>;
+/**
+ * Define a **wait-for-event** step: once its dependencies complete, it suspends
+ * (status `waiting`) instead of running, until `engine.resumeStep(workflowId, stepKey,
+ * payload)` delivers an external event. The resume payload becomes the step's output
+ * (validated by dependents against `outputSchema`), then the DAG advances.
+ *
+ * Use for human-in-the-loop approvals, webhooks, or any async external dependency.
+ */
+declare function defineWaitStep<TOutput extends Record<string, unknown> = Record<string, unknown>, TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: {
+  type: string;
+  /** Shape of the event payload delivered via `resumeStep`. */
+  outputSchema: z.ZodType<TOutput>;
+  dependencies?: TDeps;
+}): TypedStep<Record<string, never>, TOutput, TDeps, TContext>;
+/**
+ * Define a **map** step: dynamic fan-out. `items(ctx)` produces a runtime-sized
+ * list from the step's deps/input; the engine spawns one child per item (each running
+ * `each(item, …)` with its own retry/timeout), suspends the parent as `mapping`, and
+ * completes it with `{ items: childOutputs[] }` (ordered) once all children finish. A
+ * failed item fails the whole map. Use for "do X for each of N images/sections/locales".
+ *
+ * The map step's output type is `{ items: TItemOutput[] }`; dependents read `deps.X.items`.
+ */
+declare function defineMapStep<TItem, TItemOutput extends Record<string, unknown>, TWorkflowInput extends Record<string, unknown> = Record<string, unknown>, TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: {
+  type: string;
+  workflowInputSchema: z.ZodType<TWorkflowInput>;
+  /** Schema for one item's output. */
+  itemOutputSchema: z.ZodType<TItemOutput>;
+  dependencies?: TDeps;
+  /** Produce the list of items to fan out over. */
+  items: (ctx: TypedStepContext<TWorkflowInput, TDeps, TContext>) => Promise<TItem[]> | TItem[];
+  /** Process one item. */
+  each: (item: TItem, info: {
+    index: number;
+    context: TContext;
+    workflowId: number;
+    partitionKey: string;
+  }) => Promise<TItemOutput> | TItemOutput;
+  /** Optional per-item retry policy. */
+  itemRetry?: RetryPolicy;
+  /** Per-item retryability predicate — see `defineStep`'s `isRetryable`. */
+  itemIsRetryable?: (error: unknown) => boolean;
+  /** Optional per-item wall-clock timeout in ms. */
+  itemTimeoutMs?: number;
+}): TypedStep<TWorkflowInput, {
+  items: TItemOutput[];
+}, TDeps, TContext>;
+/**
+ * Define a **sub-workflow** step: once its deps complete, `input(ctx)` maps the
+ * parent context to the child workflow's input; the engine **starts the child workflow**
+ * (sharing the partition), suspends this step as `waiting`, and resumes it with the child's
+ * output once the child terminates. A failed/cancelled child fails this step (and cascades).
+ *
+ * Pass the built child workflow (`buildWorkflow(...)`); its step handlers are registered
+ * automatically alongside the parent. The step's output type is the child's output shape —
+ * give `outputSchema` to type it for dependents (defaults to an opaque record).
+ */
+declare function defineSubWorkflowStep<TOutput extends Record<string, unknown> = Record<string, unknown>, TWorkflowInput extends Record<string, unknown> = Record<string, unknown>, TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: {
+  type: string;
+  workflowInputSchema: z.ZodType<TWorkflowInput>;
+  /** The built child workflow to start (`buildWorkflow(...)`) — must share the parent's `TContext`. */
+  childWorkflow: {
+    definition: WorkflowDefinition;
+    register: (registry: StepHandlerRegistry<TContext>) => void;
+  };
+  /** Map the parent step's context to the child workflow's input. */
+  input: (ctx: TypedStepContext<TWorkflowInput, TDeps, TContext>) => Promise<Record<string, unknown>> | Record<string, unknown>;
+  /** Shape of the child workflow's output (for typing dependents). Defaults to an opaque record. */
+  outputSchema?: z.ZodType<TOutput>;
+  dependencies?: TDeps;
+}): TypedStep<TWorkflowInput, TOutput, TDeps, TContext>;
+/**
+ * Define a durable **sleep** step: a no-op step that, once its dependencies complete,
+ * is held in the queue for `sleepMs` before completing — advancing the DAG afterwards.
+ * The delay is durable (survives restarts) because it lives in the queue, not in memory.
+ *
+ * A sleep step is just `defineStep` with `delayMs` and an empty handler; use this for
+ * cooldowns, "continue in 1 hour", or spacing out downstream work.
+ */
+declare function defineSleepStep<TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: {
+  type: string;
+  /** How long to sleep once the step becomes ready, in ms. */
+  sleepMs: number;
+  dependencies?: TDeps;
+}): TypedStep<Record<string, never>, Record<string, never>, TDeps, TContext>;
+/** Minimal engine surface `buildWorkflow().start()` needs — avoids a circular import. */
+interface StartableEngine {
+  startWorkflow(definition: WorkflowDefinition, input: Record<string, unknown>, options?: StartOptions): Promise<Result<WorkflowCreatedResult, FlowError>>;
+}
+interface TypedWorkflow<TInput extends Record<string, unknown>, TContext> {
+  readonly type: string;
+  readonly inputSchema: z.ZodType<TInput>;
+  readonly definition: WorkflowDefinition;
+  /** Register every step handler with a registry. */
+  register(registry: StepHandlerRegistry<TContext>): void;
+  /** Type-safe start with input validation. */
+  start(engine: StartableEngine, input: TInput, options?: StartOptions): Promise<Result<WorkflowCreatedResult, FlowError>>;
+}
+interface BuildWorkflowConfig<TInput extends Record<string, unknown>, TSteps extends Record<string, TypedStep<any, any, any, TContext>>, TContext> {
+  type: string;
+  inputSchema: z.ZodType<TInput>;
+  steps: TSteps;
+}
+/**
+ * Build a typed workflow from step definitions. Derives the `WorkflowDefinition`
+ * DAG from each step's dependency metadata and validates at construction time
+ * that every dependency key references a real step.
+ */
+declare function buildWorkflow<TInput extends Record<string, unknown>, TContext = unknown, TSteps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: BuildWorkflowConfig<TInput, TSteps, TContext>): TypedWorkflow<TInput, TContext>;
+//#endregion
+//#region src/core/public-view.d.ts
+/** The five states a UI renders. Suspensions display as in-flight. */
+type StepDisplayStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+declare const STEP_DISPLAY_STATUS_SCHEMA: z.ZodEnum<{
+  completed: "completed";
+  failed: "failed";
+  pending: "pending";
+  running: "running";
+  skipped: "skipped";
+}>;
+/**
+ * Engine step statuses folded to display states. `waiting` (suspended for an
+ * event), `mapping` (fan-out in flight), and `compensating` (rollback running)
+ * are all "still in flight" from a reader's point of view; a `compensated`
+ * step's work was undone, which reads as `skipped`, with the failure that
+ * triggered the rollback reported by the failed step itself. Exhaustive over
+ * {@link StepStatus} so a new engine status is a compile error here, not a
+ * silent hole in a consumer's API.
+ */
+declare const STEP_DISPLAY_STATUS: Record<StepStatus, StepDisplayStatus>;
+/** Fold one engine step status to its display state. */
+declare function toDisplayStepStatus(status: StepStatus): StepDisplayStatus;
+/** A step as served to API consumers. Timestamps are ISO strings. */
+interface PublicWorkflowStep {
+  id: number;
+  key: string;
+  type: string;
+  status: StepDisplayStatus;
+  dependencies: string[];
+  input: Record<string, unknown> | null;
+  output: Record<string, unknown> | null;
+  error: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+/** A workflow (with steps) as served to API consumers. Timestamps are ISO strings. */
+interface PublicWorkflow {
+  id: number;
+  type: string;
+  status: WorkflowWithSteps['status'];
+  input: Record<string, unknown>;
+  output: Record<string, unknown> | null;
+  error: string | null;
+  entityRef: string | null;
+  totalSteps: number;
+  completedSteps: number;
+  failedSteps: number;
+  steps: PublicWorkflowStep[];
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+declare const WORKFLOW_STATUS_SCHEMA: z.ZodEnum<{
+  cancelled: "cancelled";
+  completed: "completed";
+  failed: "failed";
+  pending: "pending";
+  running: "running";
+}>;
+declare const PUBLIC_WORKFLOW_STEP_SCHEMA: z.ZodObject<{
+  id: z.ZodNumber;
+  key: z.ZodString;
+  type: z.ZodString;
+  status: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    pending: "pending";
+    running: "running";
+    skipped: "skipped";
+  }>;
+  dependencies: z.ZodArray<z.ZodString>;
+  input: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  output: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  error: z.ZodNullable<z.ZodString>;
+  startedAt: z.ZodNullable<z.ZodString>;
+  completedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const PUBLIC_WORKFLOW_SCHEMA: z.ZodObject<{
+  id: z.ZodNumber;
+  type: z.ZodString;
+  status: z.ZodEnum<{
+    cancelled: "cancelled";
+    completed: "completed";
+    failed: "failed";
+    pending: "pending";
+    running: "running";
+  }>;
+  input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  output: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  error: z.ZodNullable<z.ZodString>;
+  entityRef: z.ZodNullable<z.ZodString>;
+  totalSteps: z.ZodNumber;
+  completedSteps: z.ZodNumber;
+  failedSteps: z.ZodNumber;
+  steps: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    key: z.ZodString;
+    type: z.ZodString;
+    status: z.ZodEnum<{
+      completed: "completed";
+      failed: "failed";
+      pending: "pending";
+      running: "running";
+      skipped: "skipped";
+    }>;
+    dependencies: z.ZodArray<z.ZodString>;
+    input: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    output: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    error: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodNullable<z.ZodString>;
+    completedAt: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  createdAt: z.ZodString;
+  startedAt: z.ZodNullable<z.ZodString>;
+  completedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Project a step record to its public view. Drops `workflowId` (redundant
+ * under the parent), `metadata`, `attempts`, and `parentStepId`; folds the
+ * status.
+ */
+declare function toPublicStep(step: StepRecord): PublicWorkflowStep;
+/**
+ * Project a workflow (with steps) to its public view. Drops `partitionKey`,
+ * `idempotencyKey`, `parentWorkflowId`/`parentStepId`, and `metadata`.
+ */
+declare function toPublicWorkflow(workflow: WorkflowWithSteps): PublicWorkflow;
+//#endregion
+export { StepError as A, WorkflowDefinition as B, FlowError as C, StepCompensateHandler as D, StartOptions as E, StepId as F, WorkflowWithSteps as G, WorkflowNotFoundError as H, StepRecord as I, err as J, FlowErrorShape as K, StepRegistration as L, StepHandler as M, StepHandlerNotFoundError as N, StepCompensationContext as O, StepHandlerRegistry as P, StepStatus as R, defineWaitStep as S, RetryPolicy as T, WorkflowRecord as U, WorkflowId as V, WorkflowStatus as W, ok as Y, buildWorkflow as _, STEP_DISPLAY_STATUS as a, defineStep as b, WORKFLOW_STATUS_SCHEMA as c, toPublicWorkflow as d, StepOutput as f, WorkflowOutput as g, TypedWorkflow as h, PublicWorkflowStep as i, StepExecutionContext as j, StepDefinition as k, toDisplayStepStatus as l, TypedStepContext as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, STEP_DISPLAY_STATUS_SCHEMA as o, TypedStep as p, Result as q, PublicWorkflow as r, StepDisplayStatus as s, PUBLIC_WORKFLOW_SCHEMA as t, toPublicStep as u, defineMapStep as v, InvalidWorkflowDefinitionError as w, defineSubWorkflowStep as x, defineSleepStep as y, WorkflowCreatedResult as z };