@nhtio/adk 0.1.0-master-f0aa531d

package/lib/classes/spooled_artifact.d.ts

@@ -0,0 +1,296 @@
+import { ToolRegistry } from "./tool_registry";
+import { TokenEncoding } from "./tokenizable";
+import type { ObjectSchema } from '@nhtio/validation';
+import type { SpoolReader } from "../contracts/spool_reader";
+import type { DispatchContext } from "../contracts/dispatch_context";
+/**
+ * Constructor signature for {@link SpooledArtifact} and any subclass.
+ *
+ * @remarks
+ * Used by {@link @nhtio/adk!Tool} to declare the artifact subclass the consumer should use when wrapping
+ * the handler's serialised output. The variadic rest parameter accommodates subclass-specific
+ * constructor arguments (e.g. `SpooledJsonArtifact(reader, format?)`).
+ *
+ * @typeParam A - The {@link SpooledArtifact} subtype the constructor produces.
+ */
+export type SpooledArtifactConstructor<A extends SpooledArtifact = SpooledArtifact> = new (reader: SpoolReader, ...rest: any[]) => A;
+/**
+ * Metadata table entry for one of the artifact's existing query methods, used by
+ * {@link SpooledArtifact.forgeTools} to surface that method as an {@link @nhtio/adk!ArtifactTool}.
+ *
+ * @remarks
+ * This is a metadata shape, not a general method → tool pipeline. `forgeTools` knows how to
+ * marshal arguments for a fixed, closed set of method names (the base seven on
+ * {@link SpooledArtifact} and the JSON/Markdown methods on the bundled subclasses); a
+ * descriptor is the place to attach a tool name, description, args schema, and optional
+ * serializer to one of those methods. Adding a descriptor for a method whose name is not
+ * in that closed set will produce a tool whose handler invokes the method with no arguments.
+ *
+ * For new methods that require custom argument marshalling, branching, multi-step logic,
+ * cross-artifact joins, or any other behaviour beyond "call this existing method," override
+ * {@link SpooledArtifact.forgeTools} and mint the {@link @nhtio/adk!ArtifactTool} directly — do not try
+ * to express it through a descriptor.
+ *
+ * Zero-arg methods are the exception: a descriptor with no `argsSchema` (or one that adds
+ * only `callId`-adjacent fields you don't consume) works for any method that takes no
+ * arguments, regardless of name.
+ */
+export interface ToolMethodDescriptor {
+    /** Absolute tool name as exposed to the LLM (e.g. `'artifact_head'`). */
+    name: string;
+    /** Method to invoke on the resolved artifact instance (e.g. `'head'`, `'json_get'`). */
+    method: string;
+    /** Human-readable description passed to the model. Should mention "in this turn" so the model understands the artifact's lifecycle scope. */
+    description: string;
+    /** Schema for the method's own args, NOT including `callId`. `forgeTools()` injects `callId`. */
+    argsSchema?: ObjectSchema;
+    /** Optional formatter for non-string return values. Defaults: string → as-is; string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`. */
+    serialise?: (result: unknown) => string;
+}
+/**
+ * Default serialiser for {@link @nhtio/adk!ArtifactTool} handler return values when a descriptor does not
+ * provide its own. Exported for reuse by subclass `forgeTools` overrides.
+ *
+ * @param result - The artifact-method return value.
+ * @returns A string suitable for inclusion in an LLM tool-call response.
+ */
+export declare const defaultSerialise: (result: unknown) => string;
+/**
+ * A lazy, line-oriented view over an arbitrary backing store.
+ *
+ * @remarks
+ * All I/O methods are async to remain compatible with both in-memory and streaming
+ * {@link @nhtio/adk!SpoolReader} implementations. Token estimation delegates to
+ * {@link @nhtio/adk!Tokenizable.estimateTokens} — the same backends used elsewhere in the ADK.
+ *
+ * The class is read-only by design: mutation of the underlying data is the responsibility of the
+ * producer that created the {@link @nhtio/adk!SpoolReader}, not the consumer reading from this artifact.
+ */
+export declare class SpooledArtifact {
+    #private;
+    /**
+     * The set of artifact-query methods this class surfaces via {@link SpooledArtifact.forgeTools}.
+     *
+     * @remarks
+     * The base set covers the generic line-oriented operations every artifact supports:
+     * `artifact_head`, `artifact_tail`, `artifact_grep`, `artifact_cat`, `artifact_byte_length`,
+     * `artifact_line_count`, `artifact_estimate_tokens`. Each `toolMethods` array lists **only**
+     * its own class's descriptors — subclasses do not concatenate inherited descriptors. The
+     * subclass instead overrides {@link SpooledArtifact.forgeTools} to merge the base registry
+     * (produced by `SpooledArtifact.forgeTools(ctx)`) with its own — see
+     * {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for
+     * the canonical shape and the pattern downstream consumers should follow when building
+     * their own `SpooledArtifact` subclasses.
+     *
+     * Tool names are absolute (not subclass-prefixed). Forged tools carry
+     * `Tool.onCollision = 'replace'` so merging multiple subclasses' `forgeTools()` outputs is
+     * silent — every same-named tool dispatches the same method on whatever artifact the
+     * `callId` resolves to, so the overlap is behaviourally interchangeable.
+     *
+     * Frozen at module load.
+     */
+    static toolMethods: ReadonlyArray<ToolMethodDescriptor>;
+    /**
+     * @param reader - The backing store to read from.
+     * @throws {@link @nhtio/adk!E_NOT_A_SPOOL_READER} when `reader` does not implement {@link @nhtio/adk!SpoolReader}.
+     */
+    constructor(reader: SpoolReader);
+    /**
+     * Returns the line at the given 0-based index, or `undefined` when out of range.
+     *
+     * @remarks
+     * Protected so subclasses can scan the backing store line-by-line without allocating
+     * intermediate arrays. Delegates directly to the {@link @nhtio/adk!SpoolReader}.
+     *
+     * @param index - 0-based line index.
+     * @returns The raw line string, or `undefined` when out of range.
+     */
+    protected line(index: number): Promise<string | undefined>;
+    /**
+     * Returns `true` if `value` is a {@link SpooledArtifact} instance (including any subclass).
+     *
+     * @remarks
+     * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then
+     * `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g.
+     * {@link @nhtio/adk!SpooledJsonArtifact}) satisfy this guard because `instanceof` walks the prototype
+     * chain. The fallbacks handle the dual-module-copy case where two distinct `SpooledArtifact`
+     * classes coexist in the same realm (e.g. one bundled into a downstream library, one in the
+     * consumer's `node_modules`).
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a {@link SpooledArtifact} instance.
+     */
+    static isSpooledArtifact(value: unknown): value is SpooledArtifact;
+    /**
+     * Returns `true` if `value` is a constructor function whose prototype chain includes
+     * {@link SpooledArtifact} (including `SpooledArtifact` itself).
+     *
+     * @remarks
+     * Used by {@link @nhtio/adk!Tool} to validate the optional `artifactConstructor` field. Performs an
+     * `instanceof`-based check on the prototype chain; falls back to a duck-type test that looks
+     * for the canonical SpooledArtifact instance methods on `value.prototype` for cross-realm
+     * safety (constructors passed from a different module copy or VM context).
+     *
+     * @param value - The value to test.
+     * @returns `true` when `value` is a constructor for `SpooledArtifact` or a subclass.
+     */
+    static isSpooledArtifactConstructor(value: unknown): value is SpooledArtifactConstructor<SpooledArtifact>;
+    /**
+     * Returns the first `n` lines of the artifact.
+     *
+     * @remarks
+     * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the
+     * behaviour of POSIX `head -n`.
+     *
+     * @param n - Number of lines to return. Defaults to 10.
+     * @returns Array of line strings, without trailing newlines.
+     */
+    head(n?: number): Promise<string[]>;
+    /**
+     * Returns the last `n` lines of the artifact.
+     *
+     * @remarks
+     * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the
+     * behaviour of POSIX `tail -n`.
+     *
+     * @param n - Number of lines to return. Defaults to 10.
+     * @returns Array of line strings, without trailing newlines.
+     */
+    tail(n?: number): Promise<string[]>;
+    /**
+     * Returns all lines that match `pattern`.
+     *
+     * @remarks
+     * Behaves like POSIX `grep`: each line is tested against the pattern and included in the result
+     * when it matches. The pattern is applied as a JavaScript `RegExp`; flags (e.g. case-
+     * insensitivity) should be encoded in the expression itself.
+     *
+     * Stateful flags (`g`, `y`) on the supplied `RegExp` would normally cause `pattern.test()` to
+     * advance `lastIndex` across calls, producing skipped matches and order-dependent results. To
+     * keep the per-line semantics stateless, `grep` resets `pattern.lastIndex` to `0` before each
+     * line test. The forged `artifact_grep` tool also rejects `g` and `y` flags up-front at schema
+     * validation time.
+     *
+     * @param pattern - The regular expression to test each line against.
+     * @returns Array of matching line strings, in order.
+     */
+    grep(pattern: RegExp): Promise<string[]>;
+    /**
+     * Returns lines from the artifact, optionally bounded to a range.
+     *
+     * @remarks
+     * Without arguments, returns all lines — equivalent to POSIX `cat`. With `start` and/or `end`,
+     * behaves like `Array.prototype.slice`: `start` defaults to `0`, `end` defaults to the total
+     * line count, and only lines in `[start, end)` are fetched from the backing store. For large
+     * artifacts, prefer a bounded range or {@link SpooledArtifact.head} / {@link SpooledArtifact.tail}.
+     *
+     * @param start - 0-based start line index (inclusive). Defaults to `0`.
+     * @param end - 0-based end line index (exclusive). Defaults to `lineCount()`.
+     * @returns Array of line strings in the requested range.
+     */
+    cat(start?: number, end?: number): Promise<string[]>;
+    /**
+     * Returns the total byte length of the underlying data.
+     *
+     * @returns The byte length as reported by the {@link @nhtio/adk!SpoolReader}.
+     */
+    byteLength(): Promise<number>;
+    /**
+     * Returns the total number of lines in the artifact.
+     *
+     * @returns The line count as reported by the {@link @nhtio/adk!SpoolReader}.
+     */
+    lineCount(): Promise<number>;
+    /**
+     * Estimates the total token count of the artifact under `encoding`.
+     *
+     * @remarks
+     * Reads the full byte-faithful content via {@link SpooledArtifact.asString} (which delegates to
+     * {@link @nhtio/adk!SpoolReader.readAll}) and delegates to {@link @nhtio/adk!Tokenizable.estimateTokens}. The estimate
+     * therefore reflects the actual source bytes — including trailing newlines and non-`\n` line
+     * terminators that the line-based {@link SpooledArtifact.cat} view would otherwise discard or
+     * misrepresent.
+     *
+     * @param encoding - The encoding identifier to use for counting.
+     * @returns The estimated number of tokens.
+     */
+    estimateTokens(encoding: TokenEncoding): Promise<number>;
+    /**
+     * Returns the full artifact body as a single byte-faithful string.
+     *
+     * @remarks
+     * Round-trip faithful to whatever bytes the {@link @nhtio/adk!SpoolReader} was constructed over —
+     * preserves trailing newlines and non-`\n` line terminators that {@link SpooledArtifact.cat}
+     * discards via its line-based view. This is the canonical primitive for "inline the artifact
+     * content directly into a message" use cases.
+     *
+     * `asString()` and the static `forgeTools(ctx)` factory on each subclass are independent
+     * alternatives — a consumer chooses per turn whether to inline the body in a message
+     * (`await tc.results.asString()`) or hand the model query tools
+     * (`SpooledArtifact.forgeTools(ctx)`). Neither calls the other; either works with neither.
+     *
+     * @returns The full content as a single string.
+     */
+    asString(): Promise<string>;
+    /**
+     * Forges a fresh {@link @nhtio/adk!ToolRegistry} of ephemeral {@link @nhtio/adk!ArtifactTool} instances that let the
+     * LLM query artifacts already present in `ctx.turnToolCalls`.
+     *
+     * @remarks
+     * Standard subclass extension pattern — each class owns only its own `toolMethods` and its
+     * own `forgeTools`. The base `SpooledArtifact.forgeTools(ctx)` narrows the `callId` enum to
+     * any `tc.results instanceof SpooledArtifact` (so subclass instances are included — that's
+     * the whole point of inheritance) and dispatches the seven base methods (`head`, `tail`,
+     * `grep`, `cat`, `byteLength`, `lineCount`, `estimateTokens`) on the resolved artifact.
+     * Subclasses override `forgeTools` to call this static first and then register their own
+     * tools on the returned registry — see {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and
+     * {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for the canonical shape. There is no
+     * `requiresSubclass` field, no helper indirection, and no `this`-based class narrowing —
+     * just plain `instanceof ThisClass` at each subclass's own filter site.
+     *
+     * For each descriptor in this class's `toolMethods`, the factory:
+     *
+     * 1. Walks `ctx.turnToolCalls` to find `ToolCall`s whose `results instanceof SpooledArtifact`.
+     *    `ToolCall`s flagged `fromArtifactTool === true` are excluded — they carry a
+     *    {@link @nhtio/adk!Tokenizable}, not a `SpooledArtifact`, and including them would let the model
+     *    `artifact_grep` on a previous `artifact_grep` result (an infinite-recursion hazard with
+     *    no semantic value).
+     * 2. Returns an empty registry if no compatible callIds are found — no point shipping tools
+     *    whose `callId` enum is empty.
+     * 3. Otherwise mints an {@link @nhtio/adk!ArtifactTool} with `ephemeral: true` and `onCollision: 'replace'`
+     *    so multiple `Subclass.forgeTools(ctx)` outputs merge silently. The tool's `inputSchema`
+     *    includes a required `callId` field with `.valid(...compatibleIds)`, plus the descriptor's
+     *    own `argsSchema` fields.
+     *
+     * The handler resolves the artifact via `[...ctx.turnToolCalls].find(t => t.id === callId)`,
+     * dispatches the descriptor's method, and serialises the return value (string → as-is;
+     * string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`;
+     * `descriptor.serialise` overrides the defaults). `grep` is special-cased: the handler
+     * constructs `new RegExp(pattern, flags ?? '')` before invoking the artifact's `grep` method.
+     *
+     * The returned registry must be merged into the consumer's main registry and the main
+     * registry must be bound to `ctx` via {@link @nhtio/adk!ToolRegistry.bindContext}:
+     *
+     * ```ts
+     * const executor: DispatchExecutorFn = async (ctx) => {
+     *   const forged = SpooledArtifact.forgeTools(ctx)
+     *   const merged = ToolRegistry.merge([main, forged])
+     *   main.bindContext(ctx)
+     *   const result = await llm.invoke({ tools: merged.all(), ... })
+     *   ctx.ack() // ← ephemeral cleanup fires here
+     * }
+     * ```
+     *
+     * @warning You **must** call `registry.bindContext(ctx)` on the registry hosting these tools,
+     * or ephemeral cleanup will not run and the `callId` enum in subsequent executor calls will
+     * be stale (excluding new tool calls produced in the meantime).
+     *
+     * @param ctx - The execution context whose `turnToolCalls` snapshot defines the `callId` enum.
+     * @returns A fresh `ToolRegistry`. Empty when `turnToolCalls` contains no compatible artifacts.
+     *
+     * @see {@link @nhtio/adk!ToolRegistry.bindContext}
+     * @see {@link @nhtio/adk!ToolRegistry.merge}
+     * @see {@link @nhtio/adk!DispatchContext.onAck}
+     */
+    static forgeTools(ctx: DispatchContext): ToolRegistry;
+}

