Flows API reference

/**
 * Durable lifecycle states for a complete flow invocation.
 */
export declare const FLOW_RUN_STATUS: {
    readonly queued: "queued";
    readonly running: "running";
    readonly completed: "completed";
    readonly failed: "failed";
};
/**
 * Durable lifecycle states for one block occurrence in a run.
 */
export declare const FLOW_STEP_STATUS: {
    readonly pending: "pending";
    readonly queued: "queued";
    readonly running: "running";
    readonly waiting: "waiting";
    readonly completed: "completed";
    readonly failed: "failed";
};
/**
 * Ordered event types emitted while flow runs progress.
 */
export declare const FLOW_RUN_EVENT_TYPE: {
    readonly runCreated: "run.created";
    readonly runStarted: "run.started";
    readonly runCompleted: "run.completed";
    readonly runFailed: "run.failed";
    readonly runReplayed: "run.replayed";
    readonly stepQueued: "step.queued";
    readonly stepStarted: "step.started";
    readonly stepWaiting: "step.waiting";
    readonly stepLog: "step.log";
    readonly stepCompleted: "step.completed";
    readonly stepRetrying: "step.retrying";
    readonly stepFailed: "step.failed";
    readonly nestedStarted: "nested.started";
    readonly nestedCompleted: "nested.completed";
    readonly nestedFailed: "nested.failed";
};
/**
 * Supported replay sources for a new run.
 */
export declare const FLOW_REPLAY_DEFINITION: {
    readonly original: "original";
    readonly latest: "latest";
};
/** Durable flow-run status value. */
export type FlowRunStatus = typeof FLOW_RUN_STATUS[keyof typeof FLOW_RUN_STATUS];
/** Durable flow-step status value. */
export type FlowStepStatus = typeof FLOW_STEP_STATUS[keyof typeof FLOW_STEP_STATUS];
/** Ordered flow-run event type. */
export type FlowRunEventType = typeof FLOW_RUN_EVENT_TYPE[keyof typeof FLOW_RUN_EVENT_TYPE];
/** Definition source used to create a replayed run. */
export type FlowReplayDefinition = typeof FLOW_REPLAY_DEFINITION[keyof typeof FLOW_REPLAY_DEFINITION];

export * from './FlowInput.js';
export * from './FlowOutput.js';
export * from './Subflow.js';
import type { FlowBlockDefinition } from '../contracts/index.js';
/** Framework-owned structural blocks registered for every flow service. */
export declare const FLOW_SYSTEM_BLOCKS: FlowBlockDefinition[];

import type { FlowValues } from '../contracts/index.js';
/** Stable framework type for the visible public-input boundary node. */
export declare const FLOW_INPUT_BLOCK_TYPE = "flow.input";
/**
 * Framework-owned input boundary whose effective ports come from its flow.
 *
 * The fallback `value` port keeps an unspecialized designer node connectable.
 * The compiler replaces it with the source definition's complete input contract.
 */
export declare const FlowInput: import("../index.js").FlowBlockDefinition<FlowValues, FlowValues, FlowValues>;

import type { FlowValues } from '../contracts/index.js';
/** Stable framework type for the visible public-output boundary node. */
export declare const FLOW_OUTPUT_BLOCK_TYPE = "flow.output";
/**
 * Framework-owned output boundary whose effective ports come from its flow.
 *
 * Reaching this node terminates the current sequential run and exposes its
 * values through the public contract of the containing flow.
 */
export declare const FlowOutput: import("../index.js").FlowBlockDefinition<FlowValues, FlowValues, FlowValues>;

import type { FlowValues } from '../contracts/index.js';
/** Stable framework type for a definition-backed nested flow block. */
export declare const SUBFLOW_BLOCK_TYPE = "flow.subflow";
/**
 * Generic nested-flow placeholder resolved from its referenced definition.
 *
 * The fallback port allows a newly dropped placeholder to be connected before
 * its child definition is created. Once linked, the child contract replaces it.
 */
export declare const Subflow: import("../index.js").FlowBlockDefinition<FlowValues, FlowValues, FlowValues>;

export * from './FlowRun.js';
export * from './FlowRunEvent.js';
export * from './FlowStepRun.js';
import { FlowRun } from './FlowRun.js';
import { FlowRunEvent } from './FlowRunEvent.js';
import { FlowStepRun } from './FlowStepRun.js';
/**
 * Framework models an application installs when enabling durable flow runs.
 */
export declare const FLOW_MODELS: readonly [typeof FlowRun, typeof FlowStepRun, typeof FlowRunEvent];

