/**
 * TOON artifact battery — structured queries over TOON format artifacts.
 *
 * @module @nhtio/adk/batteries/artifacts/toon
 *
 * @remarks
 * Adds {@link SpooledToonArtifact}, a {@link @nhtio/adk!SpooledArtifact} specialisation for
 * structured TOON queries. TOON encodes the JSON data model in a compact text format; parsing
 * produces the same values as decoding JSON, so queries use {@link https://github.com/JSONPath-Plus/JSONPath JSONPath-Plus} for path navigation, exactly as {@link @nhtio/adk!SpooledJsonArtifact} does.
 *
 * Requires the optional peer `@toon-format/toon` (version `^4.1.1`). If it is not installed,
 * methods requiring it throw {@link E_TOON_PEER_MISSING} with installation instructions.
 *
 * Export note: {@link registerArtifactEncodables} must be called before any attempt to
 * `decode()` a spooled TOON artifact. Call it once at startup:
 *
 * ```ts
 * import { registerArtifactEncodables } from '@nhtio/adk/batteries/artifacts'
 * await registerArtifactEncodables()
 * ```
 */
import { Tool, ToolRegistry } from "../../../common";
declare const ENCODE_METHOD: unique symbol;
declare const DECODE_METHOD: unique symbol;
import { SpooledArtifact } from "../../../spooled_artifact";
import type { SpoolReader, ToolMethodDescriptor, DispatchContext } from "../../../types";
/** Snapshot payload for the encoder contract; the encoder treats it as opaque. */
type AdkEncodableSnapshot = unknown;
/**
 * TOON decode options.
 *
 * @remarks
 * Passed to the `@toon-format/toon` `decode` function.
 */
export interface ToonDecodeOptions {
    /** The indent size used in the TOON encoding (default: 2). */
    indentSize?: number;
    /** When `true`, reject non-standard TOON (default: `true`). */
    strict?: boolean;
}
/**
 * A {@link @nhtio/adk!SpooledArtifact} specialisation that adds TOON-aware read operations.
 *
 * @remarks
 * Construct with an optional `options` object to control decoding. When omitted, the TOON is
 * decoded with `strict: true` (default). Once decoded (on first access), the parsed value is
 * cached for the lifetime of the instance.
 *
 * All TOON methods are async, consistent with {@link @nhtio/adk!SpooledArtifact}.
 *
 * Path-based methods (`toon_get`, `toon_filter`, `toon_pluck`) use
 * [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath) expressions. Full JSONPath syntax
 * is supported, including recursive descent (`..`), filter expressions (`[?(@.age > 18)]`),
 * and union selectors.
 */
