@graphrefly/graphrefly 0.21.0 → 0.23.0

package/dist/graph-CEO2FkLY.d.ts

@@ -0,0 +1,1128 @@
+import { k as GraphReFlyConfig, a6 as VersioningLevel, N as Node, A as Actor, t as Messages, K as NodeSink } from './node-C7PD3sn9.js';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-3QjzotRv.js';
+import { a as StorageTier, S as StorageHandle } from './storage-CHT5WE9m.js';
+
+/**
+ * Graph profiling and inspection utilities.
+ *
+ * Provides per-node memory estimation, connectivity stats, and hotspot
+ * detection. Non-invasive — reads from `describe()` and node internals
+ * without modifying state.
+ *
+ * @module
+ */
+
+/** Per-node profile entry. */
+interface NodeProfile {
+    /** Qualified path within the graph. */
+    path: string;
+    /** Node type (state, derived, producer, effect). */
+    type: string;
+    /** Node status (disconnected, dirty, settled, errored, completed). */
+    status: string;
+    /** Approximate retained bytes for the node's cached value. */
+    valueSizeBytes: number;
+    /** Number of downstream subscribers (sinks). */
+    subscriberCount: number;
+    /** Number of upstream dependencies. */
+    depCount: number;
+    /**
+     * True if this is an effect node with no external subscribers — a classic
+     * leak pattern. See {@link GraphProfileResult.orphans} for the broader
+     * orphan-node detection across `derived` / `producer` / `effect`.
+     */
+    isOrphanEffect: boolean;
+    /**
+     * Orphan category (batch 8 Unit 13 D). `null` when the node is healthy.
+     * - `"orphan-effect"` — effect with zero subscribers (pre-existing class).
+     * - `"idle-derived"` — derived with zero subscribers (wasted compute path
+     *   if it ever activates; may indicate a factory forgot keepalive).
+     * - `"idle-producer"` — producer with zero subscribers (no external
+     *   consumer; may be an over-eager factory or forgotten cleanup).
+     */
+    orphanKind: "orphan-effect" | "idle-derived" | "idle-producer" | null;
+}
+/** Aggregate graph profile. */
+interface GraphProfileResult {
+    /** Total node count. */
+    nodeCount: number;
+    /** Total edge count. */
+    edgeCount: number;
+    /** Subgraph count. */
+    subgraphCount: number;
+    /** All node profiles. */
+    nodes: NodeProfile[];
+    /** Total approximate value memory across all nodes. */
+    totalValueSizeBytes: number;
+    /**
+     * Top-N hotspots by dimension. Each list is sorted descending. See
+     * {@link GraphProfileOptions.topN} for the cap (default 10).
+     */
+    hotspots: {
+        byValueSize: NodeProfile[];
+        bySubscriberCount: NodeProfile[];
+        byDepCount: NodeProfile[];
+    };
+    /**
+     * Every orphan across types — `effect`, `derived`, `producer` with zero
+     * subscribers. See {@link NodeProfile.orphanKind} for category.
+     */
+    orphans: NodeProfile[];
+    /** Effect nodes with no external subscribers (legacy; subset of `orphans`). */
+    orphanEffects: NodeProfile[];
+}
+/** Options for {@link graphProfile}. */
+interface GraphProfileOptions {
+    /** Limit hotspot list (default 10). */
+    topN?: number;
+}
+/**
+ * Profile a graph's memory and connectivity characteristics.
+ *
+ * Uses `describe({ detail: "standard" })` for node metadata and direct
+ * `NodeImpl` access for subscriber counts and cached values.
+ *
+ * @param graph - The graph to profile.
+ * @param opts - Optional configuration.
+ * @returns Aggregate profile with per-node details, hotspots (multi-dim), and orphans.
+ */
+declare function graphProfile(graph: Graph, opts?: GraphProfileOptions): GraphProfileResult;
+
+/**
+ * Reserved segment for meta companion paths: `nodeName::__meta__::metaKey` (GRAPHREFLY-SPEC §3.6).
+ * Forbidden as a local node or mount name.
+ */
+declare const GRAPH_META_SEGMENT = "__meta__";
+/**
+ * Options for {@link Graph}. Named fields documented below; the open index
+ * signature is preserved so callers can stash extension data on the graph
+ * without losing type discipline on the reserved names.
+ *
+ * - `config` — bind this graph to a specific {@link GraphReFlyConfig} for
+ *   tier/metaPassthrough/inspector lookups. Defaults to the singleton
+ *   `defaultConfig` exported from `core/node.ts`.
+ * - `versioning` — convenience for `graph.setVersioning(level)` at
+ *   construction time. Monotonic bulk-apply; see {@link Graph.setVersioning}.
+ * - `factories` — reserved for future per-graph factory registration;
+ *   currently factories flow through `Graph.fromSnapshot(data, {factories})`.
+ */
+interface GraphOptions {
+    config?: GraphReFlyConfig;
+    versioning?: VersioningLevel;
+    factories?: Record<string, GraphNodeFactory>;
+    /**
+     * Capacity of the reasoning-trace ring buffer. Default: `1000`. Set lower
+     * to reduce memory; higher for audit-heavy workloads. Set at construction
+     * time — not mutable afterward (ring buffers can't resize cleanly).
+     */
+    traceCapacity?: number;
+    [key: string]: unknown;
+}
+/** Filter for {@link Graph.describe} — object-style partial match or predicate. */
+type DescribeFilter = Partial<Pick<DescribeNodeOutput, "type" | "status">> | {
+    type?: DescribeNodeOutput["type"];
+    status?: DescribeNodeOutput["status"];
+    /** Keep nodes whose `deps` includes this qualified path. */
+    depsIncludes?: string;
+    /** Snake-case alias for `depsIncludes` (Python parity). */
+    deps_includes?: string;
+    /** Keep nodes whose `meta` contains this key. */
+    metaHas?: string;
+    /** Snake-case alias for `metaHas` (Python parity). */
+    meta_has?: string;
+} | ((node: DescribeNodeOutput) => boolean) | ((nodePath: string, node: DescribeNodeOutput) => boolean);
+/** Options for {@link Graph.signal} and {@link Graph.set} (actor context, internal lifecycle). */
+type GraphActorOptions = {
+    actor?: Actor;
+    /**
+     * When `true`, skips node guards (graph lifecycle TEARDOWN, unmount teardown, etc.).
+     */
+    internal?: boolean;
+};
+/** Options for {@link Graph.describe} (Phase 3.3b progressive disclosure). */
+type GraphDescribeOptions = {
+    actor?: Actor;
+    /**
+     * Node filter. Filters operate on whatever fields the chosen `detail` level
+     * provides. For `metaHas` and `status` filters, use `detail: "standard"` or
+     * higher — at `"minimal"` those fields are absent and the filter silently
+     * excludes all nodes.
+     */
+    filter?: DescribeFilter;
+    /**
+     * Detail level (Phase 3.3b). Default: `"minimal"`.
+     * - `"minimal"` — type + deps only
+     * - `"standard"` — type, status, value, deps, meta, versioning (`v`)
+     * - `"full"` — standard + guard, lastMutation
+     */
+    detail?: DescribeDetail;
+    /**
+     * Explicit field selection (GraphQL-style). Overrides `detail` when provided.
+     * Dotted paths like `"meta.label"` select specific meta keys.
+     */
+    fields?: DescribeField[];
+    /**
+     * Output format.
+     * - `undefined` / omitted — return the full {@link GraphDescribeOutput} object.
+     * - `"spec"` — GraphSpec input format (object; no status/value, deps as edges).
+     * - `"json"` — stable JSON **text** with sorted keys.
+     * - `"pretty"` — human-readable plaintext (optionally colorized; see
+     *   `colorize` / `indent` / `logger` / `includeEdges` / `includeSubgraphs`).
+     * - `"mermaid"` — Mermaid flowchart text.
+     * - `"d2"` — D2 diagram text.
+     */
+    format?: "spec" | "json" | "pretty" | "mermaid" | "d2";
+    /** Pretty/diagram render: direction for diagram formats (default `LR`). */
+    direction?: GraphDiagramDirection;
+    /** Pretty/JSON render: indent (default 2 for JSON, ignored for pretty). */
+    indent?: number;
+    /** Pretty render: optional logger hook; fires with the rendered text before return. */
+    logger?: (text: string) => void;
+    /** Pretty render: include an Edges section (default `true`). */
+    includeEdges?: boolean;
+    /** Pretty render: include a Subgraphs section (default `true`). */
+    includeSubgraphs?: boolean;
+};
+/** JSON snapshot from {@link Graph.describe} (GRAPHREFLY-SPEC §3.6, Appendix B). */
+type GraphDescribeOutput = {
+    name: string;
+    nodes: Record<string, DescribeNodeOutput>;
+    edges: ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+    subgraphs: string[];
+    /**
+     * Re-read the live graph with higher detail (Phase 3.3b).
+     * Returns a new `GraphDescribeOutput`; the original remains a snapshot.
+     * Present on live describe results; absent on deserialized snapshots.
+     */
+    expand?: (detailOrFields: DescribeDetail | DescribeField[]) => GraphDescribeOutput;
+};
+/**
+ * Persisted graph snapshot: {@link GraphDescribeOutput} plus optional format version
+ * ({@link Graph.snapshot}, {@link Graph.restore}, {@link Graph.fromSnapshot}, {@link Graph.toObject},
+ * {@link Graph.toJSONString} — §3.8).
+ */
+type GraphPersistSnapshot = GraphDescribeOutput & {
+    version?: number;
+};
+type GraphFactoryContext = {
+    path: string;
+    type: DescribeNodeOutput["type"];
+    value: unknown;
+    meta: Record<string, unknown>;
+    deps: readonly string[];
+    resolvedDeps: readonly Node[];
+};
+type GraphNodeFactory = (name: string, context: GraphFactoryContext) => Node;
+/**
+ * Checkpoint record shape passed to `StorageTier.save`. Written by
+ * {@link Graph.attachStorage} per-tier according to each tier's
+ * `compactEvery` cadence.
+ *
+ * `mode: "full"` → full snapshot. Baseline anchor emitted on the first save
+ *   and every `compactEvery`-th save thereafter. Sufficient to recover state
+ *   on its own without WAL replay.
+ * `mode: "diff"` → delta payload only, relative to this tier's most recent
+ *   `"full"` baseline. Between compacts. Wire-efficient; requires WAL replay
+ *   over the preceding `"full"` record to reconstruct state.
+ *
+ * Every record includes `seq` (per-tier monotonic counter), `timestamp_ns`
+ * (wall-clock at flush time), and `format_version` (envelope version for
+ * cross-version WAL replay).
+ */
+type GraphCheckpointRecord = {
+    seq: number;
+    timestamp_ns: number;
+    format_version: number;
+} & ({
+    mode: "full";
+    snapshot: GraphPersistSnapshot;
+} | {
+    mode: "diff";
+    diff: GraphWALDiff;
+});
+/** Options for {@link Graph.attachStorage}. */
+type GraphAttachStorageOptions = {
+    /**
+     * Before the first save, attempt to restore from the first tier whose
+     * `load(graph.name)` hits. Runs asynchronously in the background for
+     * async tiers; errors surface via `onError`. Default `false`.
+     */
+    autoRestore?: boolean;
+    /**
+     * Limit the subscription surface (scoped observe). By default
+     * `attachStorage` observes every node in the graph tree; on large graphs
+     * that's thousands of subscriptions just for tier-gating. Pass a path
+     * list (or a single glob) to observe only those nodes.
+     */
+    paths?: readonly string[] | string;
+    /** Pre-save path-level filter — skip records triggered by paths that fail this predicate. */
+    filter?: (name: string, described: DescribeNodeOutput) => boolean;
+    /** Surfaced on tier save errors and autoRestore failures. */
+    onError?: (error: unknown, tier: StorageTier) => void;
+};
+/** Direction options for diagram export helpers. */
+type GraphDiagramDirection = "TD" | "LR" | "BT" | "RL";
+/** Options for {@link Graph.toMermaid} / {@link Graph.toD2}. */
+type GraphDiagramOptions = {
+    /**
+     * Diagram flow direction.
+     * - `TD`: top-down
+     * - `LR`: left-right (default)
+     * - `BT`: bottom-top
+     * - `RL`: right-left
+     */
+    direction?: GraphDiagramDirection;
+};
+/**
+ * Option shapes that trigger structured-mode dispatch in {@link Graph.observe}.
+ * Presence of any of these fields (truthy) → returns {@link ObserveResult};
+ * otherwise `observe()` returns the raw-stream variants.
+ */
+type StructuredTriggers = {
+    structured?: true;
+    timeline?: true;
+    causal?: true;
+    derived?: true;
+    format?: "pretty" | "json";
+    detail?: "minimal" | "full";
+};
+/** {@link Graph.observe} on a single node or meta path — sink receives plain message batches. */
+type GraphObserveOne = {
+    subscribe(sink: NodeSink): () => void;
+    /** Send messages upstream toward the observed node's sources (e.g. PAUSE/RESUME). */
+    up(messages: Messages): void;
+};
+/**
+ * {@link Graph.observe} on the whole graph — sink receives each batch with the qualified source path.
+ * Subscription order follows code-point sort on paths (mounts-first walk, then sorted locals/meta).
+ */
+type GraphObserveAll = {
+    subscribe(sink: (nodePath: string, messages: Messages) => void): () => void;
+    /** Send messages upstream toward a specific observed node's sources (e.g. PAUSE/RESUME). */
+    up(path: string, messages: Messages): void;
+};
+/**
+ * Detail level for `observe()` progressive disclosure (Phase 3.3b).
+ * - `"minimal"` — DATA events only, no timestamps, no causal info.
+ * - `"standard"` — all message types (DATA, DIRTY, RESOLVED, INVALIDATE,
+ *   PAUSE, RESUME, COMPLETE, ERROR, TEARDOWN).
+ * - `"full"` — standard + timeline + causal + derived.
+ */
+type ObserveDetail = "minimal" | "standard" | "full";
+/** Options for structured observation modes on {@link Graph.observe}. */
+type ObserveOptions = {
+    actor?: Actor;
+    /** Return an {@link ObserveResult} accumulator instead of a raw stream. */
+    structured?: boolean;
+    /** Include causal trace info (which dep triggered each recomputation). */
+    causal?: boolean;
+    /** Include timestamps and batch context on each event. */
+    timeline?: boolean;
+    /** Include per-evaluation dep snapshots for compute/derived nodes. */
+    derived?: boolean;
+    /**
+     * Detail level (Phase 3.3b). Individual flags (`causal`, `timeline`, `derived`)
+     * override. `"full"` implies all three plus structured.
+     * `"minimal"` filters to DATA-only events.
+     */
+    detail?: ObserveDetail;
+    /**
+     * When set, auto-enables structured mode and attaches a logger.
+     * `"pretty"` renders colored one-line output; `"json"` emits one JSON object per event.
+     */
+    format?: "pretty" | "json";
+    /** Sink for rendered lines (`console.log` by default). Only used when `format` is set. */
+    logger?: (line: string, event: ObserveEvent) => void;
+    /** Keep only these event types in formatted output. Only used when `format` is set. */
+    includeTypes?: ObserveEvent["type"][];
+    /** Exclude these event types from formatted output. Only used when `format` is set. */
+    excludeTypes?: ObserveEvent["type"][];
+    /** Built-in color preset (`ansi` default) or explicit color tokens. Only used when `format` is set. */
+    theme?: ObserveThemeName | ObserveTheme;
+    /**
+     * Cap the `events` buffer. When set, the result uses a {@link RingBuffer}
+     * under the hood: oldest events are dropped on overflow. Unbounded when
+     * omitted (default).
+     */
+    maxEvents?: number;
+};
+/** Accumulated observation result (structured mode). */
+type ObserveResult<T = unknown> = AsyncIterable<ObserveEvent> & {
+    /** Latest DATA value by observed path. */
+    readonly values: Record<string, T>;
+    /** Number of DIRTY messages received. */
+    readonly dirtyCount: number;
+    /** Number of RESOLVED messages received. */
+    readonly resolvedCount: number;
+    /** Number of INVALIDATE messages received (tier 1 cache-clear). */
+    readonly invalidateCount: number;
+    /** Number of PAUSE messages received (tier 2 backpressure). */
+    readonly pauseCount: number;
+    /** Number of RESUME messages received (tier 2 backpressure). */
+    readonly resumeCount: number;
+    /** Number of TEARDOWN messages received (tier 5 permanent cleanup). */
+    readonly teardownCount: number;
+    /**
+     * All events in order — ring-buffered when `options.maxEvents` is set,
+     * unbounded otherwise. Always materialized as an `ObserveEvent[]`
+     * snapshot on read.
+     */
+    readonly events: ObserveEvent[];
+    /** True if any observed node sent COMPLETE without prior ERROR on that node. */
+    readonly anyCompletedCleanly: boolean;
+    /** True if any observed node sent ERROR. */
+    readonly anyErrored: boolean;
+    /** True if at least one COMPLETE received and no ERROR from any observed node. */
+    readonly completedWithoutErrors: boolean;
+    /**
+     * Attach a live listener that fires for each event as it arrives.
+     * Returns an unsubscribe fn. Independent of the `events` buffer.
+     */
+    onEvent(listener: (event: ObserveEvent) => void): () => void;
+    /** Stop observing. */
+    dispose(): void;
+    /**
+     * Resubscribe with higher detail (Phase 3.3b).
+     * Disposes current observation, returns new `ObserveResult` with merged options.
+     */
+    expand(extra: Partial<Pick<ObserveOptions, "causal" | "timeline" | "derived">> | ObserveDetail): ObserveResult<T>;
+};
+/** Fields common to every {@link ObserveEvent} variant. */
+interface ObserveEventBase {
+    path?: string;
+    /** Optional `timeline` context — wall-clock when `options.timeline === true`. */
+    timestamp_ns?: number;
+    in_batch?: boolean;
+    /** Monotonically increasing counter per subscribe-callback invocation. All events in one delivery share the same id. */
+    batch_id?: number;
+}
+/** Optional `causal` context present on `data`/`resolved`/`derived` events. */
+interface ObserveCausalContext {
+    trigger_dep_index?: number;
+    trigger_dep_name?: string;
+    /**
+     * V0 version of the triggering dep at observation time (§6.0b).
+     * This is the dep's post-emission version (after its own `advanceVersion`),
+     * not the pre-emission version that caused this node's recomputation.
+     */
+    trigger_version?: {
+        id: string;
+        version: number;
+    };
+    /**
+     * One scalar per dep: the last value that arrived in the current wave,
+     * or the pre-wave cached value for deps that didn't fire. Convenient
+     * for single-value-wave tooling (the common case).
+     */
+    dep_values?: unknown[];
+    /**
+     * Full per-dep batches for the wave that fired the fn — `dep_batches[i]`
+     * is the array of values dep `i` delivered this wave (`undefined` for
+     * deps that didn't fire). Use this to distinguish a single-value wave
+     * from a multi-value wave; `dep_values` compresses each batch to its
+     * last element and hides that difference.
+     */
+    dep_batches?: ReadonlyArray<ReadonlyArray<unknown> | undefined>;
+}
+/** A single event in the structured observation log (discriminated on `type`). */
+type ObserveEvent = (ObserveEventBase & ObserveCausalContext & {
+    type: "data";
+    data: unknown;
+}) | (ObserveEventBase & {
+    type: "dirty";
+}) | (ObserveEventBase & ObserveCausalContext & {
+    type: "resolved";
+}) | (ObserveEventBase & {
+    type: "invalidate";
+}) | (ObserveEventBase & {
+    type: "pause";
+    lockId: unknown;
+}) | (ObserveEventBase & {
+    type: "resume";
+    lockId: unknown;
+}) | (ObserveEventBase & {
+    type: "complete";
+}) | (ObserveEventBase & {
+    type: "error";
+    data: unknown;
+}) | (ObserveEventBase & {
+    type: "teardown";
+}) | (ObserveEventBase & ObserveCausalContext & {
+    type: "derived";
+    dep_values: unknown[];
+});
+/** Built-in color preset names for observe `format` rendering. */
+type ObserveThemeName = "none" | "ansi";
+/** ANSI/style overrides for observe `format` event rendering. */
+type ObserveTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", string>>;
+/**
+ * Named container for nodes and explicit edges (GRAPHREFLY-SPEC §3.1–§3.7).
+ *
+ * Qualified paths use `::` as the segment separator (for example `parent::child::node`).
+ *
+ * Edges are pure wires: `connect` only validates wiring — the target must already list the source in
+ * its dependency array; no transforms run on the edge.
+ *
+ * @example
+ * ```ts
+ * import { Graph, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const g = new Graph("app");
+ * g.add("counter", state(0));
+ * ```
+ *
+ * @category graph
+ */
+declare class Graph {
+    readonly name: string;
+    readonly opts: Readonly<GraphOptions>;
+    /** Protocol config bound to this graph (defaults to `defaultConfig`). */
+    readonly config: GraphReFlyConfig;
+    /** @internal — exposed for {@link teardownMountedGraph} and cross-graph helpers. */
+    readonly _nodes: Map<string, Node<unknown>>;
+    /**
+     * @internal Reverse lookup for duplicate-instance detection in
+     * {@link Graph.add} — O(1) replacement for an O(n) scan of `_nodes`.
+     * Weak so nodes can be GC'd after `remove()` even if a caller keeps the
+     * map alive via some unusual pattern.
+     */
+    private readonly _nodeToName;
+    /** @internal — exposed for {@link teardownMountedGraph}. */
+    readonly _mounts: Map<string, Graph>;
+    /**
+     * @internal Parent graph if this instance is mounted. `undefined` when
+     * this is the root or when the graph has been unmounted. Used for
+     * reparenting rejection + O(depth) ancestor walks.
+     */
+    _parent: Graph | undefined;
+    private readonly _storageDisposers;
+    private readonly _disposers;
+    /**
+     * @param name - Non-empty graph id (must not contain `::` and must not
+     *   equal the reserved meta segment `__meta__`).
+     * @param opts - See {@link GraphOptions}. Stored frozen on the instance.
+     */
+    constructor(name: string, opts?: GraphOptions);
+    /**
+     * Walk ancestors up through `_parent`. Returns the chain starting at this
+     * instance, ending at the root (a graph with no parent). O(depth).
+     *
+     * @param includeSelf - Include `this` in the chain (default `true`).
+     */
+    ancestors(includeSelf?: boolean): Graph[];
+    /**
+     * Registers a node under a local name. Fails if the name is already used,
+     * reserved by a mount, the same node instance is already registered, or
+     * the node is torn down.
+     *
+     * Returns the registered node so callers can chain:
+     * `const counter = g.add("counter", state(0))`.
+     *
+     * @param name - Local key (no `::`).
+     * @param node - Node instance to own.
+     */
+    add<T extends Node>(name: string, node: T): T;
+    /**
+     * Bulk-apply a minimum versioning level to every currently-registered node
+     * in this graph (roadmap §6.0). `_applyVersioning` is monotonic — nodes
+     * already at a higher level are untouched. The method refuses to run
+     * mid-wave; invoke at setup time before any external subscribers attach.
+     *
+     * **Not** a default-for-future-adds mechanism — that's what
+     * `config.defaultVersioning` is for. Nodes added after this call do NOT
+     * automatically inherit `level`; register new nodes with their own
+     * `opts.versioning` or set `config.defaultVersioning` before construction.
+     *
+     * **Scope:** local only. Does not propagate to mounted subgraphs.
+     *
+     * @param level - `0` for V0, `1` for V1, or `undefined` to no-op.
+     */
+    setVersioning(level: VersioningLevel | undefined): void;
+    /**
+     * Unregisters a node or unmounts a subgraph and sends `[[TEARDOWN]]` to the
+     * removed node or recursively through the mounted subtree (§3.2).
+     *
+     * @param name - Local mount or node name.
+     * @returns Audit record of what was removed: `{kind, nodes, mounts}`.
+     *   `kind: "node"` → `nodes: [name]`, `mounts: []`. `kind: "mount"` →
+     *   `nodes` lists every primary node torn down across the subtree (sorted
+     *   qualified paths relative to the unmounted subgraph) and `mounts` lists
+     *   the mounted subgraphs in depth-first order including `name` itself.
+     */
+    remove(name: string): GraphRemoveAudit;
+    /**
+     * Bulk remove — invokes {@link Graph.remove} for every local name matching
+     * `filter`. Audit records merge into a single result. Mounted subgraphs
+     * are included via `filter` receiving the mount name; internal subtree
+     * entries are not walked directly (use describe + scan for tree-level
+     * queries).
+     *
+     * @param filter - Predicate or glob. Glob strings support `*` within a
+     *   segment and `**` across segments (same grammar as `restore({only})`).
+     * @returns Combined audit of all nodes + mounts removed.
+     */
+    removeAll(filter: ((name: string) => boolean) | string): GraphRemoveAudit;
+    /**
+     * Iterable over locally-registered `[localName, Node]` pairs (sorted).
+     * Does not recurse into mounts.
+     */
+    [Symbol.iterator](): IterableIterator<[string, Node]>;
+    /**
+     * Returns a node by local name or `::` qualified path.
+     * Local names are looked up directly; paths with `::` delegate to {@link resolve}.
+     *
+     * @param name - Local name or qualified path.
+     */
+    node(name: string): Node;
+    /**
+     * Reads `graph.node(name).get()` — accepts `::` qualified paths (§3.2).
+     *
+     * @param name - Local name or qualified path.
+     * @returns Cached value or `undefined`.
+     */
+    get(name: string): unknown;
+    /**
+     * Shorthand for `graph.node(name).down([[DATA, value]], { actor })` — accepts `::` qualified paths (§3.2).
+     *
+     * @param name - Local name or qualified path.
+     * @param value - Next `DATA` payload.
+     * @param options - Optional `actor` and `internal` guard bypass.
+     */
+    set(name: string, value: unknown, options?: GraphActorOptions): void;
+    /**
+     * Atomic multi-node DATA write. Wraps every {@link Graph.set} call in a
+     * single `batch(...)` so downstream dependents see one coalesced wave
+     * instead of N cascading ones.
+     *
+     * @param entries - `{name → value}` map or `[name, value]` pairs.
+     * @param options - Passed to each underlying `set` call (same `actor` + `internal` semantics).
+     */
+    setAll(entries: Record<string, unknown> | Iterable<readonly [string, unknown]>, options?: GraphActorOptions): void;
+    /**
+     * Emit a single `[[INVALIDATE]]` (tier 1) on a node. Thin wrapper over
+     * `node.down([[INVALIDATE]], …)` matching the {@link Graph.set} ergonomics.
+     */
+    invalidate(name: string, options?: GraphActorOptions): void;
+    /**
+     * Emit a single `[[ERROR, err]]` (tier 4) on a node.
+     */
+    error(name: string, err: unknown, options?: GraphActorOptions): void;
+    /**
+     * Emit a single `[[COMPLETE]]` (tier 4) on a node, declaring the stream
+     * cleanly finished. Distinct from {@link Graph.remove} (which emits
+     * TEARDOWN and unregisters the node).
+     */
+    complete(name: string, options?: GraphActorOptions): void;
+    /**
+     * Returns the full edge list for this graph tree, derived on demand from
+     * each registered node's `_deps` (no stored registry). Local-only
+     * (non-recursive) by default to match the historical `edges()` surface;
+     * pass `{recursive: true}` to include mounted subgraphs with qualified
+     * paths relative to this graph.
+     *
+     * Use {@link Graph.describe} for full-tree snapshots with edges already
+     * qualified and paired with node metadata.
+     */
+    edges(opts?: {
+        recursive?: boolean;
+    }): ReadonlyArray<[string, string]>;
+    /**
+     * Embed a child graph at a local mount name (§3.4). Child nodes are reachable via
+     * {@link Graph.resolve} using `::` delimited paths (§3.5). Lifecycle
+     * {@link Graph.signal} visits mounted subgraphs recursively.
+     *
+     * Rejects: same name as existing node or mount, self-mount, mount cycles,
+     * and the same child graph instance mounted twice on one parent.
+     *
+     * @param name - Local mount point.
+     * @param child - Nested `Graph` instance.
+     * @returns The mounted `child`, for chaining.
+     */
+    mount<G extends Graph>(name: string, child: G): G;
+    /**
+     * Look up a node by qualified path (§3.5). Segments are separated by `::`.
+     *
+     * If the first segment equals this graph's {@link Graph.name}, it is stripped
+     * (so `root.resolve("app::a")` works when `root.name === "app"`). The strip
+     * is applied **recursively** when descending into mounted children, so
+     * `child.resolve("child::x")` also works when `child.name === "child"`.
+     *
+     * @param path - Qualified `::` path or local name.
+     * @returns The resolved `Node`.
+     */
+    resolve(path: string): Node;
+    /**
+     * Non-throwing {@link Graph.resolve}. Returns `undefined` instead of
+     * throwing when the path does not resolve to a node.
+     */
+    tryResolve(path: string): Node | undefined;
+    private _resolveFromSegments;
+    /**
+     * Resolve `::__meta__::key` segments from a registered primary node (possibly chained).
+     */
+    private _resolveMetaChainFromNode;
+    /**
+     * Deliver a message batch to every registered node in this graph and, recursively,
+     * in mounted child graphs (§3.7). Recurses into mounts first, then delivers to
+     * local nodes (sorted by name). Each {@link Node} receives at most one delivery
+     * per call (deduped by reference).
+     *
+     * **Primary-vs-meta filter asymmetry (intentional):** primary nodes receive the
+     * unfiltered `messages` batch — that's the canonical data-plane flow. Companion
+     * `meta` nodes receive a filtered subset keyed by the per-type `metaPassthrough`
+     * flag on {@link GraphReFlyConfig}. Built-in defaults: PAUSE / RESUME / DATA /
+     * RESOLVED pass through to meta; INVALIDATE / COMPLETE / ERROR / TEARDOWN do
+     * not.
+     *
+     * **Where lifecycle terminals reach meta:**
+     * - **TEARDOWN** — primary's `_emit` cascades to meta children directly (see
+     *   `core/node.ts` "Meta TEARDOWN fan-out" block) so meta is torn down with
+     *   its primary regardless of the signal-level filter.
+     * - **COMPLETE / ERROR / INVALIDATE** — scoped to primaries on the broadcast
+     *   path. Meta companions are an attribution side-channel, not a lifecycle
+     *   participant; address meta directly via `meta.down(...)` if you need to
+     *   forward these. Audit confirmed 2026-04-17: no current meta consumer
+     *   relies on broadcast COMPLETE/ERROR/INVALIDATE delivery.
+     *
+     * @param messages - Batch to deliver to every registered node (and mounts, recursively).
+     * @param options - Optional `actor` / `internal` for transport.
+     */
+    signal(messages: Messages, options?: GraphActorOptions): void;
+    private _signalDeliver;
+    private _signalMetaSubtree;
+    /**
+     * Static structure snapshot: qualified node keys, edges, mount names (GRAPHREFLY-SPEC §3.6, Appendix B).
+     *
+     * `format` controls the return type:
+     * - omitted or `"spec"` → {@link GraphDescribeOutput} object.
+     * - `"json"` / `"pretty"` / `"mermaid"` / `"d2"` → rendered string.
+     *
+     * @param options - Optional `actor` for guard-scoped visibility, `filter` for
+     *   selective output, or `format` to render.
+     *
+     * @example
+     * ```ts
+     * graph.describe()                                         // full snapshot object
+     * graph.describe({ filter: { status: "errored" } })        // filtered object
+     * graph.describe({ format: "pretty" })                     // human-readable text
+     * graph.describe({ format: "mermaid" })                    // Mermaid flowchart
+     * graph.describe({ format: "d2", direction: "TD" })        // D2 top-down
+     * ```
+     */
+    describe(options: GraphDescribeOptions & {
+        format: "json" | "pretty" | "mermaid" | "d2";
+    }): string;
+    describe(options?: GraphDescribeOptions): GraphDescribeOutput;
+    private _collectSubgraphs;
+    /**
+     * Snapshot-based resource profile: per-node stats, orphan effect detection,
+     * memory hotspots. Zero runtime overhead — walks nodes on demand.
+     *
+     * @param opts - Optional `topN` for hotspot limit (default 10).
+     * @returns Aggregate profile with per-node details, hotspots, and orphan effects.
+     */
+    resourceProfile(opts?: GraphProfileOptions): GraphProfileResult;
+    /**
+     * Reachability query rooted at `from`. Instance convenience — wraps
+     * `reachable(this.describe(), from, direction, opts)`. See
+     * {@link reachable} for semantics.
+     */
+    reachable(from: string, direction: ReachableDirection, opts: ReachableOptions & {
+        withDetail: true;
+    }): ReachableResult;
+    reachable(from: string, direction: ReachableDirection, opts?: ReachableOptions): string[];
+    /**
+     * @internal Collect all qualified paths in this graph tree matching a
+     * glob pattern. Used by scoped autoCheckpoint subscription.
+     */
+    private _pathsMatching;
+    private _collectObserveTargets;
+    private _appendMetaObserveTargets;
+    /**
+     * Live message stream from one node (or meta path), or from the whole graph (§3.6).
+     *
+     * Two modes dispatched on first argument:
+     * - `observe(path, options?)` — one node. Returns {@link GraphObserveOne}
+     *   (raw stream), or {@link ObserveResult} when `options` requests structured
+     *   accumulation (`structured`, `timeline`, `causal`, `derived`, `format`,
+     *   `detail: "minimal"|"full"`).
+     * - `observe(options?)` — all nodes. Returns {@link GraphObserveAll} (raw),
+     *   or {@link ObserveResult} under the same structured trigger conditions.
+     *
+     * Structured mode subscribes in sorted path order (code-point). Inspector
+     * extras (`causal`/`derived`) require `graph.config.inspectorEnabled`;
+     * when disabled, those fields silently drop and the rest still works.
+     *
+     * `ObserveResult` is also an `AsyncIterable<ObserveEvent>` — use
+     * `for await (const ev of result)` for pull-based consumption.
+     */
+    observe(path: string, options?: ObserveOptions & StructuredTriggers): ObserveResult;
+    observe(path: string, options?: ObserveOptions): GraphObserveOne;
+    observe(options: ObserveOptions & StructuredTriggers): ObserveResult;
+    observe(options?: ObserveOptions): GraphObserveAll;
+    /** Dispatch helper — builds a unified observer + its expand closure. */
+    private _buildStructuredObserver;
+    /**
+     * Unified observer builder — replaces the four ex-creators
+     * (`_createObserveResult` / `...ForAll` / `_createFallback…`). Accepts a
+     * list of `[path, node]` targets (single-element for one-node observe,
+     * N-element for all-nodes). Inspector hooks attach per-target when
+     * `causal`/`derived` requested AND `config.inspectorEnabled`; otherwise
+     * those fields gracefully drop.
+     *
+     * Events flow through a `recordEvent()` helper so the format logger,
+     * ring-buffer, and async-iterable hooks all share one push path.
+     */
+    private _createObserveResult;
+    /**
+     * Attach format-rendering logger to an ObserveResult by subscribing to its
+     * event stream (no monkey-patching). Renders each event per `format` and
+     * `theme`, filtered by `includeTypes` / `excludeTypes`.
+     */
+    private _attachFormatLogger;
+    /**
+     * Register a cleanup function to be called on {@link Graph.destroy}.
+     *
+     * Factories use this to attach teardown logic for internal nodes, keepalive
+     * subscriptions, or other resources that are not registered on the graph and
+     * would otherwise leak on repeated create/destroy cycles.
+     *
+     * Returns a removal function — call it to unregister the disposer early.
+     */
+    addDisposer(fn: () => void): () => void;
+    /**
+     * Drains disposers (registered via {@link addDisposer}), then sends `[[TEARDOWN]]` to all
+     * nodes and clears registries on this graph and every mounted subgraph (§3.7).
+     * The instance is left empty and may be reused with {@link Graph.add}.
+     */
+    destroy(): void;
+    /** Clear structure after parent already signaled TEARDOWN through this subtree. */
+    private _destroyClearOnly;
+    /**
+     * Serializes structure and current values to JSON-shaped data (§3.8). Same
+     * information as {@link Graph.describe} plus a `version` field for format
+     * evolution.
+     *
+     * The overload path supports three outputs:
+     * - no arg → `GraphPersistSnapshot` (plain JS object).
+     * - `{format: "json-string"}` → deterministic JSON `string`
+     *   (key-sorted; safe for hashing or file write).
+     * - `{format: "bytes", codec: name}` → `Uint8Array` wrapped in the v1
+     *   envelope from {@link encodeEnvelope}. The codec must be registered
+     *   on this graph's {@link GraphReFlyConfig} via `config.registerCodec`.
+     *   Paired with {@link Graph.decode} for auto-dispatch on the read side.
+     */
+    snapshot(): GraphPersistSnapshot;
+    snapshot(opts: {
+        format: "json-string";
+    }): string;
+    snapshot(opts: {
+        format: "bytes";
+        codec: string;
+    }): Uint8Array;
+    /**
+     * Auto-dispatch a byte buffer produced by {@link Graph.snapshot} with
+     * `{format: "bytes", codec: name}`. Reads the v1 envelope, resolves the
+     * named codec on `config` (defaults to `defaultConfig`), and returns the
+     * decoded snapshot. Combine with {@link Graph.fromSnapshot} to rehydrate
+     * a full graph topology from bytes.
+     *
+     * @throws If the envelope is malformed or the named codec isn't
+     *   registered on the target config.
+     */
+    static decode(bytes: Uint8Array, opts?: {
+        config?: GraphReFlyConfig;
+    }): GraphPersistSnapshot;
+    /**
+     * Apply persisted values onto an existing graph whose topology matches the snapshot
+     * (§3.8). Only {@link DescribeNodeOutput.type} `state` entries with a `value` field
+     * are written by default; `derived` / `operator` / `effect` are always skipped so
+     * deps drive recomputation. `producer` entries are skipped unless `includeProducers`
+     * is set (producers recompute on activation, so restoring is usually a no-op
+     * overwritten on the next wave — opt in for audit / forensic round-trip use cases).
+     * Unknown paths are ignored.
+     *
+     * @param data - Snapshot envelope with matching `name` and node slices.
+     * @throws If `data.name` does not equal {@link Graph.name}.
+     */
+    restore(data: GraphPersistSnapshot, options?: {
+        only?: string | readonly string[];
+        /**
+         * Fires per failing write. Default behavior (omitted) is silent —
+         * missing paths and guard denials are swallowed to match the
+         * historical semantics. Provide a callback to surface failures
+         * without aborting the remaining restores.
+         */
+        onError?: (path: string, err: unknown) => void;
+        /**
+         * Restore `producer` node values alongside `state`. Default `false`:
+         * producers are reactive sources whose value recomputes on
+         * activation, so restoring from a snapshot is usually a no-op
+         * overwritten on the next wave. Audit / forensic round-trip use
+         * cases that need the stored value to survive restoration can
+         * opt in. Does not change `derived` / `effect` handling — those
+         * are always skipped.
+         */
+        includeProducers?: boolean;
+    }): void;
+    /**
+     * Creates a graph named from the snapshot, optionally runs `build` to register nodes
+     * and mounts, then {@link Graph.restore} values (§3.8).
+     *
+     * @param data - Snapshot envelope (`version` checked).
+     * @param opts - Either a legacy `build(g)` callback, or an options object:
+     *   - `build?` — topology constructor; skips auto-hydration when present.
+     *   - `factories?` — map from glob pattern to {@link GraphNodeFactory},
+     *     used by auto-hydration to reconstruct non-state nodes. Per-call (no
+     *     process-global registry). First matching pattern wins.
+     * @returns Hydrated `Graph` instance.
+     */
+    static fromSnapshot(data: GraphPersistSnapshot, opts?: ((g: Graph) => void) | {
+        build?: (g: Graph) => void;
+        factories?: Record<string, GraphNodeFactory>;
+    }): Graph;
+    /**
+     * ECMAScript `JSON.stringify` hook — returns the same object as
+     * {@link Graph.snapshot}. Makes `JSON.stringify(graph)` "just work"
+     * without double-encoding.
+     */
+    toJSON(): GraphPersistSnapshot;
+    /**
+     * Unified persistence surface (§3.8). Cascades snapshot records through
+     * one or more {@link StorageTier}s, each with its own `debounceMs` /
+     * `compactEvery` cadence and independent diff baseline.
+     *
+     * Subscription gates on {@link messageTier} ≥ 3 (DATA/RESOLVED/terminal),
+     * never on tier-0/1/2 control waves (START/DIRTY/INVALIDATE/PAUSE/RESUME)
+     * or tier-5 TEARDOWN (graceful shutdown is the caller's responsibility).
+     *
+     * Per-tier cadence lets the hot tier stay sync while cold tiers absorb
+     * async writes without blocking the hot path. Each tier holds its own
+     * `{lastSnapshot, lastVersionFingerprint}` so cold-tier diff baselines
+     * aren't polluted by hot-tier flushes. Tiers with `debounceMs === 0`
+     * share a single snapshot computation per observe event; debounced tiers
+     * compute their own snapshot when their timer fires.
+     */
+    attachStorage(tiers: readonly StorageTier[], options?: GraphAttachStorageOptions): StorageHandle;
+    /**
+     * Try tiers in order (hottest first); apply the first record that hits
+     * via {@link Graph.restore}. Returns `true` if any tier produced a
+     * restorable snapshot, `false` if all missed.
+     *
+     * Resilience: a tier that returns data which cannot be restored (load
+     * throws, shape unrecognized, or `restore()` itself throws) does not abort
+     * the cascade — the error is routed through `onError` (if supplied) and
+     * the next colder tier is tried. This mirrors how a multi-tier cache
+     * falls through on a corrupt hot entry.
+     *
+     * Note: `restore()` mutates state incrementally. If a restore throws
+     * partway through, the graph may hold a mixed state (some slices from
+     * the bad tier, some pre-existing). A subsequent successful tier's
+     * `restore()` overwrites the overlapping slices.
+     *
+     * Internal helper shared by {@link Graph.attachStorage}'s `autoRestore`
+     * option and the static {@link Graph.fromStorage} factory.
+     */
+    private _cascadeRestore;
+    /**
+     * Construct a fresh {@link Graph} pre-hydrated from the first tier that
+     * hits. Delegates topology reconstruction to {@link Graph.fromSnapshot}
+     * on `"full"` records and direct {@link Graph.restore} on bare snapshots.
+     *
+     * Always asynchronous — awaits `tier.load()` for async tier support even
+     * when all tiers are sync. Callers that know they only pass sync tiers
+     * can safely `await` immediately.
+     *
+     * @throws If no tier holds a restorable record matching `name` *and* no
+     *   `factories` override is provided for dynamic nodes.
+     */
+    static fromStorage(name: string, tiers: readonly StorageTier[], opts?: GraphOptions & {
+        factories?: Record<string, GraphNodeFactory>;
+        /**
+         * Called when a tier throws during `load()` or when
+         * {@link Graph.fromSnapshot} rejects a tier's record. The cascade
+         * falls through to the next colder tier regardless.
+         */
+        onError?: (err: unknown, tier: StorageTier) => void;
+    }): Promise<Graph>;
+    private _annotations;
+    private readonly _traceRing;
+    /**
+     * Unified reasoning trace: write annotations or read the ring buffer.
+     *
+     * Write: `graph.trace("path", "reason")` — attaches a reasoning annotation
+     * to a node, capturing *why* an AI agent set a value. Unknown paths are
+     * silently dropped (matching `observe` resilience). No-op when
+     * `config.inspectorEnabled` is `false`.
+     *
+     * Read: `graph.trace()` — returns a chronological log of all annotations.
+     * Returns `[]` when `config.inspectorEnabled` is `false`.
+     */
+    trace(path: string, reason: string, opts?: {
+        actor?: Actor;
+    }): void;
+    trace(): readonly TraceEntry[];
+    /**
+     * Latest reason annotation attached to `path` via {@link Graph.trace},
+     * or `undefined` if none. `describe()` surfaces this via the `reason`
+     * field on each node entry (when present).
+     */
+    annotation(path: string): string | undefined;
+    /**
+     * Clear all reasoning-trace state (both the per-path annotations map and
+     * the ring buffer). Useful for long-running processes that want periodic
+     * resets, or tests that need a clean slate.
+     */
+    clearTrace(): void;
+    /**
+     * Remove trace entries matching `predicate`. Returns the number of
+     * entries removed. Does not touch the per-path annotations map — call
+     * {@link Graph.clearTrace} for a full reset.
+     */
+    pruneTrace(predicate: (entry: TraceEntry) => boolean): number;
+    /**
+     * Computes structural + value diff between two {@link Graph.describe} snapshots.
+     *
+     * @param a - Earlier describe output.
+     * @param b - Later describe output.
+     * @returns Added/removed nodes, changed fields, and edge deltas.
+     */
+    static diff(a: GraphDescribeOutput, b: GraphDescribeOutput): GraphDiffResult;
+}
+/** Entry in the reasoning trace ring buffer (roadmap 3.3). */
+type TraceEntry = {
+    path: string;
+    reason: string;
+    timestamp_ns: number;
+    /**
+     * Actor that produced the annotation (optional). Enables multi-agent
+     * attribution: distinguish "LLM set this rootCause" from "human approved
+     * this intervention" in the trace log.
+     */
+    actor?: Actor;
+};
+/** Result of {@link Graph.diff}. */
+type GraphDiffResult = {
+    nodesAdded: string[];
+    nodesRemoved: string[];
+    nodesChanged: GraphDiffChange[];
+    /**
+     * V0 version bumps (same `v.id`, different `v.version`). Surfaced even
+     * when values are identical — the bump itself is audit-meaningful.
+     */
+    versionChanges: GraphVersionChange[];
+    edgesAdded: Array<{
+        from: string;
+        to: string;
+    }>;
+    edgesRemoved: Array<{
+        from: string;
+        to: string;
+    }>;
+    subgraphsAdded: string[];
+    subgraphsRemoved: string[];
+};
+/**
+ * WAL-oriented diff — extends {@link GraphDiffResult} with the full node
+ * slice for each added path so {@link replayWAL} can reconstruct nodes added
+ * between full anchors (topology mutations inside a `compactEvery` window).
+ *
+ * `Graph.diff()` returns the audit shape (no payload); `attachStorage` writes
+ * this WAL shape. The two shapes stay structurally compatible — `GraphWALDiff`
+ * is a superset.
+ */
+type GraphWALDiff = GraphDiffResult & {
+    /**
+     * Full node slices for every path in `nodesAdded`, keyed by path. Applied
+     * verbatim to `snapshot.nodes[path]` during replay.
+     */
+    nodesAddedFull: Record<string, DescribeNodeOutput>;
+};
+/**
+ * Build a WAL-ready diff between two snapshots: the structural diff from
+ * {@link Graph.diff} plus the full node slice for each added path (pulled
+ * from `b.nodes`). Callers that only need the audit shape should use
+ * `Graph.diff` directly.
+ */
+declare function diffForWAL(a: GraphDescribeOutput, b: GraphDescribeOutput): GraphWALDiff;
+/** A single field change within a diff. */
+type GraphDiffChange = {
+    path: string;
+    field: string;
+    from: unknown;
+    to: unknown;
+};
+/** A single V0 version bump within a diff. */
+type GraphVersionChange = {
+    path: string;
+    id: string;
+    from: number;
+    to: number;
+};
+/** Audit record returned by {@link Graph.remove}. */
+type GraphRemoveAudit = {
+    /** Whether the removed entry was a local node or a mount. */
+    kind: "node" | "mount";
+    /**
+     * Primary nodes torn down by this `remove()`. For `kind: "node"` contains
+     * just the removed name; for `kind: "mount"` lists every primary node in
+     * the unmounted subtree (qualified paths relative to the mount point,
+     * sorted).
+     */
+    nodes: string[];
+    /**
+     * Mounted subgraphs that were unmounted. For `kind: "node"` this is empty;
+     * for `kind: "mount"` starts with the top-level mount name and lists its
+     * descendants in depth-first order.
+     */
+    mounts: string[];
+};
+/** Direction for {@link reachable} graph traversal. */
+type ReachableDirection = "upstream" | "downstream";
+/** Options for {@link reachable}. */
+type ReachableOptions = {
+    /** Maximum hop depth from `from` (0 returns `[]`). Omit for unbounded traversal. */
+    maxDepth?: number;
+    /**
+     * Traverse both directions in one pass (union of upstream + downstream).
+     * Ignores the `direction` arg when set.
+     */
+    both?: boolean;
+    /**
+     * Return the richer {@link ReachableResult} shape (paths + per-path
+     * hop depth + truncation flag) instead of the flat sorted string array.
+     */
+    withDetail?: boolean;
+};
+/** Rich reachable result (opt-in via `{withDetail: true}`). */
+type ReachableResult = {
+    /** Reachable paths, sorted lexicographically. */
+    paths: string[];
+    /** Hop depth from `from` to each reachable path. */
+    depths: Map<string, number>;
+    /** True when traversal hit `maxDepth` and some neighbors were not explored. */
+    truncated: boolean;
+};
+/**
+ * Reachability query over a {@link Graph.describe} snapshot.
+ *
+ * Traversal follows `deps` (upstream) and reverse-`deps` (downstream). Edges
+ * are derived from deps post Unit 7, so `edges[]` in the snapshot is
+ * redundant with deps — it's walked defensively in case a caller supplied a
+ * pre-Unit-7 snapshot.
+ *
+ * @param described - `graph.describe()` output to traverse.
+ * @param from - Start path (qualified node path).
+ * @param direction - Traversal direction (ignored when `opts.both` is `true`).
+ * @param options - Optional `maxDepth`, `both`, `withDetail`.
+ * @returns Sorted paths (flat) — or {@link ReachableResult} when `withDetail: true`.
+ */
+declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions & {
+    withDetail: true;
+}): ReachableResult;
+declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
+
+export { diffForWAL as A, graphProfile as B, reachable as C, type DescribeFilter as D, Graph as G, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAttachStorageOptions as b, type GraphProfileResult as c, type GraphProfileOptions as d, GRAPH_META_SEGMENT as e, type GraphActorOptions as f, type GraphCheckpointRecord as g, type GraphDescribeOptions as h, type GraphDescribeOutput as i, type GraphDiagramDirection as j, type GraphDiagramOptions as k, type GraphDiffChange as l, type GraphDiffResult as m, type GraphFactoryContext as n, type GraphNodeFactory as o, type GraphObserveAll as p, type GraphObserveOne as q, type GraphPersistSnapshot as r, type GraphVersionChange as s, type GraphWALDiff as t, type ObserveEvent as u, type ObserveOptions as v, type ObserveResult as w, type ObserveTheme as x, type ObserveThemeName as y, type ReachableOptions as z };