import { QueueableJob, type QueueableJobContext } from '../queue/index.js';
/**
 * Serialized payload for one queue-backed flow block execution.
 */
export interface FlowStepJobData extends Record<string, unknown> {
    /** Durable flow run ULID. */
    runId: string;
    /** Block occurrence ULID from the run definition snapshot. */
    blockId: string;
}
/**
 * Queueable job that delegates one block execution to the active app Flows service.
 */
export declare class FlowStepJob extends QueueableJob<FlowStepJobData> {
    static readonly jobName = "flow.step";
    /**
     * Creates a durable block step job.
     *
     * @param data - Flow run and block identity.
     */
    constructor(data: FlowStepJobData);
    /**
     * Executes the durable step through the application-scoped Flows service.
     *
     * @param context - Claimed queue job metadata.
     */
    handle(context: QueueableJobContext): Promise<void>;
}

import type { QueueJob } from '../queue/index.js';
import type { FlowBlockMetadata, FlowDefinition, FlowDefinitionSummary, FlowDefinitionWriteOptions, FlowReplayOptions, FlowRunOptions, FlowValues, FlowsOptions, StoredFlowDefinition } from './contracts/index.js';
import { FlowBlockRegistry } from './FlowBlockRegistry.js';
import { FlowRun, FlowRunEvent, FlowStepRun } from './models/index.js';
/**
 * Durable run details returned to APIs and development inspectors.
 */
export interface FlowRunDetails {
    /** Flow run summary and immutable definition snapshot. */
    run: FlowRun;
    /** Block step states in execution order. */
    steps: FlowStepRun[];
    /** Ordered lifecycle and log events. */
    events: FlowRunEvent[];
}
/**
 * Application-scoped flow definition, execution, observability, and replay service.
 */
export declare class Flows {
    #private;
    private readonly options;
    /** Source-of-truth definition provider exposed for advanced app integrations. */
    readonly definitions: import("./contracts/index.js").FlowDefinitionStore;
    /** Registered executable block types. */
    readonly blocks: FlowBlockRegistry;
    /**
     * Creates an application flow service over the existing queue and models.
     *
     * @param options - Queue, definition store, block types, and runtime limits.
     */
    constructor(options: FlowsOptions);
    /**
     * Lists current source definitions from the configured provider.
     *
     * @returns Available flow definition summaries.
     */
    listDefinitions(): Promise<FlowDefinitionSummary[]>;
    /**
     * Loads and validates one source definition.
     *
     * @param id - Stable flow ULID.
     * @returns Stored definition and provider metadata.
     */
    definition(id: string): Promise<StoredFlowDefinition>;
    /**
     * Validates and persists one definition through the configured provider.
     *
     * @param definition - Source-of-truth graph to save.
     * @param options - Optional revision and creation path.
     * @returns Stored definition and new revision.
     */
    saveDefinition(definition: FlowDefinition, options?: FlowDefinitionWriteOptions): Promise<StoredFlowDefinition>;
    /**
     * Returns registered block metadata for palettes and inspectors.
     *
     * @returns Designer-safe block metadata.
     */
    blockMetadata(): FlowBlockMetadata[];
    /**
     * Creates and queues a new run of the latest stored definition.
     *
     * @param flowId - Stable flow ULID.
     * @param input - Public flow input values.
     * @param options - Optional replay relationship metadata.
     * @returns Newly-created durable flow run.
     */
    run(flowId: string, input: FlowValues, options?: FlowRunOptions): Promise<FlowRun>;
    /**
     * Replays a historical run using its original snapshot or the latest source.
     *
     * @param runId - Historical flow run ULID.
     * @param options - Definition source and optional replacement input.
     * @returns Newly-created linked replay run.
     */
    replay(runId: string, options?: FlowReplayOptions): Promise<FlowRun>;
    /**
     * Lists recent runs, optionally restricted to one source flow.
     *
     * @param flowId - Optional source flow ULID.
     * @param limit - Maximum rows to return.
     * @returns Recent runs ordered newest first.
     */
    listRuns(flowId?: string, limit?: number): Promise<FlowRun[]>;
    /**
     * Loads one run with ordered block steps and timeline events.
     *
     * @param runId - Flow run ULID.
     * @returns Complete durable run details.
     */
    runDetails(runId: string): Promise<FlowRunDetails>;
    /**
     * Executes one queued block step and advances the durable run.
     *
     * This method is public for FlowStepJob and should not be called directly by
     * application routes.
     *
     * @param runId - Flow run ULID.
     * @param blockId - Block occurrence ULID.
     * @param queueJob - Claimed queue job metadata.
     */
    processStep(runId: string, blockId: string, queueJob: QueueJob): Promise<void>;
}

