/**
 * YAML artifact battery: {@link SpooledYamlArtifact} and bidirectional converters.
 *
 * @remarks
 * Provides structured query tools for YAML documents, both single-document and
 * multi-document streams. Includes converter tools to transform between YAML and JSON
 * representations without materialising the artifact contents.
 *
 * Requires the optional peer `js-yaml@^4.1.1`. Install with:
 * ```
 * pnpm add js-yaml
 * ```
 *
 * Note: `decode()` on `SpooledYamlArtifact` instances throws until
 * `registerArtifactEncodables()` has been called.
 *
 * @module @nhtio/adk/batteries/artifacts/yaml
 */
import { E_YAML_PARSE_ERROR, E_YAML_PEER_MISSING } from "./exceptions";
import { Tool, ToolRegistry, SpooledJsonArtifact } from "../../../common";
import { SpooledArtifact } from "../../../spooled_artifact";
import type { SpoolReader } from "../../../common";
import type { ToolMethodDescriptor, DispatchContext } from "../../../types";
declare const ENCODE_METHOD: unique symbol;
declare const DECODE_METHOD: unique symbol;
/** Snapshot payload for the encoder contract; the encoder treats it as opaque. */
type AdkEncodableSnapshot = unknown;
/**
 * A {@link SpooledArtifact} specialisation that adds YAML-aware read operations.
 *
 * @remarks
 * Handles both single-document YAML and multi-document streams (delimited by `---`).
 * Parsed documents are cached in a private field for the lifetime of the instance.
 *
 * For multi-document streams:
 * - `yaml_length` reports the document count.
 * - `yaml_keys` returns the deduplicated union of keys across all documents.
 * - `yaml_get` / `yaml_filter` / `yaml_pluck` evaluate paths against all documents and return
 *   a flat array of all matches.
 *
 * Non-finite numbers (`.NaN`, `.inf`, `-.inf`) present in the YAML are preserved through the
 * `yaml_to_json` converter using a custom replacer.
 */
