/**
 * A structured artifact battery for XML documents.
 *
 * @module @nhtio/adk/batteries/artifacts/xml
 *
 * @remarks
 * Provides {@link SpooledXmlArtifact} — a `SpooledArtifact` specialisation that parses XML
 * into a JSON projection and offers path-based query tools over that projection. The XML-to-JSON
 * mapping defaults to `ignoreAttributes: false` and `attributeNamePrefix: '_'`, both settable
 * per instance through the constructor; `preserveOrder: false` is fixed. Under the default
 * mapping:
 *
 * - Element attributes become keys prefixed with `_` (e.g., `root-element` with `href="x"`
 *   becomes `{ a: { _href: 'x', ... } }`).
 * - Element text content becomes a `#text` key when the element also has attributes or siblings.
 * - Repeated sibling elements collapse into an array.
 * - The full projection is queryable via JSONPath expressions (e.g., `$..name` finds all name
 *   elements anywhere in the tree). Attributes are accessed via underscore-prefixed keys,
 *   e.g. `$..["_href"]` for the href attribute (recursive descent).
 *
 * The battery also exports two converter `Tool` constants: `xmlToJsonTool` and `jsonToXmlTool`.
 * These accept either inline XML/JSON text or a reference to an artifact produced earlier in
 * the turn, and return the converted result as a new `SpooledJsonArtifact` or
 * `SpooledXmlArtifact`.
 *
 * Battery exceptions are defined in this module's `exceptions.ts` file — `createException`
 * re-exported from `@nhtio/adk/factories`. Decoding a {@link SpooledXmlArtifact} instance via
 * `decode()` throws until `registerArtifactEncodables()` has run (see
 * {@link @nhtio/adk/batteries/artifacts!registerArtifactEncodables}).
 */
import { SpooledJsonArtifact } from "../../../common";
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 } from "../../../types";
import type { ToolMethodDescriptor, DispatchContext } from "../../../types";
/** Snapshot payload for the encoder contract; the encoder treats it as opaque. */
type AdkEncodableSnapshot = unknown;
/**
 * A {@link @nhtio/adk!SpooledArtifact} specialisation that adds XML-aware read operations.
 *
 * @remarks
 * The artifact parses XML into a JSON projection on first access and caches it for the
 * lifetime of the instance. The projection uses `ignoreAttributes` and `attributeNamePrefix` as
 * supplied to the constructor — defaulting to `false` and `'_'` — with `preserveOrder: false`.
 *
 * Under this mapping, an XML element like:
 *
 * `root-element` with an `href` attribute and text content becomes a JSON object like:
 * `{ root: { element: { _href: 'value', '#text': 'content' } } }`
 *
 * Attributes are prefixed with `_` by default rather than the conventional `@_`, because
 * `jsonpath-plus` reads a leading `@` in a path segment as its type-selector sigil before
 * honouring quotes: `$..["@_href"]` throws `Unknown value type _hr`, while `$..["_href"]`
 * matches. Text nodes use the `#text` key.
 *
 * All XML methods are async, consistent with {@link @nhtio/adk!SpooledArtifact}.
 *
 * Path-based methods (`xml_get`, `xml_filter`, `xml_pluck`) use
 * [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath) expressions over the projection.
 * Full JSONPath syntax is supported, including recursive descent (`..`), filter expressions,
 * and union selectors.
 */