import type { Queue } from '../../queue/index.js';
import type { AppDatabaseProvider } from '../../server/index.js';
import type { FlowBlockDefinition } from './FlowBlock.js';
import type { FlowDefinitionStore } from './FlowDefinitionStore.js';
/**
 * Dependencies and limits used by one application-scoped Flows service.
 */
export interface FlowsOptions {
    /** Existing application queue used to execute durable block jobs. */
    queue: Queue;
    /** Definition provider used to load and save source-of-truth graphs. */
    definitions: FlowDefinitionStore;
    /** Executable block types available to this application. */
    blocks: FlowBlockDefinition[];
    /** Queue/channel used for flow step jobs. Defaults to `flows`. */
    queueName?: string;
    /** Maximum queue attempts for each block step. Defaults to 3. */
    maxTries?: number;
    /** Maximum serialized input or output size retained per boundary. */
    maxPayloadBytes?: number;
}
/**
 * Minimal application shape required by queue-rehydrated flow step jobs.
 */
export interface FlowStepJobApp extends AppDatabaseProvider {
    /** Application-scoped flow service. */
    flows: {
        /**
         * Executes one durable step claimed by the queue.
         *
         * @param runId - Flow run ULID.
         * @param blockId - Block occurrence ULID.
         * @param job - Claimed queue job metadata.
         */
        processStep(runId: string, blockId: string, job: import('../../queue/index.js').QueueJob): Promise<void>;
    };
}

import type { FlowValueDefinitions, FlowValues } from './FlowValue.js';
/**
 * Position persisted for a block in compatible graph designers.
 */
export interface FlowBlockPosition {
    /** Horizontal canvas coordinate. */
    x: number;
    /** Vertical canvas coordinate. */
    y: number;
}
/**
 * One configured occurrence of a registered block type inside a flow.
 */
export interface FlowBlockInstance {
    /** Stable ULID for this block occurrence. */
    id: string;
    /** Registered executable block type. */
    type: string;
    /** Optional instance label overriding the block type name in the designer. */
    name?: string;
    /** JSON-safe configuration supplied to the block when it runs. */
    config?: FlowValues;
    /** Designer position stored with the source-of-truth definition. */
    position: FlowBlockPosition;
    /** Optional nested flow id when this instance executes another flow. */
    flowId?: string;
}
/**
 * Serializable input/output contract captured for one resolved block occurrence.
 *
 * Generic subflow and flow-boundary blocks derive their ports from a referenced
 * definition rather than from a statically registered block file. Runs retain
 * this resolved contract so queued steps and replay do not depend on later edits.
 */
export interface FlowResolvedBlockContract {
    /** Named values accepted by the resolved block occurrence. */
    inputs: FlowValueDefinitions;
    /** Named values emitted by the resolved block occurrence. */
    outputs: FlowValueDefinitions;
}
/**
 * One directed value connection between named block ports.
 */
export interface FlowConnection {
    /** Stable ULID for this graph connection. */
    id: string;
    /** Source block occurrence ULID. */
    sourceBlockId: string;
    /** Named output port on the source block. */
    sourcePort: string;
    /** Target block occurrence ULID. */
    targetBlockId: string;
    /** Named input port on the target block. */
    targetPort: string;
}
/**
 * Serializable source-of-truth graph executed by the flow runtime.
 */
export interface FlowDefinition {
    /** Definition schema version used for future compatible migrations. */
    schemaVersion: 1;
    /** Stable ULID used to invoke and reference this flow. */
    id: string;
    /** Human-readable flow name. */
    name: string;
    /** Optional longer explanation for developers and AI tooling. */
    description?: string;
    /** Public input contract accepted when the flow is invoked. */
    inputs: FlowValueDefinitions;
    /** Public output contract returned by the terminal block. */
    outputs: FlowValueDefinitions;
    /** Configured block occurrences in the graph. */
    blocks: FlowBlockInstance[];
    /** Directed connections between block ports. */
    connections: FlowConnection[];
}
/**
 * Immutable execution snapshot produced from one source flow definition.
 *
 * Resolution data is stored only on durable runs. Definition providers continue
 * to read and write the smaller `FlowDefinition` source shape.
 */
