import type { EncodableValue } from "./types";
/**
 * The closed set of comparison operators a structured predicate leaf may name.
 *
 * `truthy` and `exists` take no `value`; every other operator requires one. The set is CLOSED —
 * `parseStructuredPredicate` refuses any other string with a model-addressed reason naming the
 * legal set, so a branch/select author cannot smuggle an operator no cell implements.
 */
export type PredicateOp = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'in' | 'contains' | 'truthy' | 'exists';
/**
 * A leaf predicate: read `path` from the readable context and compare it with `op`.
 *
 * `value` is optional because `truthy` and `exists` are unary — they need no right-hand side.
 * For every other operator `parseStructuredPredicate` requires `value` to be present.
 */
export interface PredicateLeaf {
    /** The dot-path into the readable context to read and compare. */
    path: string;
    /** The comparison operator. `truthy`/`exists` are unary and must not carry `value`. */
    op: PredicateOp;
    /** The right-hand side to compare against. Required for every operator except `truthy`/`exists`. */
    value?: EncodableValue;
}
/** A predicate that is satisfied only when EVERY member is satisfied. */
export interface AllPredicate {
    /** The member predicates; all must be satisfied. */
    all: StructuredPredicate[];
}
/** A predicate that is satisfied when AT LEAST ONE member is satisfied. */
export interface AnyPredicate {
    /** The member predicates; at least one must be satisfied. */
    any: StructuredPredicate[];
}
/** A predicate that is satisfied exactly when its single member is NOT satisfied. */
export interface NotPredicate {
    /** The member predicate; its negation is the result. */
    not: StructuredPredicate;
}
/**
 * The structured predicate IR — the value a branch/select node's `predicate` field holds when the
 * structured cell interprets it.
 *
 * A discriminated union of four shapes: a leaf (`{path, op, value?}`), and the three combinators
 * `{all}`, `{any}`, `{not}`. The combinator shapes are discriminated by their single key, and a
 * leaf by the presence of `path`/`op`. `parseStructuredPredicate` is the single authority that
 * turns an untrusted `EncodableValue` into this IR.
 */
export type StructuredPredicate = PredicateLeaf | AllPredicate | AnyPredicate | NotPredicate;
/**
 * Type guard for {@link PredicateLeaf}. A leaf is a plain object carrying a string `path` and a
 * string `op`; the `op` is narrowed to `PredicateOp` only when it is a member of the closed set.
 */
export declare const isPredicateLeaf: (v: unknown) => v is PredicateLeaf;
/**
 * Type guard for {@link AllPredicate}. An `all` combinator is a plain object whose sole
 * discriminator key `all` holds an array of structured predicates.
 */
export declare const isAllPredicate: (v: unknown) => v is AllPredicate;
/**
 * Type guard for {@link AnyPredicate}. An `any` combinator is a plain object whose sole
 * discriminator key `any` holds an array of structured predicates.
 */
export declare const isAnyPredicate: (v: unknown) => v is AnyPredicate;
/**
 * Type guard for {@link NotPredicate}. A `not` combinator is a plain object whose sole
 * discriminator key `not` holds a single structured predicate.
 */
export declare const isNotPredicate: (v: unknown) => v is NotPredicate;
/**
 * Type guard for the whole {@link StructuredPredicate} union. A value is a structured predicate
 * iff it is one of the four shapes. Because the combinator shapes are discriminated by their
 * single key and a leaf by `path`/`op`, the four guards are mutually exclusive.
 */
export declare const isStructuredPredicate: (v: unknown) => v is StructuredPredicate;
/**
 * The result of {@link parseStructuredPredicate}: either a validated predicate, or a
 * model-addressed reason naming the fix.
 */
export type ParsePredicateResult = {
    ok: true;
    predicate: StructuredPredicate;
} | {
    ok: false;
    reason: string;
};
/**
 * The deepest combinator nesting a structured predicate may carry.
 *
 * @remarks
 * Chosen well below the measured failure point rather than at it: evaluation begins throwing
 * `RangeError` around 5,000 levels on Node 24, and a limit tuned to one engine's stack size would
 * be a limit that shifts under the reader. 256 is far past anything a human or a model writes —
 * `all`/`any` take LISTS, so real predicates are wide, not deep — while leaving a very large
 * margin against the actual overflow.
 */
export declare const MAX_PREDICATE_DEPTH = 256;
/**
 * Validates an untrusted `EncodableValue` into the structured predicate IR.
 *
 * This is the single authority that turns a branch/select node's `predicate` field (typed
 * `EncodableValue` in the IR) into a {@link StructuredPredicate}. It never throws: every failure
 * returns `{ok: false, reason}` where `reason` is MODEL-ADDRESSED — it names the offending field
 * and the fix (for example, which operator is unknown and what the legal set is), so an authoring
 * model can correct the plan in one pass.
 *
 * The value is validated structurally, not by type alone: a leaf requires a string `path` and a
 * closed-set `op`; `truthy`/`exists` must not carry a `value` while every other operator must;
 * combinators require arrays of already-valid predicates (`all`/`any`) or a single one (`not`).
 * A value that is none of the four shapes is refused with a reason naming the shape it most
 * resembles, so the author knows what to change.
 *
 * @param value - The untrusted value to validate, as read from a plan's `predicate` field.
 * @returns A discriminated result: `{ok: true, predicate}` on success, or `{ok: false, reason}`
 *   naming the fix on failure.
 */
export declare const parseStructuredPredicate: (value: unknown, depth?: number) => ParsePredicateResult;
/**
 * Wraps a cell's `load()` so it is idempotent and converts a failed lazy `await import()` into
 * `E_ORCH_CELL_UNAVAILABLE`.
 *
 * A cell's `load()` is expected to resolve an optional ESM peer through a lazy `await import()`.
 * That import can fail (the package is not installed), and the failure must surface as a named
 * `E_ORCH_CELL_UNAVAILABLE` whose message names the missing package and its install command —
 * not as a raw module-resolution error the author cannot act on. This helper also makes `load()`
 * idempotent: the wrapped loader runs at most once, and every subsequent call resolves with the
 * same outcome, so a cell can be loaded once and reused across many plans without re-importing.
 *
 * The helper is deliberately minimal — it is a single idempotence + error-mapping wrapper, not a
 * plugin registry. A cell that needs to register itself with a consumer's registry does so in its
 * own `load()` body, before or after calling the wrapped loader.
 *
 * @param id - The cell's id, used to name the missing package in the error.
 * @param loader - The cell's actual load body (typically a lazy `await import()`).
 * @returns A wrapped loader that is idempotent and maps import failure to
 *   `E_ORCH_CELL_UNAVAILABLE`.
 */
export declare const loadOnce: (id: string, loader: () => Promise<void>) => (() => Promise<void>);