/**
 * Enumerate all possible traversal paths through a Bridge.
 *
 * Every bridge has a finite set of execution paths ("traversals"),
 * determined by the wire structure alone — independent of runtime values.
 *
 * Examples:
 *   `o <- i.a || i.b catch i.c`  →  3 traversals (primary, fallback, catch)
 *   `o <- i.arr[] as a { .data <- a.a ?? a.b }`  →  3 traversals
 *      (empty-array, primary for .data, nullish fallback for .data)
 *
 * The traversal manifest is a static analysis result. At runtime, the
 * execution engine produces a compact numeric `executionTraceId` (bitmask)
 * that records which traversal paths were actually taken. Use
 * {@link decodeExecutionTrace} to map the bitmask back to entries.
 */
import type { Bridge, WireSourceEntry, SourceLocation, Expression } from "./types.ts";
/**
 * A single traversal path through a bridge wire.
 */
export interface TraversalEntry {
    /** Stable identifier for this traversal path. */
    id: string;
    /** Index of the originating wire in `bridge.wires` (-1 for synthetic entries like empty-array). */
    wireIndex: number;
    /** Target path segments from the wire's `to` NodeRef. */
    target: string[];
    /** Classification of this traversal path. */
    kind: "primary" | "fallback" | "catch" | "empty-array" | "scope" | "then" | "else" | "const";
    /**
     * When `true`, this entry represents the error path for its source —
     * the source threw an exception that was not caught by the wire's own
     * `catch` handler.
     *
     * Error entries are only generated for sources that can throw (tool
     * calls without `?.` root-safe navigation).  When the wire already
     * carries a `catch` clause, individual source error entries are
     * omitted because the catch absorbs them.
     */
    error?: true;
    /** Fallback chain index (only when kind is `"fallback"`). */
    fallbackIndex?: number;
    /** Gate type (only when kind is `"fallback"`): `"falsy"` for `||`, `"nullish"` for `??`. */
    gateType?: "falsy" | "nullish";
    /** Bit position in the execution trace bitmask (0-based). */
    bitIndex: number;
    /** Source span for the specific traversal branch, when known. */
    loc?: SourceLocation;
    /** Source span covering the entire wire (full line), when known. */
    wireLoc?: SourceLocation;
    /**
     * Human-readable description of the source for this path.
     * Examples: `"api.username"`, `"|| \"Anonymous\""`, `"catch continue"`, `"= \"SBB\""`.
     */
    description?: string;
}
/**
 * Build the static traversal manifest for a bridge.
 *
 * Entries are sorted lexicographically by semantic ID before bit indices
 * are assigned, guaranteeing ABI stability across source-code reorderings.
 */
export declare function buildTraversalManifest(bridge: Bridge): TraversalEntry[];
/**
 * Build traversal manifest and runtime trace maps from a Bridge's Statement[] body.
 *
 * Entries are sorted lexicographically by semantic ID before bit indices
 * are assigned. This guarantees the bitmask encoding is stable across
 * source-code reorderings (ABI stability).
 *
 * Returns:
 * - `manifest` — the ordered TraversalEntry[] (for decoding, coverage checks)
 * - `chainBitsMap` — Map<WireSourceEntry[], TraceWireBits> for O(1) runtime lookups
 *   (keyed by the `sources` array reference, shared between original and scope-prefixed copies)
 * - `emptyArrayBits` — Map<Expression, number> keyed by ArrayExpression reference for
 *   O(1) runtime lookups in evaluateArrayExpr
 */
export declare function buildBodyTraversalMaps(bridge: Bridge): {
    manifest: TraversalEntry[];
    chainBitsMap: Map<WireSourceEntry[], TraceWireBits>;
    emptyArrayBits: Map<Expression, number>;
};
/**
 * Decode a runtime execution trace bitmask against a traversal manifest.
 *
 * Returns the subset of {@link TraversalEntry} objects whose bits are set
 * in the trace — i.e. the paths that were actually taken during execution.
 *
 * @param manifest  The static manifest from {@link buildTraversalManifest}.
 * @param trace     The bigint bitmask produced by the execution engine.
 */
export declare function decodeExecutionTrace(manifest: TraversalEntry[], trace: bigint): TraversalEntry[];
/**
 * Per-wire bit positions used by the execution engine to record which
 * traversal paths were taken.  Built once per bridge from the manifest.
 */
export interface TraceWireBits {
    /** Bit index for the primary / then / const path. */
    primary?: number;
    /** Bit index for the else branch (conditional wires only). */
    else?: number;
    /** Bit indices for each fallback gate (same order as `fallbacks` array). */
    fallbacks?: number[];
    /** Bit index for the catch path. */
    catch?: number;
    /** Bit index for the primary / then source error path. */
    primaryError?: number;
    /** Bit index for the else source error path (conditional wires only). */
    elseError?: number;
    /** Bit indices for each fallback source error path. */
    fallbackErrors?: number[];
    /** Bit index for the catch source error path. */
    catchError?: number;
}
/**
 * Build a lookup map from array-iterator path keys to their "empty-array"
 * trace bit positions.
 */
export declare function buildEmptyArrayBitsMap(manifest: TraversalEntry[]): Map<string, number>;
//# sourceMappingURL=enumerate-traversals.d.ts.map