export declare class SpooledYamlArtifact extends SpooledArtifact {
    #private;
    /**
     * @param reader - The backing store to read from.
     * @param options - Optional configuration for parsing.
     * @param options.multiDocument - Declares the source's document mode. `true` parses as a
     *   stream and makes {@link SpooledYamlArtifact.yaml_type} report `'multi-document'` regardless
     *   of the current count. `false` asserts exactly one document and parses with `load`, so a
     *   `---` stream raises `E_YAML_PARSE_ERROR` instead of being silently accepted. When omitted,
     *   mode is auto-detected
     *   by parsing the content with `loadAll`.
     */
    constructor(reader: SpoolReader, options?: {
        multiDocument?: boolean;
    });
    /**
     * Returns `true` if `value` is a {@link SpooledYamlArtifact} instance.
     *
     * @remarks
     * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard. Safe against the
     * dual-module-copy case where two distinct `SpooledYamlArtifact` classes coexist in the
     * same realm.
     *
     * @param value - The value to test.
     * @returns `true` when `value` is a {@link SpooledYamlArtifact} instance.
     */
    static isSpooledYamlArtifact(value: unknown): value is SpooledYamlArtifact;
    /**
     * The YAML-specific artifact-query descriptors this class adds on top of the base set.
     *
     * @remarks
     * Lists `artifact_yaml_type`, `artifact_yaml_keys`, `artifact_yaml_length`,
     * `artifact_yaml_get`, `artifact_yaml_filter`, `artifact_yaml_slice`, `artifact_yaml_pluck`.
     * The base seven descriptors (`artifact_head`, etc.) are NOT included here — they are
     * forged separately by {@link SpooledYamlArtifact.forgeTools}.
     */
    static toolMethods: ReadonlyArray<ToolMethodDescriptor>;
    /**
     * Forges base-class tools plus YAML-specific tools narrowed to {@link SpooledYamlArtifact}.
     *
     * @remarks
     * Standard subclass extension pattern: call `SpooledArtifact.forgeTools(ctx)` to produce
     * the base seven `artifact_*` tools narrowed to any `SpooledArtifact` in the turn, then
     * register one `ArtifactTool` per YAML-specific descriptor narrowed to YAML artifacts.
     */
    static forgeTools(ctx: DispatchContext): ToolRegistry;
    /**
     * Returns whether this artifact contains a single document or multiple documents.
     *
     * @remarks
     * When the constructor was given `multiDocument: true`, the source is treated as a stream and
     * this reports `'multi-document'` even if that stream currently holds one document — a
     * one-element stream is still a stream, and {@link SpooledYamlArtifact.yaml_length} reports the
     * real count either way. `multiDocument: false` cannot disagree with the count, because parsing
     * a `---` stream under it fails outright rather than silently reporting the wrong mode.
     *
     * @returns `'single-document'` or `'multi-document'`.
     */
    yaml_type(): Promise<'single-document' | 'multi-document'>;
    /**
     * Returns the top-level keys of the parsed content.
     *
     * @remarks
     * For single-document: returns the keys of the root object, or `undefined` when the root
     * is not a plain object.
     * For multi-document: returns the union of keys across all documents that are plain objects.
     * Duplicate keys are deduplicated.
     *
     * @returns Array of key strings, or `undefined` when no object keys are present.
     */
    yaml_keys(): Promise<string[] | undefined>;
    /**
     * Returns the total number of documents in the artifact.
     *
     * @remarks
     * The result comes directly from js-yaml.loadAll(). For sources with no actual YAML content
     * (empty, whitespace-only, or BOM-only), the parser typically returns 0 documents, but certain
     * whitespace arrangements (such as a bare double newline) may yield 1. Do not rely on the exact
     * count to test for emptiness. For real documents, the count is reliable: a single-document
     * YAML returns 1, and a `---`-separated stream returns its exact document count.
     *
     * @returns The document count.
     */
    yaml_length(): Promise<number>;
    /**
     * Evaluates a JSONPath expression against the parsed documents.
     *
     * @remarks
     * For single-document: evaluates the expression against the root value.
     * For multi-document: evaluates the expression against each document and returns a flat
     * array of all matches across all documents.
     *
     * Uses [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath). Full JSONPath syntax is
     * supported.
     *
     * @param path - A JSONPath expression (e.g. `'$.user.address.city'`, `'$..name'`).
     * @returns Array of matched values. Empty array when no matches are found.
     */
    yaml_get(path: string): Promise<unknown[]>;
    /**
     * Returns documents matched by a JSONPath filter expression.
     *
     * @remarks
     * Evaluates `path` against each document and returns those for which the expression
     * produces at least one match.
     *
     * @param path - A JSONPath expression (e.g. `'$[?(@.status === "active")]'`).
     * @returns Array of matching documents.
     */
    yaml_filter(path: string): Promise<unknown[]>;
    /**
     * Returns a slice of documents by index range.
     *
     * @remarks
     * Behaves like `Array.prototype.slice` over the document array.
     *
     * @param start - Start index (inclusive). Defaults to `0`.
     * @param end - End index (exclusive). Defaults to the document count.
     * @returns Array of sliced documents.
     */
    yaml_slice(start?: number, end?: number): Promise<unknown[]>;
    /**
     * Returns all values matched by a JSONPath expression across every document.
     *
     * @remarks
     * Convenience over {@link yaml_get} with an identical signature — use whichever name
     * better communicates intent at the call site.
     *
     * @param path - A JSONPath expression (e.g. `'$..name'`).
     * @returns Array of matched values.
     */
    yaml_pluck(path: string): Promise<unknown[]>;
    /**
     * Serialise this SpooledYamlArtifact into an `@nhtio/encoder` snapshot.
     *
     * @remarks
     * Overrides {@link SpooledArtifact.[ENCODE_METHOD]} to carry the constructor's `multiDocument`
     * option. The parsed-document cache is derived and not encoded. Round-trips via
     * {@link SpooledYamlArtifact.[DECODE_METHOD]}.
     *
     * @returns A snapshot consumed by {@link SpooledYamlArtifact.[DECODE_METHOD]}.
     */
    [ENCODE_METHOD](): AdkEncodableSnapshot;
    /**
     * Reconstruct a {@link SpooledYamlArtifact} from a {@link SpooledYamlArtifact.[ENCODE_METHOD]}
     * snapshot.
     *
     * @param data - The snapshot produced by {@link SpooledYamlArtifact.[ENCODE_METHOD]}.
     * @returns A fresh {@link SpooledYamlArtifact}} backed by a freshly-resolved reader.
     */
    static [DECODE_METHOD](data: AdkEncodableSnapshot): SpooledYamlArtifact;
}
/**
 * Converter tool: YAML → JSON.
 *
 * @remarks
 * Takes either inline YAML text or a reference to a {@link SpooledYamlArtifact} produced
 * earlier in the turn. Converts to JSON and returns a fresh {@link SpooledJsonArtifact}
 * immediately queryable with JSON artifact tools.
 *
 * Non-finite numbers are preserved as their YAML token strings (`.NaN`, `.inf`, `-.inf`).
 * Undefined values are normalised to the JSON string `'null'`.
 */
export declare const yamlToJsonTool: Tool<SpooledJsonArtifact<unknown>>;
/**
 * Converter tool: JSON → YAML.
 *
 * @remarks
 * Takes either inline JSON text or a reference to a {@link SpooledJsonArtifact} produced
 * earlier in the turn. Converts to YAML and returns a fresh {@link SpooledYamlArtifact}}
 * immediately queryable with YAML artifact tools.
 */
export declare const jsonToYamlTool: Tool<SpooledYamlArtifact>;
export { E_YAML_PARSE_ERROR, E_YAML_PEER_MISSING };