export interface FlowExecutionDefinition extends FlowDefinition {
    /** Effective dynamic contracts keyed by block occurrence ULID. */
    resolvedBlocks: Record<string, FlowResolvedBlockContract>;
    /** Immediate child snapshots keyed by flow-backed block occurrence ULID. */
    nestedDefinitions: Record<string, StoredNestedFlowDefinition>;
}
/**
 * Stored child definition captured as part of a parent execution snapshot.
 */
export interface StoredNestedFlowDefinition {
    /** Fully resolved child definition used when the nested block is reached. */
    definition: FlowExecutionDefinition;
    /** Definition-provider revision captured with the child source. */
    revision: string;
    /** Optional provider-relative source path. */
    path?: string;
}
/**
 * Lightweight definition metadata used by flow lists and selectors.
 */
export interface FlowDefinitionSummary {
    /** Stable flow ULID. */
    id: string;
    /** Human-readable flow name. */
    name: string;
    /** Optional developer-facing description. */
    description?: string;
    /** Public input contract exposed when this flow is used as a subflow block. */
    inputs: FlowValueDefinitions;
    /** Public output contract exposed when this flow is used as a subflow block. */
    outputs: FlowValueDefinitions;
    /** Current content revision returned by the definition provider. */
    revision: string;
    /** Provider-relative source path, when one exists. */
    path?: string;
}

import type { FlowBlockInstance } from './FlowDefinition.js';
import type { FlowValue, FlowValueDefinitions, FlowValues } from './FlowValue.js';
/**
 * Severity attached to one durable block log entry.
 */
export type FlowLogLevel = 'debug' | 'info' | 'warning' | 'error';
/** Execution strategy owned by a registered block type. */
export type FlowBlockKind = 'function' | 'flow';
/**
 * Runtime information and services exposed to an executing block function.
 */
export interface FlowBlockContext<TConfig extends FlowValues = FlowValues> {
    /** Flow definition currently being executed. */
    flowId: string;
    /** Durable run ULID. */
    runId: string;
    /** Durable step-run ULID. */
    stepRunId: string;
    /** Configured block occurrence being executed. */
    block: FlowBlockInstance;
    /** Validated block configuration with defaults applied. */
    config: TConfig;
    /**
     * Records an ordered durable log entry for this block.
     *
     * @param level - Log severity.
     * @param message - Human-readable log message.
     * @param data - Optional structured diagnostic data.
     */
    log(level: FlowLogLevel, message: string, data?: FlowValue): Promise<void>;
}
/**
 * Executable block type registered with a Flows service.
 */
export interface FlowBlockDefinition<TInput extends FlowValues = FlowValues, TOutput extends FlowValues = FlowValues, TConfig extends FlowValues = FlowValues> {
    /** Stable namespaced type used by serialized flow definitions. */
    type: string;
    /** Whether this block executes a function or delegates to a nested flow. */
    kind?: FlowBlockKind;
    /** Human-readable block type name. */
    name: string;
    /** Optional explanation shown in block palettes and inspectors. */
    description?: string;
    /** Whether this block safely preserves a value when automatically inserted on a compatible connection. */
    insertable?: boolean;
    /** Named values accepted by the block function. */
    inputs: FlowValueDefinitions;
    /** Named values returned by the block function. */
    outputs: FlowValueDefinitions;
    /** Serializable configuration fields shown in the block inspector. */
    config?: FlowValueDefinitions;
    /**
     * Executes the block with validated input and runtime context.
     *
     * @param input - Values assembled from the flow input or incoming connections.
     * @param context - Durable run context, configuration, and logging API.
     * @returns Values emitted through the block output ports.
     */
    run?(input: TInput, context: FlowBlockContext<TConfig>): TOutput | Promise<TOutput>;
}
/**
 * Designer-safe metadata for one registered executable block type.
 */
export type FlowBlockMetadata = Omit<FlowBlockDefinition, 'run'>;

/**
 * JSON-safe value that can cross a flow block boundary or be persisted in a run.
 */
export type FlowValue = string | number | boolean | null | FlowValue[] | {
    [key: string]: FlowValue;
};
/**
 * Named JSON-safe values received or returned by a flow block.
 */
export type FlowValues = Record<string, FlowValue>;
/**
 * Value kinds understood by the initial flow validator and designer inspector.
 */
export type FlowValueType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'json';
/**
 * Optional presentation hints for definition-driven input and configuration forms.
 *
 * Runtime validation does not depend on these values. Hosts may map `component`
 * names such as `DomTextInput` or `DomJsonInput` to their own component registry.
 */