package/lib/classes/spooled_json_artifact.d.ts

@@ -0,0 +1,158 @@
+import { ToolRegistry } from "./tool_registry";
+import { SpooledArtifact } from "./spooled_artifact";
+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 running {@link inferFormat}. 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[]>;
+}

package/lib/classes/spooled_markdown_artifact.d.ts

@@ -0,0 +1,202 @@
+import { ToolRegistry } from "./tool_registry";
+import { SpooledArtifact } from "./spooled_artifact";
+import type { Root } from 'mdast';
+import type { SpoolReader } from "../contracts/spool_reader";
+import type { ToolMethodDescriptor } from "./spooled_artifact";
+import type { DispatchContext } from "../contracts/dispatch_context";
+/**
+ * A single heading entry in the document's structural index.
+ *
+ * @remarks
+ * `startLine` is the 0-based line of the heading itself. `endLine` is the 0-based index of the
+ * last line belonging to this section (inclusive) — the line immediately before the next heading
+ * of equal or lesser depth, or the last line of the document.
+ */
+export interface MarkdownHeadingEntry {
+    /** ATX heading depth: 1 (`#`) through 6 (`######`). */
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    /** The heading text with the leading `#` prefix stripped and trimmed. */
+    text: string;
+    /** 0-based line index of the heading line itself. */
+    startLine: number;
+    /** 0-based line index of the last line in this section (inclusive). */
+    endLine: number;
+}
+/**
+ * A single fenced code block entry in the document's structural index.
+ */
+export interface MarkdownCodeEntry {
+    /** The language identifier immediately after the opening fence, or `null` when absent. */
+    lang: string | null;
+    /** 0-based line index of the opening fence line. */
+    startLine: number;
+    /** 0-based line index of the closing fence line. */
+    endLine: number;
+}
+/**
+ * A section of a markdown document as returned by {@link SpooledMarkdownArtifact.md_sections}.
+ *
+ * @remarks
+ * Contains only line-range metadata — no content is fetched until the caller explicitly
+ * requests it via `cat(bodyStartLine, bodyEndLine + 1)`.
+ */
+export interface MarkdownSection {
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    /** The heading text. */
+    heading: string;
+    /** 0-based line of the heading itself. */
+    headingLine: number;
+    /** 0-based line of the first body line (heading line + 1). */
+    bodyStartLine: number;
+    /** 0-based line of the last body line (inclusive). */
+    bodyEndLine: number;
+}
+/**
+ * A {@link @nhtio/adk!SpooledArtifact} specialisation that adds markdown-aware structural queries.
+ *
+ * @remarks
+ * Designed for large markdown documents where loading the full content into memory is
+ * impractical. The structural index (heading positions, code block positions) is built by a
+ * single line-by-line scan of the {@link @nhtio/adk!SpoolReader} without retaining any content. Only the
+ * tiny metadata index and the parsed frontmatter object are cached.
+ *
+ * Content retrieval is always bounded — use `cat(start, end)` or the `startLine`/`endLine`
+ * parameters on inline methods to fetch only the lines you need.
+ *
+ * Inline methods (`md_links`, `md_images`, `md_text`, `md_ast`) accept optional line-range
+ * arguments. Without a range they read the full document — documented trade-off, caller
+ * responsibility to bound the range for large documents.
+ *
+ * The processor always applies `remark-gfm` (tables, task lists, strikethrough, autolinks)
+ * in addition to standard CommonMark and YAML frontmatter.
+ */
+export declare class SpooledMarkdownArtifact extends SpooledArtifact {
+    #private;
+    /**
+     * @param reader - The backing store to read from.
+     */
+    constructor(reader: SpoolReader);
+    /**
+     * Returns `true` if `value` is a {@link SpooledMarkdownArtifact} 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
+     * `SpooledMarkdownArtifact` classes coexist in the same realm.
+     */
+    static isSpooledMarkdownArtifact(value: unknown): value is SpooledMarkdownArtifact;
+    /**
+     * The markdown-specific artifact-query descriptors this class adds on top of the base set.
+     *
+     * @remarks
+     * Lists `artifact_md_frontmatter`, `artifact_md_headings`, `artifact_md_code_blocks`,
+     * `artifact_md_sections`, `artifact_md_links`, `artifact_md_images`, `artifact_md_text`,
+     * `artifact_md_ast`. The base seven descriptors (`artifact_head`, etc.) are NOT included
+     * here — they are forged separately by {@link SpooledMarkdownArtifact.forgeTools}, which
+     * calls `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then
+     * registers its own markdown 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 markdown-specific tools narrowed to
+     * {@link SpooledMarkdownArtifact}.
+     *
+     * @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 markdown-specific descriptor narrowed to markdown
+     * artifacts. Downstream consumers building their own subclasses should follow the same
+     * shape.
+     */
+    static forgeTools(ctx: DispatchContext): ToolRegistry;
+    /**
+     * Returns the parsed YAML frontmatter, or `undefined` when no frontmatter block is present.
+     *
+     * @remarks
+     * Short-circuits after reading the frontmatter block — never reads the document body. Caches
+     * the result so subsequent calls are free. The result is `undefined` (not an empty object)
+     * when no frontmatter is found, distinguishing "no frontmatter" from "empty frontmatter".
+     */
+    md_frontmatter(): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Returns all headings in document order, optionally filtered by depth.
+     *
+     * @remarks
+     * Uses the cached structural index — no content is fetched from the {@link @nhtio/adk!SpoolReader}.
+     *
+     * @param depth - When provided, only headings at this ATX depth (1–6) are returned.
+     */
+    md_headings(depth?: 1 | 2 | 3 | 4 | 5 | 6): Promise<MarkdownHeadingEntry[]>;
+    /**
+     * Returns all fenced code block entries, optionally filtered by language identifier.
+     *
+     * @remarks
+     * Returns line-range metadata only — no content is fetched. Use `cat(entry.startLine + 1,
+     * entry.endLine)` to retrieve the code body (excluding fence lines).
+     *
+     * @param lang - When provided, only blocks with this exact lang identifier are returned.
+     *   Pass an empty string to match blocks with no lang identifier.
+     */
+    md_code_blocks(lang?: string): Promise<MarkdownCodeEntry[]>;
+    /**
+     * Returns document sections derived from the structural index.
+     *
+     * @remarks
+     * Returns only line-range metadata — body content is never fetched. To retrieve the body of a
+     * section, call `cat(section.bodyStartLine, section.bodyEndLine + 1)`.
+     *
+     * When `depth` is provided, only sections introduced by a heading at that depth are returned;
+     * deeper headings become part of the body.
+     *
+     * @param depth - When provided, only sections at this ATX depth (1–6) are returned.
+     */
+    md_sections(depth?: 1 | 2 | 3 | 4 | 5 | 6): Promise<MarkdownSection[]>;
+    /**
+     * Returns the full MDAST Root for the specified line range.
+     *
+     * @remarks
+     * Without a range, reads the full document — for large documents, use
+     * {@link SpooledMarkdownArtifact.md_sections} to locate sections and pass
+     * bounded line ranges here.
+     *
+     * @param startLine - 0-based start line (inclusive). Defaults to `0`.
+     * @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+     */
+    md_ast(startLine?: number, endLine?: number): Promise<Root>;
+    /**
+     * Returns all inline and reference links in the specified line range.
+     *
+     * @param startLine - 0-based start line (inclusive). Defaults to `0`.
+     * @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+     */
+    md_links(startLine?: number, endLine?: number): Promise<Array<{
+        text: string;
+        url: string;
+        title?: string;
+    }>>;
+    /**
+     * Returns all images in the specified line range.
+     *
+     * @param startLine - 0-based start line (inclusive). Defaults to `0`.
+     * @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+     */
+    md_images(startLine?: number, endLine?: number): Promise<Array<{
+        alt: string;
+        url: string;
+        title?: string;
+    }>>;
+    /**
+     * Returns all document text with markup stripped, for the specified line range.
+     *
+     * @remarks
+     * Uses `mdast-util-to-string` to extract plain text from the AST — code, link text, and
+     * alt text are included; markdown syntax is removed.
+     *
+     * @param startLine - 0-based start line (inclusive). Defaults to `0`.
+     * @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+     */
+    md_text(startLine?: number, endLine?: number): Promise<string>;
+}