import type { FlowDefinition } from "./types.js";
/**
 * The filename suffixes a flow file may carry, in probe order. `.json` is the
 * legacy bare form and stays last so an explicit `.flow.json` wins a tie.
 *
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare const FLOW_FILE_EXTENSIONS: readonly [".flow.yaml", ".flow.yml", ".flow.json", ".json"];
/** A discovered flow paired with the file it was loaded from. */
export interface FlowFileEntry {
    flow: FlowDefinition;
    path: string;
}
/**
 * The conventional on-disk locations of flow `flowId` inside one `flows/` search
 * dir: the flat `<dir>/<id><ext>` and the per-flow-directory
 * `<dir>/<id>/<id><ext>`, for every {@link FLOW_FILE_EXTENSIONS}. Existence is
 * NOT checked. Shared with the CLI's `findFlowFile` so the naming convention has
 * exactly one definition.
 *
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare function flowFileCandidates(dirPath: string, flowId: string): string[];
/**
 * Load a single {@link FlowDefinition} from a YAML or JSON file on disk.
 *
 * Format detection is based on file extension:
 * - `.yaml` / `.yml` — parsed with the `yaml` library.
 * - Everything else  — parsed as JSON.
 *
 * @param filePath - Absolute path to the flow file.
 * @returns The parsed {@link FlowDefinition}.
 * @throws {Error} If the file does not exist, cannot be read, or fails to parse.
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare function loadFlow(filePath: string): FlowDefinition;
/**
 * Load every flow in a `flows/` directory, in both supported shapes, keeping the
 * file each one came from.
 *
 * Two tiers, and nothing else:
 * 1. **Flat** — a file directly in `dirPath` ending in one of {@link FLOW_FILE_EXTENSIONS}.
 * 2. **Per-flow directory** — `<dir>/<sub>/<sub><ext>`; the file MUST be named after
 *    its directory, which is what lets a flow keep sibling assets (README, fixtures,
 *    prompts) without them being parsed as flows.
 *
 * A subdirectory that holds something flow-shaped but no conventional file is
 * **reported** through `onWarn` rather than dropped silently — silence is the
 * defect this contract exists to remove. Files/dirs prefixed with `_` are the
 * explicit opt-out and stay silent. Parse failures are warned about and skipped,
 * never thrown.
 *
 * @param dirPath - Absolute path to the directory to scan.
 * @param opts.onWarn - Sink for warnings; defaults to `stderr`. Pass a no-op on
 *   hot paths where a probe miss is normal (e.g. resolving an arbitrary CLI arg).
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare function loadFlowEntriesFromDir(dirPath: string, opts?: {
    onWarn?: (message: string) => void;
}): FlowFileEntry[];
/**
 * Load all flows from a directory — {@link loadFlowEntriesFromDir} without the
 * originating file paths. See it for the two supported layouts, the warning
 * contract, and the `_`-prefix opt-out.
 *
 * @param dirPath - Absolute path to the directory to scan.
 * @returns Array of successfully parsed {@link FlowDefinition} objects. Empty if the
 *   directory does not exist or contains no valid flow files.
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare function loadFlowsFromDir(dirPath: string): FlowDefinition[];
/**
 * Discover every flow under a content root, keeping the file each came from.
 *
 * Covers both content-root layouts (`<root>/flows/` and `<root>/<domain>/flows/`)
 * via `assetSearchDirs`, and within each of those both flow layouts via
 * {@link loadFlowEntriesFromDir}. De-duped by **declared id**, first search dir
 * wins — the same identity every other flow surface resolves by.
 *
 * @param aiResourcesRoot - Absolute path to a content root (`ai-assets/` or equivalent).
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare function loadAllFlowEntries(aiResourcesRoot: string, opts?: {
    onWarn?: (message: string) => void;
}): FlowFileEntry[];
/**
 * Discover and load all flow definitions under a content root —
 * {@link loadAllFlowEntries} without the originating file paths.
 *
 * @param aiResourcesRoot - Absolute path to the `ai-assets/` directory (or equivalent
 *   resource root). Typically the `ai-assets/` folder at the monorepo root.
 * @returns Flat array of all successfully parsed {@link FlowDefinition} objects across
 *   all domains. Empty if the root directory does not exist.
 * @docLink packages/flow-engine/concepts#flow-loading
 */
export declare function loadAllFlows(aiResourcesRoot: string): FlowDefinition[];
//# sourceMappingURL=loader.d.ts.map