import { ToolRegistry } from "./tool_registry";
import { ENCODE_METHOD, DECODE_METHOD } from "../utils/encoder_symbols";
import { SpooledArtifact } from "./spooled_artifact";
import type { AdkEncodableSnapshot } from "./encodable";
import type { SpoolReader } from "../contracts/spool_reader";
import type { ToolMethodDescriptor } from "./spooled_artifact";
import type { DispatchContext } from "../contracts/dispatch_context";
/**
 * The set of JSON-derived formats that {@link SpooledJsonArtifact} can handle.
 *
 * @remarks
 * - `json` — a single JSON value spanning the entire artifact (strict RFC 8259).
 * - `json5` — a single JSON5 value spanning the entire artifact; permits comments, trailing
 *   commas, unquoted keys, and other relaxed syntax via the `json5` package.
 * - `jsonl` — newline-delimited JSON; each non-empty line is an independent JSON value.
 * - `ndjson` — alias for `jsonl`; both names are accepted and behave identically.
 */
export type JsonArtifactFormat = 'json' | 'json5' | 'jsonl' | 'ndjson';
/**
 * A {@link @nhtio/adk!SpooledArtifact} specialisation that adds JSON-aware read operations.
 *
 * @typeParam T - The expected shape of each parsed record. Defaults to `unknown`.
 *
 * @remarks
 * Construct with an optional `format` hint. When omitted the format is auto-detected on first
 * access by reading the full artifact and inferring the format. Once detected (or
 * provided), the format is cached for the lifetime of the instance.
 *
 * All JSON methods are async, consistent with {@link @nhtio/adk!SpooledArtifact}.
 *
 * Path-based methods (`json_get`, `json_filter`, `json_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 SpooledJsonArtifact<T = unknown> extends SpooledArtifact {
    #private;
    /**
     * @param reader - The backing store to read from.
     * @param format - Optional format hint. When omitted, the format is inferred on first access.
     */
    constructor(reader: SpoolReader, format?: JsonArtifactFormat);
    /**
     * Returns `true` if `value` is a {@link SpooledJsonArtifact} 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
     * `SpooledJsonArtifact` classes coexist in the same realm.
     *
     * @param value - The value to test.
     * @returns `true` when `value` is a {@link SpooledJsonArtifact} instance.
     */
    static isSpooledJsonArtifact(value: unknown): value is SpooledJsonArtifact;
    /**
     * The JSON-specific artifact-query descriptors this class adds on top of the base set.
     *
     * @remarks
     * Lists `artifact_json_type`, `artifact_json_keys`, `artifact_json_length`,
     * `artifact_json_get`, `artifact_json_filter`, `artifact_json_slice`, `artifact_json_pluck`.
     * The base seven descriptors (`artifact_head`, etc.) are NOT included here — they are
     * forged separately by {@link SpooledJsonArtifact.forgeTools}, which calls
     * `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then registers
     * its own JSON 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 JSON-specific tools narrowed to {@link SpooledJsonArtifact}.
     *
     * @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 JSON-specific descriptor narrowed to JSON artifacts.
     * Downstream consumers building their own subclasses should follow the same shape.
     */
    static forgeTools(ctx: DispatchContext): ToolRegistry;
    /**
     * Returns the detected or provided format for this artifact.
     *
     * @returns One of `'json'`, `'json5'`, `'jsonl'`, or `'ndjson'`.
     */
    json_type(): Promise<JsonArtifactFormat>;
    /**
     * Returns the top-level keys of the parsed content.
     *
     * @remarks
     * - For `json`/`json5`: returns the keys of the root object, or `undefined` when the root is
     *   not a plain object (e.g. an array or scalar).
     * - For `jsonl`/`ndjson`: returns the union of keys across all records that are plain objects.
     *   Duplicate keys are deduplicated.
     *
     * @returns Array of key strings, or `undefined` when no object keys are present.
     */
    json_keys(): Promise<string[] | undefined>;
    /**
     * Returns the total number of records in the artifact.
     *
     * @remarks
     * - For `json`/`json5`: always `1` (the entire artifact is a single value).
     * - For `jsonl`/`ndjson`: the number of non-empty lines.
     *
     * @returns The record count.
     */
    json_length(): Promise<number>;
    /**
     * Evaluates a JSONPath expression against the parsed 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.
     *
     * - For `json`/`json5`: evaluates the expression against the root value.
     * - For `jsonl`/`ndjson`: evaluates the expression against each record and returns a flat
     *   array of all matches across all records.
     *
     * @param path - A JSONPath expression (e.g. `'$.user.address.city'`, `'$..name'`).
     * @returns Array of matched values. Empty array when no matches are found.
     */
    json_get(path: string): Promise<unknown[]>;
    /**
     * Returns a slice of the parsed records by index range.
     *
     * @remarks
     * For `json`/`json5`: always returns `[root]` — the artifact is a single record so slicing is
     * not meaningful. For `jsonl`/`ndjson`: behaves like `Array.prototype.slice`.
     *
     * @param start - Start index (inclusive). Defaults to `0`.
     * @param end - End index (exclusive). Defaults to the record count.
     * @returns Array of sliced records.
     */
    json_slice(start?: number, end?: number): Promise<T[]>;
    /**
     * Returns records matched by a JSONPath filter expression.
     *
     * @remarks
     * Evaluates `path` against each record and returns those for which the expression produces at
     * least one match. For `json`/`json5`, evaluates 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 records.
     */
    json_filter(path: string): Promise<T[]>;
    /**
     * Returns all values matched by a JSONPath expression across every record.
     *
     * @remarks
     * Convenience over {@link SpooledJsonArtifact.json_get} with an identical signature — use
     * whichever name better communicates intent at the call site. `json_pluck` reads well for
     * extracting a single field column; `json_get` reads well for structured queries.
     *
     * @param path - A JSONPath expression (e.g. `'$..name'`).
     * @returns Array of matched values.
     */
    json_pluck(path: string): Promise<unknown[]>;
    /**
     * Serialise this SpooledJsonArtifact into an `@nhtio/encoder` snapshot — the reader **handle** plus
     * the `format` discriminator.
     *
     * @remarks
     * Overrides {@link SpooledArtifact.[ENCODE_METHOD]} to carry the constructor's `format` hint (the
     * parsed-record cache is derived and not encoded). Round-trips via
     * {@link SpooledJsonArtifact.[DECODE_METHOD]}.
     *
     * @returns A snapshot consumed by {@link SpooledJsonArtifact.[DECODE_METHOD]}.
     */
    [ENCODE_METHOD](): AdkEncodableSnapshot;
    /**
     * Reconstruct a {@link SpooledJsonArtifact} from a {@link SpooledJsonArtifact.[ENCODE_METHOD]}
     * snapshot.
     *
     * @param data - The snapshot produced by {@link SpooledJsonArtifact.[ENCODE_METHOD]}.
     * @returns A fresh {@link SpooledJsonArtifact} backed by a freshly-resolved reader.
     */
    static [DECODE_METHOD](data: AdkEncodableSnapshot): SpooledJsonArtifact;
}