export interface FlowValueEditorDefinition {
    /** Host component name preferred for this value. */
    component?: string;
    /** Human-readable field label overriding the serialized value name. */
    label?: string;
    /** Optional empty-value guidance rendered by compatible editors. */
    placeholder?: string;
    /** Preferred textarea row count for multiline or JSON values. */
    rows?: number;
}
/**
 * Serializable schema for one block port or configuration value.
 */
export interface FlowValueDefinition {
    /** Value kind used for validation and editor controls. */
    type: FlowValueType;
    /** Whether the value must be present and non-null. */
    required?: boolean;
    /** Human-readable explanation shown by development tools. */
    description?: string;
    /** Default value applied when block configuration omits the field. */
    default?: FlowValue;
    /** Optional host-agnostic form renderer hints. */
    editor?: FlowValueEditorDefinition;
}
/**
 * Named schemas for block ports or configuration values.
 */
export type FlowValueDefinitions = Record<string, FlowValueDefinition>;

import type { FlowReplayDefinition } from '../constants.js';
import type { FlowValue, FlowValues } from './FlowValue.js';
/**
 * Structured error snapshot stored on failed runs and block steps.
 */
export interface FlowErrorSnapshot {
    /** Error class or provider name. */
    name: string;
    /** Human-readable failure message. */
    message: string;
    /** Optional stack trace captured in development/runtime logs. */
    stack?: string;
}
/**
 * Options controlling creation of a new flow run.
 */
export interface FlowRunOptions {
    /** Optional run ULID that this invocation replays. */
    replayOfRunId?: string;
}
/**
 * Options controlling which definition snapshot a replay executes.
 */
export interface FlowReplayOptions {
    /** Whether to execute the original snapshot or the latest stored definition. */
    definition?: FlowReplayDefinition;
    /** Optional replacement public input for the replay. */
    input?: FlowValues;
}
/**
 * Durable log entry requested by an executing block.
 */
export interface FlowBlockLogInput {
    /** Log severity. */
    level: 'debug' | 'info' | 'warning' | 'error';
    /** Human-readable log message. */
    message: string;
    /** Optional structured diagnostic value. */
    data?: FlowValue;
}

import type { FlowDefinition, FlowDefinitionSummary } from './FlowDefinition.js';
/**
 * Definition plus provider metadata required for conflict-safe editing.
 */
export interface StoredFlowDefinition {
    /** Parsed and validated source-of-truth definition. */
    definition: FlowDefinition;
    /** Content revision used for optimistic concurrency. */
    revision: string;
    /** Provider-relative source path, when one exists. */
    path?: string;
}
/**
 * Options used when saving one flow definition.
 */
export interface FlowDefinitionWriteOptions {
    /** Previously-read revision that must still match before replacement. */
    expectedRevision?: string;
    /** Optional provider-relative path used when creating a new definition. */
    path?: string;
}
/**
 * Storage boundary shared by local file definitions and future hosted drivers.
 */
export interface FlowDefinitionStore {
    /**
     * Lists available definitions without requiring callers to know provider paths.
     *
     * @returns Available flow summaries.
     */
    list(): Promise<FlowDefinitionSummary[]>;
    /**
     * Loads one definition by stable flow ULID.
     *
     * @param id - Flow ULID.
     * @returns Stored definition or null when absent.
     */
    read(id: string): Promise<StoredFlowDefinition | null>;
    /**
     * Creates or replaces one definition.
     *
     * @param definition - Valid flow definition to persist.
     * @param options - Revision and optional creation path.
     * @returns Newly stored definition metadata.
     */
    write(definition: FlowDefinition, options?: FlowDefinitionWriteOptions): Promise<StoredFlowDefinition>;
}

import type { FlowDefinition, FlowDefinitionStore, FlowDefinitionSummary, FlowDefinitionWriteOptions, StoredFlowDefinition } from '../contracts/index.js';
/**
 * Options for a Git-friendly file definition provider.
 */
export interface FileFlowDefinitionStoreOptions {
    /** Directory containing `flow.json` or `*.flow.json` definitions. */
    root: string;
}
/**
 * Error thrown when a save would overwrite a newer definition revision.
 */
export declare class FlowDefinitionConflictError extends Error {
    readonly id: string;
    /**
     * Creates a revision conflict error.
     *
     * @param id - Flow definition ULID.
     */
    constructor(id: string);
}
/**
 * Stores source-of-truth flow definitions as deterministic project JSON files.
 */