export declare class SpooledXmlArtifact extends SpooledArtifact {
    #private;
    /**
     * @param reader - The backing store to read from.
     * @param options - Optional parser configuration.
     * @param options.attributeNamePrefix - Prefix for attribute keys (default: '_'). Set to '@_'
     *   if you need the conventional XML-to-JSON mapping, but be aware that naming such a key in a
     *   JSONPath segment fails — `$..["@_attr"]` throws `Unknown value type _at`, and quoting does
     *   not escape it. A filter expression still reaches it (`$..[?(@['@_attr'])]`); a wildcard
     *   does too, but only when placed exactly one level above the key, so the working path
     *   depends on whether repeated elements collapsed into an array.
     * @param options.ignoreAttributes - When true, ignore element attributes (default: false).
     */
    constructor(reader: SpoolReader, options?: {
        attributeNamePrefix?: string;
        ignoreAttributes?: boolean;
    });
    /**
     * Returns `true` if `value` is a {@link SpooledXmlArtifact} instance.
     *
     * @remarks
     * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard. Safe against the
     * dual-module-copy case where two distinct `SpooledXmlArtifact` classes coexist in the same
     * realm.
     *
     * @param value - The value to test.
     * @returns `true` when `value` is a {@link SpooledXmlArtifact} instance.
     */
    static isSpooledXmlArtifact(value: unknown): value is SpooledXmlArtifact;
    /**
     * Returns the effective XML-to-JSON parser configuration for this artifact.
     *
     * @remarks
     * When converting an XML artifact to JSON by call_id, the converter inherits the source
     * artifact's attribute prefix and ignoreAttributes setting. This accessor exposes those
     * options so the converter can apply them consistently.
     *
     * @returns An object with `attributeNamePrefix` and `ignoreAttributes` keys.
     */
    getParserOptions(): {
        attributeNamePrefix: string;
        ignoreAttributes: boolean;
    };
    /**
     * The XML-specific artifact-query descriptors this class adds on top of the base set.
     *
     * @remarks
     * Lists `artifact_xml_root`, `artifact_xml_keys`, `artifact_xml_tags`, `artifact_xml_length`,
     * `artifact_xml_get`, `artifact_xml_filter`, `artifact_xml_pluck`. The base seven descriptors
     * (`artifact_head`, etc.) are NOT included here — they are forged separately by
     * {@link SpooledXmlArtifact.forgeTools}.
     */
    static toolMethods: ReadonlyArray<ToolMethodDescriptor>;
    /**
     * The root element name of the XML document.
     *
     * @returns The name of the root element.
     * @throws Error when the document is malformed or empty.
     */
    xml_root(): Promise<string>;
    /**
     * Keys directly under the root element.
     *
     * @returns Array of key names at the root level.
     */
    xml_keys(): Promise<string[]>;
    /**
     * Every distinct element name in the document, deduplicated.
     *
     * @remarks
     * Walks the entire projection recursively, excluding attribute keys (prefixed with the
     * configured `attributeNamePrefix`, default `_`) and `#text` keys. This is what a model
     * calls before it can write a path into an unfamiliar document.
     *
     * @returns Sorted array of unique element names.
     */
    xml_tags(): Promise<string[]>;
    /**
     * Element count when the root contains an array of children; otherwise 1.
     *
     * @returns Number of elements.
     */
    xml_length(): Promise<number>;
    /**
     * Query the document via JSONPath expression.
     *
     * @param path - A JSONPath expression (e.g., `'$..name'`).
     * @returns Array of matched values.
     */
    xml_get(path: string): Promise<unknown[]>;
    /**
     * Returns the elements (subtrees) that match a JSONPath expression.
     *
     * @remarks
     * Evaluates the path against the XML projection and returns the elements that
     * contain matching values. Unlike xml_get (which returns matched values), xml_filter
     * returns the element objects containing those matches.
     *
     * Candidate set definition for XML's single-rooted projection:
     * - If the root element contains an array of repeated siblings (e.g., root.item
     *   where item is an array property), filters across those siblings and returns
     *   elements that have matching content.
     * - If the root element contains a single object, evaluates the path against it
     *   and returns it when matched.
     *
     * The path is evaluated using JSONPath-Plus with resultType 'all' to extract
     * parent elements of matched values. The immediate parent object of any matched
     * value is included in the result, deduplicating elements.
     *
     * Example: for XML with root containing multiple 'item' elements each with an
     * 'id' attribute, xml_filter('$.root.item[*]._id') returns the item elements
     * that have an id attribute, whereas xml_get would return the id values themselves.
     *
     * @param path - A JSONPath expression (e.g. '$.root.item[*]._id' or '$[?(@.status)]').
     * @returns Array of matching element subtrees. Empty array when no matches found.
     */
    xml_filter(path: string): Promise<unknown[]>;
    /**
     * Alias for xml_get — extract values matching a JSONPath.
     *
     * @param path - A JSONPath expression (e.g., `'$..name'`).
     * @returns Array of matched values.
     */
    xml_pluck(path: string): Promise<unknown[]>;
    /**
     * 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 XML-specific descriptor narrowed to XML artifacts.
     */
    static forgeTools(ctx: DispatchContext): ToolRegistry;
    /**
     * Serialise this SpooledXmlArtifact into an `@nhtio/encoder` snapshot — the reader **handle**
     * plus the constructor options for `attributeNamePrefix` and `ignoreAttributes`.
     *
     * @remarks
     * Overrides {@link SpooledArtifact.[ENCODE_METHOD]} to carry the constructor's options
     * (the parsed projection cache is derived and not encoded). Round-trips via
     * {@link SpooledXmlArtifact.[DECODE_METHOD]}.
     *
     * @returns A snapshot consumed by {@link SpooledXmlArtifact.[DECODE_METHOD]}.
     */
    [ENCODE_METHOD](): AdkEncodableSnapshot;
    /**
     * Reconstruct a {@link SpooledXmlArtifact} from a {@link SpooledXmlArtifact.[ENCODE_METHOD]}
     * snapshot.
     *
     * @param data - The snapshot produced by {@link SpooledXmlArtifact.[ENCODE_METHOD]}.
     * @returns A fresh {@link SpooledXmlArtifact} backed by a freshly-resolved reader.
     */
    static [DECODE_METHOD](data: AdkEncodableSnapshot): SpooledXmlArtifact;
}
/**
 * A tool that converts XML (inline or from an artifact) to JSON.
 *
 * @remarks
 * Input is either `text` (inline XML) or `call_id` (an XML artifact from earlier in this turn).
 * Provide exactly one. Returns a new {@link SpooledJsonArtifact}.
 */
export declare const xmlToJsonTool: Tool<SpooledJsonArtifact<unknown>>;
/**
 * A tool that converts JSON (inline or from an artifact) to XML.
 *
 * @remarks
 * Input is either `text` (inline JSON) or `call_id` (a JSON artifact from earlier in this turn).
 * Provide exactly one. Returns a new {@link SpooledXmlArtifact}.
 *
 * Note: XML has no faithful JSON inverse. A JSON document that never came from XML may not
 * rebuild into sensible markup. This tool converts on a best-effort basis; the result may not
 * round-trip perfectly back to the original JSON.
 */
export declare const jsonToXmlTool: Tool<SpooledXmlArtifact>;
/**
 * Re-export the exceptions for battery-scoped error handling.
 *
 * @remarks
 * Battery exceptions are defined in `exceptions.ts` and re-exported here per the
 * battery-scoped-exceptions pattern — consumers of `@nhtio/adk/batteries/artifacts/xml`
 * can import these exception classes directly.
 */
export { E_XML_PARSER_PEER_MISSING, E_XML_PARSE_FAILED } from "./exceptions";