import { HsonNode } from "../../../core/types.js";
import { Tokens } from "../token.types.js";
import type { HsonSemanticPrimitive } from "../../../core/types.js";
import type { HsonSourceProvenanceBuilder } from "../../../internal/hson-source-provenance/hson-source-provenance.js";
export type ParseTokensOptions = Readonly<{
    /** Internal document admission for top-level text and exact zero-length source. */
    allowTopLevelDocumentText?: boolean;
}>;
/**
 * Create a canonical Hson leaf node from a primitive value.
 *
 * Rules:
 * - `string`  → `<_hson_str>` node with `$_content: [value]`.
 * - non-string primitive (`number | boolean | null`) → `<_hson_val>` node with `$_content: [value]`.
 *
 * Notes:
 * - Empty optional containers are omitted from leaf nodes created here.
 * - This is the preferred constructor for primitive payloads to keep string vs non-string
 *   semantics explicit in the IR.
 *
 * @param v - Primitive value to wrap as a leaf node.
 * @returns A new `HsonNode` using `_hson_str` or `_hson_val` depending on the runtime type of `v`.
 */
export declare const make_leaf: (v: HsonSemanticPrimitive) => HsonNode;
/**
 * Assemble a flat token stream into a hierarchical `HsonNode` tree.
 *
 * This is the second stage of the Hson parser: it consumes the output of
 * `tokenize_hson` and builds the final IR, enforcing the Hson clustering
 * and close-mode rules.
 *
 * High-level behavior:
 * - Walks the token array once, maintaining an index (`ix`) into `$tokens`.
 * - Uses `readTag` to assemble the scanner's lowered element and object-member
 *   token sequences (`OPEN`…`CLOSE`) into nodes. Angle closer classification
 *   and object-member grammar have already been resolved by the scanner.
 * - Uses `readArray` to parse `ARR_OPEN`…`ARR_CLOSE` sequences into
 *   `_hson_arr` nodes full of `_hson_ii` children, each tagged with `index`.
 * - Handles empty objects (`EMPTY_OBJ`, i.e. `<>`) both at
 *   top-level and inside arrays.
 * - Converts `TEXT` tokens into primitive leaves:
 *   - quoted text → `JSON.parse(raw)` to decode string literals
 *   - unquoted text → `coerce(raw)` for primitive inference
 *   then wraps the result with `make_leaf`.
 * - Tracks the close kind for each top-level construct in `topCloseKinds`
 *   so that implicit roots can be shaped correctly later.
 *
 * Root synthesis:
 * - If the sole top-level node is already `<_hson_root>`, return it directly.
 * - Otherwise, synthesize a `_hson_root` node according to the top-level shape:
 *   - A single cluster node (`_hson_obj`, `_hson_arr`, `_hson_elem`) is wrapped as-is.
 *   - A single standard element is wrapped in `_hson_elem` according to its
 *     recorded close kind.
 *   - A sole primitive leaf is attached directly beneath `_hson_root`.
 *   - No tokens remain an internal fallback state; `parse_hson` handles exact
 *     zero-length document source before tokenization and rejects all other
 *     tokenless source before that fallback can become a source result.
 *   - Multiple top-level elements form ordered document content. Multiple top-level
 *     object values reject because one object angle pair owns the full member
 *     collection; mixed structural modes also reject.
 *
 * Error handling:
 * - Any unexpected token kind in a given context (inside tags, arrays,
 *   or at the top level) results in a transform error.
 * - Missing closing tokens, malformed `_hson_root` / VSN shapes, or invalid
 *   payloads for special tags (e.g. `<_hson_val>`) also throw.
 *
 * @param tokens - Token array produced by `tokenize_hson`.
 * @returns A `_hson_root`-wrapped `HsonNode` representing the parsed Hson tree.
 * @see tokenize_hson
 * @see make_leaf
 */
export declare function parse_tokens(tokens: Tokens[], options?: ParseTokensOptions, provenance?: HsonSourceProvenanceBuilder): HsonNode;
//# sourceMappingURL=parse-tokens.d.ts.map