export declare class FileFlowDefinitionStore implements FlowDefinitionStore {
    #private;
    /**
     * Creates a file definition provider rooted inside one project.
     *
     * @param options - File provider options.
     */
    constructor(options: FileFlowDefinitionStoreOptions);
    /**
     * Lists every readable definition beneath the configured root.
     *
     * @returns Flow summaries ordered by name.
     */
    list(): Promise<FlowDefinitionSummary[]>;
    /**
     * Loads one definition by its stable flow ULID.
     *
     * @param id - Flow ULID.
     * @returns Stored definition or null.
     */
    read(id: string): Promise<StoredFlowDefinition | null>;
    /**
     * Creates or atomically replaces one deterministic JSON definition file.
     *
     * @param definition - Definition to persist.
     * @param options - Optional expected revision and creation path.
     * @returns Stored definition metadata after writing.
     */
    write(definition: FlowDefinition, options?: FlowDefinitionWriteOptions): Promise<StoredFlowDefinition>;
}

import type { FlowBlockDefinition, FlowValues } from './contracts/index.js';
/**
 * Preserves generic block input, output, and configuration types while exposing
 * the plain one-file block contract used by the runtime.
 *
 * @param definition - Executable block definition.
 * @returns The same definition with its inferred generic types intact.
 *
 * @example
 * export default defineBlock({
 * 	type: 'text.uppercase',
 * 	name: 'Uppercase',
 * 	inputs: { text: { type: 'string', required: true } },
 * 	outputs: { text: { type: 'string', required: true } },
 * 	run: input => ({ text: input.text.toUpperCase() }),
 * });
 */
export declare function defineBlock<TInput extends FlowValues, TOutput extends FlowValues, TConfig extends FlowValues = FlowValues>(definition: FlowBlockDefinition<TInput, TOutput, TConfig>): FlowBlockDefinition<TInput, TOutput, TConfig>;

import type { FlowBlockDefinition, FlowBlockMetadata } from './contracts/index.js';
/**
 * Runtime registry resolving serialized block type names into executable functions.
 */
export declare class FlowBlockRegistry {
    #private;
    /**
     * Creates a registry and optionally registers initial block types.
     *
     * @param blocks - Block definitions available to the runtime.
     */
    constructor(blocks?: FlowBlockDefinition[]);
    /**
     * Registers one executable block type.
     *
     * @param block - Block definition to register.
     */
    register(block: FlowBlockDefinition): void;
    /**
     * Resolves one registered block type.
     *
     * @param type - Serialized block type name.
     * @returns Registered block definition or null.
     */
    get(type: string): FlowBlockDefinition | null;
    /**
     * Resolves one block type or throws a developer-facing error.
     *
     * @param type - Serialized block type name.
     * @returns Registered block definition.
     */
    require(type: string): FlowBlockDefinition;
    /**
     * Returns serializable metadata for block palettes and inspectors.
     *
     * @returns Registered block metadata ordered by display name.
     */
    metadata(): FlowBlockMetadata[];
}

import type { CompiledFlowDefinition, FlowDefinition, FlowExecutionDefinition } from './contracts/index.js';
import { FlowBlockRegistry } from './FlowBlockRegistry.js';
/**
 * Validates serialized flow graphs and produces deterministic sequential plans.
 */
export declare class FlowCompiler {
    #private;
    private readonly blocks;
    /**
     * Creates a compiler backed by the executable block registry.
     *
     * @param blocks - Registered block types available to definitions.
     */
    constructor(blocks: FlowBlockRegistry);
    /**
     * Validates and compiles one source definition into execution order.
     *
     * The initial compiler deliberately accepts only one connected sequential path.
     * Multiple port connections may exist between adjacent blocks, but branching,
     * merging, and cycles are rejected until their runtime semantics are explicit.
     *
     * @param definition - Parsed flow definition or durable execution snapshot.
     * @returns Validated sequential execution plan.
     */
    compile(definition: FlowDefinition | FlowExecutionDefinition): CompiledFlowDefinition;
}

import type { FlowBlockDefinition } from './FlowBlock.js';
import type { FlowBlockInstance, FlowConnection, FlowExecutionDefinition } from './FlowDefinition.js';
/**
 * Executable block occurrence with its resolved type and graph connections.
 */
export interface CompiledFlowBlock {
    /** Zero-based execution position in the sequential graph. */
    sequence: number;
    /** Configured block occurrence from the source definition. */
    instance: FlowBlockInstance;
    /** Registered executable block type. */
    block: FlowBlockDefinition;
    /** Connections supplying this block's input values. */
    incoming: FlowConnection[];
    /** Connections carrying this block's output values forward. */
    outgoing: FlowConnection[];
}
/**
 * Validated sequential execution plan derived from a flow definition snapshot.
 */