export declare class SpooledToonArtifact extends SpooledArtifact {
    #private;
    /**
     * @param reader - The backing store to read from.
     * @param options - Optional TOON decode options.
     */
    constructor(reader: SpoolReader, options?: ToonDecodeOptions);
    /**
     * Returns `true` if `value` is a {@link SpooledToonArtifact} instance.
     *
     * @remarks
     * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then
     * `Symbol.hasInstance`, then a `constructor.name` fallback. Matches the pattern used by every
     * other class guard in the ADK; safe against the dual-module-copy case where two distinct
     * `SpooledToonArtifact` classes coexist in the same realm.
     *
     * @param value - The value to test.
     * @returns `true` when `value` is a {@link SpooledToonArtifact} instance.
     */
    static isSpooledToonArtifact(value: unknown): value is SpooledToonArtifact;
    /**
     * The TOON-specific artifact-query descriptors this class adds on top of the base set.
     *
     * @remarks
     * Lists `artifact_toon_type`, `artifact_toon_keys`, `artifact_toon_length`,
     * `artifact_toon_get`, `artifact_toon_filter`, `artifact_toon_slice`, `artifact_toon_pluck`.
     * The base seven descriptors (`artifact_head`, etc.) are NOT included here — they are
     * forged separately by {@link SpooledToonArtifact.forgeTools}, which calls
     * `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then registers
     * its own TOON tools on the result. Downstream consumers building custom subclasses
     * should follow the same pattern: own only your own descriptors; override `forgeTools` to
     * compose with the base output.
     */
    static toolMethods: ReadonlyArray<ToolMethodDescriptor>;
    /**
     * Forges base-class tools plus TOON-specific tools narrowed to {@link SpooledToonArtifact}.
     *
     * @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 TOON-specific descriptor narrowed to TOON artifacts.
     * Downstream consumers building their own subclasses should follow the same shape.
     */
    static forgeTools(ctx: DispatchContext): ToolRegistry;
    /**
     * Returns the format of a TOON artifact.
     *
     * @remarks
     * Reports only the format name. The delimiter is deliberately not reported: the TOON decoder
     * exposes no delimiter information, and every method of inferring one from the source proved
     * unreliable for some class of strict-valid document. Four distinct approaches were attempted,
     * each defeated by its own edge case:
     * - Lexical scanning for the delimiter character failed on unquoted pipes inside values
     * - Anchored header regex requiring a word key failed on quoted keys and keyless root arrays
     * - Widened regex accepting quoted keys failed on escaped quotes within the key (e.g., "a\"b")
     * - Byte-exact round-trip re-encoding failed on non-canonical formatting (indentation, line
     *   endings, trailing newlines)
     *
     * Delimiter inference is no longer attempted: nothing in the model's workflow needs it, and
     * the TOON decoder is the source of truth for all document metadata.
     *
     * This result is cached after the first parse and returned identically on every call.
     *
     * @returns An object with `format: 'toon'`.
     */
    toon_type(): Promise<{
        format: string;
    }>;
    /**
     * Returns the top-level keys of the parsed TOON content.
     *
     * @remarks
     * - If the root is an object, returns its keys.
     * - If the root is not a plain object (e.g. an array or scalar), returns `undefined`.
     *
     * @returns Array of key strings, or `undefined` when the root is not an object.
     */
    toon_keys(): Promise<string[] | undefined>;
    /**
     * Returns the element count of the parsed TOON content.
     *
     * @remarks
     * - If the root is an array, returns the array length.
     * - Otherwise, returns `1` (the root is a single element).
     *
     * @returns The element count.
     */
    toon_length(): Promise<number>;
    /**
     * Evaluates a JSONPath expression against the parsed TOON content.
     *
     * @remarks
     * Uses [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath). Full JSONPath syntax is
     * supported: recursive descent (`$..*`), filter expressions (`$[?(@.age > 18)]`), union
     * selectors, and more.
     *
     * @param path - A JSONPath expression (e.g. `'$.user.address.city'`, `'$..name'`).
     * @returns Array of matched values. Empty array when no matches are found.
     */
    toon_get(path: string): Promise<unknown[]>;
    /**
     * Returns elements matched by a JSONPath filter expression.
     *
     * @remarks
     * Evaluates `path` against the root value and returns it in an array if matched.
     *
     * @param path - A JSONPath expression (e.g. `'$[?(@.status === "active")]'`).
     * @returns Array of matching elements (at most one element, the root if matched).
     */
    toon_filter(path: string): Promise<unknown[]>;
    /**
     * Returns a slice of the parsed content by index range.
     *
     * @remarks
     * - If the root is an array, behaves like `Array.prototype.slice`.
     * - If the root is not an array, returns the entire root in an array.
     *
     * @param start - Start index (inclusive). Defaults to `0`.
     * @param end - End index (exclusive). Defaults to the element count.
     * @returns Array of sliced elements.
     */
    toon_slice(start?: number, end?: number): Promise<unknown[]>;
    /**
     * Returns all values matched by a JSONPath expression.
     *
     * @remarks
     * Convenience over {@link SpooledToonArtifact.toon_get} with an identical signature — use
     * whichever name better communicates intent at the call site. `toon_pluck` reads well for
     * extracting a single field; `toon_get` reads well for structured queries.
     *
     * @param path - A JSONPath expression (e.g. `'$..name'`).
     * @returns Array of matched values.
     */
    toon_pluck(path: string): Promise<unknown[]>;
    /**
     * Serialise this SpooledToonArtifact into an `@nhtio/encoder` snapshot — the reader **handle** plus
     * the decode `options`.
     *
     * @remarks
     * Overrides {@link SpooledArtifact.[ENCODE_METHOD]} to carry the constructor's `options` (the
     * parsed-value cache is derived and not encoded). Round-trips via
     * {@link SpooledToonArtifact.[DECODE_METHOD]}.
     *
     * @returns A snapshot consumed by {@link SpooledToonArtifact.[DECODE_METHOD]}.
     */
    [ENCODE_METHOD](): AdkEncodableSnapshot;
    /**
     * Reconstruct a {@link SpooledToonArtifact} from a {@link SpooledToonArtifact.[ENCODE_METHOD]}
     * snapshot.
     *
     * @param data - The snapshot produced by {@link SpooledToonArtifact.[ENCODE_METHOD]}.
     * @returns A fresh {@link SpooledToonArtifact}} backed by a freshly-resolved reader.
     */
    static [DECODE_METHOD](data: AdkEncodableSnapshot): SpooledToonArtifact;
}
/**
 * Converter tool: TOON to JSON.
 *
 * @remarks
 * Accepts either inline TOON text or a reference to an artifact produced earlier in this turn.
 * Converts to JSON and returns a new {@link @nhtio/adk!SpooledJsonArtifact}.
 *
 * This is a plain {@link @nhtio/adk!Tool}, not an {@link @nhtio/adk!ArtifactTool} — the handler
 * returns the new artifact directly, allowing the forge to discover and query it on the next
 * iteration without explicit wiring.
 */
export declare const toonToJsonTool: Tool;
/**
 * Converter tool: JSON to TOON.
 *
 * @remarks
 * Accepts either inline JSON text or a reference to a JSON artifact produced earlier in this turn.
 * Converts to TOON and returns a new {@link SpooledToonArtifact}.
 *
 * This is a plain {@link @nhtio/adk!Tool}, not an {@link @nhtio/adk!ArtifactTool} — the handler
 * returns the new artifact directly, allowing the forge to discover and query it on the next
 * iteration without explicit wiring.
 */
export declare const jsonToToonTool: Tool;
/**
 * Exports for the public barrel.
 */
export { E_TOON_PEER_MISSING, E_TOON_DECODE_FAILED } from "./exceptions";