/**
 * Wrap a `LiteCtx` so every CE verb call is recorded LIVE into a {@link ContextGraph}. Drop it in next
 * to your build, run your loop unchanged, then read `.trace`. Zero changes to litectx internals — the
 * proxy reads each verb's args + return value (the same accountable results recall/assemble already
 * give back). `new LiteCtx({ trace: true })` applies this wrap for you.
 *
 *   proxy.trace          → the {@link ContextGraph} (call `.json()` / `.mermaid()`)
 *   proxy.tap(verb, fn)  → wrap a free-function verb (assemble/compress/summaryWindow) into the same trace
 *
 * The proxy boundary is intentionally untyped (`any`) — like the embedder's optional-dep boundary — so
 * the dynamic forwarding needs no cast or `@ts-ignore`.
 * @param {any} ctx  a LiteCtx instance (or any object whose CE verbs return accountable results)
 * @returns {any} the same object, proxied to record CE verb calls; `.trace` exposes the graph
 * @category graph
 * @when Record every CE verb call live into a context graph you can export as JSON or Mermaid — drop-in tracing for a run.
 * @fails Does not throw; `instanceof LiteCtx` still holds on the returned proxy, and tracing is zero-overhead when unused.
 * @signature observe(ctx: LiteCtx) => LiteCtx  // proxied; read `.trace`
 * @example
 * import { LiteCtx, observe } from 'litectx'
 * const ctx = observe(new LiteCtx({ root: process.cwd() }))
 * await ctx.recall('auth')
 * console.log(ctx.trace.mermaid())
 */
export function observe(ctx: any): any;
/**
 * @typedef {Object} TraceNode
 * @property {string} id                       stable node id (`n0`, `n1`, …)
 * @property {string} verb                     the verb called (`recall`, `assemble`, …)
 * @property {string} [primitive]              its CE primitive — `Write|Select|Compress|Isolate|Substrate`
 * @property {string} [detail]                 one-line summary read off the verb's result
 * @property {string} [accent]                 a colour hint for renderers (not interpreted here)
 * @property {number} col                      pipeline depth (layout hint)
 * @property {number} row                      parallel-branch lane (layout hint)
 * @property {Record<string, unknown>} [stats] the recorded args-in / result-out
 */
/**
 * @typedef {Object} TraceEdge
 * @property {string} from
 * @property {string} to
 * @property {string} [label]
 */
/** The four CE primitives (LangChain's trunk: every technique is Write, Select, Compress, or Isolate). */
export const PRIMITIVES: string[];
/**
 * Canonical verb → primitive map, grounded in `docs/01-product/litectx-ce-prd.md` §skill-map.
 * @type {Record<string, string[]>}
 */
export const VERBS_BY_PRIMITIVE: Record<string, string[]>;
/** Flat verb → primitive lookup, derived from {@link VERBS_BY_PRIMITIVE}. @type {Record<string, string>} */
export const PRIMITIVE: Record<string, string>;
/**
 * The recorder: a node per verb call, an edge per dataflow handoff. Build one directly for a custom
 * trace, or let {@link observe} fill it. `col`/`row` are layout hints (depth / parallel lane) that
 * default to a single horizontal line.
 */
export class ContextGraph {
    /** @type {TraceNode[]} */ nodes: TraceNode[];
    /** @type {TraceEdge[]} */ edges: TraceEdge[];
    /**
     * @param {{verb: string, detail?: string, primitive?: string, accent?: string, stats?: Record<string, unknown>, col?: number, row?: number}} n
     * @returns {string} the new node's id
     */
    node(n: {
        verb: string;
        detail?: string;
        primitive?: string;
        accent?: string;
        stats?: Record<string, unknown>;
        col?: number;
        row?: number;
    }): string;
    /** Record the data handed from one verb to the next. @param {string} from @param {string} to @param {string} [label] @returns {string} */
    edge(from: string, to: string, label?: string): string;
    /** @returns {{ nodes: TraceNode[], edges: TraceEdge[] }} the structured trace */
    json(): {
        nodes: TraceNode[];
        edges: TraceEdge[];
    };
    /** @returns {string} a Mermaid flowchart of the trace — agent-readable, renders anywhere markdown does */
    mermaid(): string;
}
export type TraceNode = {
    /**
     * stable node id (`n0`, `n1`, …)
     */
    id: string;
    /**
     * the verb called (`recall`, `assemble`, …)
     */
    verb: string;
    /**
     * its CE primitive — `Write|Select|Compress|Isolate|Substrate`
     */
    primitive?: string | undefined;
    /**
     * one-line summary read off the verb's result
     */
    detail?: string | undefined;
    /**
     * a colour hint for renderers (not interpreted here)
     */
    accent?: string | undefined;
    /**
     * pipeline depth (layout hint)
     */
    col: number;
    /**
     * parallel-branch lane (layout hint)
     */
    row: number;
    /**
     * the recorded args-in / result-out
     */
    stats?: Record<string, unknown> | undefined;
};
export type TraceEdge = {
    from: string;
    to: string;
    label?: string | undefined;
};