export interface CompiledFlowDefinition {
    /** Definition snapshot used to produce this plan. */
    definition: FlowExecutionDefinition;
    /** Blocks in deterministic execution order. */
    blocks: CompiledFlowBlock[];
    /** Root block receiving the public flow input. */
    root: CompiledFlowBlock;
    /** Terminal block producing the public flow output. */
    terminal: CompiledFlowBlock;
}

import type { FlowValue, FlowValueDefinition, FlowValueDefinitions, FlowValues } from './contracts/index.js';
/**
 * Validates and normalizes named values against a serializable flow schema.
 *
 * @param values - Unknown values supplied by a run, connection, or block configuration.
 * @param definitions - Named schema definitions.
 * @param label - Developer-facing location used in validation errors.
 * @returns JSON-safe values with configured defaults applied.
 */
export declare function validateFlowValues(values: unknown, definitions: FlowValueDefinitions, label: string): FlowValues;
/**
 * Tests whether a value matches one serializable flow value definition.
 *
 * @param value - Value to test.
 * @param definition - Expected value definition.
 * @returns True when the value is JSON-safe and type-compatible.
 */
export declare function matchesDefinition(value: unknown, definition: FlowValueDefinition): value is FlowValue;
/**
 * Returns true when an unknown value can be persisted as flow JSON.
 *
 * @param value - Unknown value to inspect.
 * @returns True for recursive JSON-safe values.
 */
export declare function isFlowValue(value: unknown): value is FlowValue;
/**
 * Creates a detached JSON-safe copy suitable for persistence and block isolation.
 *
 * @param value - JSON-safe value to clone.
 * @returns Detached value.
 */
export declare function cloneFlowValue(value: FlowValue): FlowValue;

/**
 * One actionable validation issue found in a serialized flow definition.
 */
export interface FlowDefinitionIssue {
    /** Definition path associated with the issue. */
    path: string;
    /** Human-readable explanation. */
    message: string;
}
/**
 * Error thrown when a flow definition cannot be compiled safely.
 */
export declare class FlowDefinitionError extends Error {
    readonly issues: FlowDefinitionIssue[];
    /**
     * Creates an aggregate validation error.
     *
     * @param issues - Actionable definition issues.
     */
    constructor(issues: FlowDefinitionIssue[]);
}

import type { FlowErrorSnapshot } from './contracts/index.js';
/**
 * Converts an unknown thrown value into a JSON-safe durable error snapshot.
 *
 * @param error - Unknown thrown value.
 * @returns Structured error suitable for run and step models.
 */
export declare function flowErrorSnapshot(error: unknown): FlowErrorSnapshot;

import { ActiveRecord, type FieldBuilder } from '../../db/index.js';
import type { EntityRef } from '../../db/fields/LinkField.js';
import { type FlowReplayDefinition, type FlowRunStatus } from '../constants.js';
import type { FlowErrorSnapshot, FlowExecutionDefinition, FlowValues } from '../contracts/index.js';
/**
 * Durable invocation of one immutable flow definition snapshot.
 */
export declare class FlowRun extends ActiveRecord {
    static table: string;
    static primaryKey: string;
    static labelFields: string[];
    static comment: string;
    /**
     * Defines persisted flow-run identity, snapshot, lifecycle, and result fields.
     *
     * @param field - ActiveRecord field builder.
     * @returns Flow run field definitions.
     */
    static fields(field: FieldBuilder): {
        id: import("../../db/index.js").UlidField;
        flowId: import("../../db/index.js").StringField;
        flowName: import("../../db/index.js").StringField;
        status: import("../../db/index.js").ChoiceStringField;
        replayDefinition: import("../../db/index.js").ChoiceStringField;
        definitionRevision: import("../../db/index.js").StringField;
        definitionSnapshot: import("../../db/index.js").JsonStringField<FlowExecutionDefinition>;
        input: import("../../db/index.js").JsonStringField<FlowValues>;
        output: import("../../db/index.js").JsonStringField<FlowValues>;
        error: import("../../db/index.js").JsonStringField<FlowErrorSnapshot>;
        replayOf: import("../../db/index.js").LinkField<FlowRun>;
        parentRun: import("../../db/index.js").LinkField<FlowRun>;
        parentBlockId: import("../../db/index.js").StringField;
        startedAt: import("../../db/index.js").TimestampField;
        completedAt: import("../../db/index.js").TimestampField;
        createdAt: import("../../db/index.js").TimestampField;
        updatedAt: import("../../db/index.js").TimestampField;
    };
    id: string | null;
    flowId: string | null;
    flowName: string | null;
    status: FlowRunStatus | null;
    replayDefinition: FlowReplayDefinition | null;
    definitionRevision: string | null;
    definitionSnapshot: FlowExecutionDefinition | null;
    input: FlowValues | null;
    output: FlowValues | null;
    error: FlowErrorSnapshot | null;
    replayOf: EntityRef<FlowRun> | null;
    parentRun: EntityRef<FlowRun> | null;
    parentBlockId: string | null;
    startedAt: Date | null;
    completedAt: Date | null;
    createdAt: Date | null;
    updatedAt: Date | null;
}

import { ActiveRecord, type FieldBuilder } from '../../db/index.js';
import type { EntityRef } from '../../db/fields/LinkField.js';
import { type FlowStepStatus } from '../constants.js';
import type { FlowErrorSnapshot, FlowValues } from '../contracts/index.js';
import { FlowRun } from './FlowRun.js';
/**
 * Durable execution state for one block occurrence within a flow run.
 */
export declare class FlowStepRun extends ActiveRecord {
    static table: string;
    static primaryKey: string;
    static labelFields: string[];
    static comment: string;
    /**
     * Defines the durable per-block execution schema.
     *
     * @param field - ActiveRecord field builder.
     * @returns Flow step-run field definitions.
     */
    static fields(field: FieldBuilder): {
        id: import("../../db/index.js").UlidField;
        run: import("../../db/index.js").LinkField<FlowRun>;
        blockId: import("../../db/index.js").StringField;
        blockType: import("../../db/index.js").StringField;
        blockName: import("../../db/index.js").StringField;
        sequence: import("../../db/index.js").IntegerField;
        status: import("../../db/index.js").ChoiceStringField;
        attempt: import("../../db/index.js").IntegerField;
        queueJobId: import("../../db/index.js").StringField;
        nestedRun: import("../../db/index.js").LinkField<FlowRun>;
        input: import("../../db/index.js").JsonStringField<FlowValues>;
        output: import("../../db/index.js").JsonStringField<FlowValues>;
        error: import("../../db/index.js").JsonStringField<FlowErrorSnapshot>;
        startedAt: import("../../db/index.js").TimestampField;
        completedAt: import("../../db/index.js").TimestampField;
        createdAt: import("../../db/index.js").TimestampField;
        updatedAt: import("../../db/index.js").TimestampField;
    };
    id: string | null;
    run: EntityRef<FlowRun>;
    blockId: string | null;
    blockType: string | null;
    blockName: string | null;
    sequence: number | null;
    status: FlowStepStatus | null;
    attempt: number | null;
    queueJobId: string | null;
    nestedRun: EntityRef<FlowRun> | null;
    input: FlowValues | null;
    output: FlowValues | null;
    error: FlowErrorSnapshot | null;
    startedAt: Date | null;
    completedAt: Date | null;
    createdAt: Date | null;
    updatedAt: Date | null;
}

import { ActiveRecord, type FieldBuilder } from '../../db/index.js';
import type { EntityRef } from '../../db/fields/LinkField.js';
import { type FlowRunEventType } from '../constants.js';
import type { FlowLogLevel, FlowValue } from '../contracts/index.js';
import { FlowRun } from './FlowRun.js';
import { FlowStepRun } from './FlowStepRun.js';
/**
 * Ordered durable lifecycle or log event emitted during a flow run.
 */
export declare class FlowRunEvent extends ActiveRecord {
    static table: string;
    static primaryKey: string;
    static labelFields: string[];
    static comment: string;
    /**
     * Defines ordered flow event fields and run-local sequence constraints.
     *
     * @param field - ActiveRecord field builder.
     * @returns Flow run event field definitions.
     */
    static fields(field: FieldBuilder): {
        id: import("../../db/index.js").UlidField;
        run: import("../../db/index.js").LinkField<FlowRun>;
        stepRun: import("../../db/index.js").LinkField<FlowStepRun>;
        sequence: import("../../db/index.js").IntegerField;
        type: import("../../db/index.js").ChoiceStringField;
        level: import("../../db/index.js").ChoiceStringField;
        message: import("../../db/index.js").StringField;
        data: import("../../db/index.js").JsonStringField<FlowValue>;
        createdAt: import("../../db/index.js").TimestampField;
    };
    id: string | null;
    run: EntityRef<FlowRun>;
    stepRun: EntityRef<FlowStepRun> | null;
    sequence: number | null;
    type: FlowRunEventType | null;
    level: FlowLogLevel | null;
    message: string | null;
    data: FlowValue | null;
    createdAt: Date | null;
}