@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/graph-D9LFnda9.d.ts

@@ -1,1861 +0,0 @@
-import { A as Actor, l as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-kK3CvTrR.js';
-import { D as DescribeNodeOutput, a as DerivedFn, E as EffectFn, c as DescribeDetail, d as DescribeField } from './sugar-fhLIE7TT.js';
-import { StorageHandle } from './extra/storage-core.js';
-import { SnapshotStorageTier } from './extra/storage-tiers.js';
-
-/**
- * Pure structural diff over `GraphDescribeOutput` snapshots.
- *
- * Produces a {@link DescribeChangeset} of {@link DescribeEvent}s describing the
- * topology delta from `prev` → `next`. Used by `Graph.describe({ reactive:
- * "diff" })` internally and re-exported here for static-snapshot diffing
- * (e.g. computing the topology delta between two persisted snapshots without
- * spinning up a live graph).
- *
- * Topology-only — no value/state events. The data layer lives in
- * `Graph.observe`. Per Tier 1.5.1 (locked Session A.1), `DescribeEvent` and
- * {@link ObserveEvent} have disjoint type sets so a consumer can route both
- * streams without ambiguity.
- *
- * `flushedAt_ns` is taken from `core/clock.ts`'s `monotonicNs()` so callers can
- * order changesets across the same process without wall-clock skew.
- *
- * @module
- */
-
-/**
- * Meta dictionary attached to a node, as surfaced by
- * {@link DescribeNodeOutput.meta}. Aliased here so {@link DescribeEvent}'s
- * `node-meta-changed` variant has a stable, narrow type.
- */
-type Meta = Record<string, unknown>;
-/**
- * One topology delta between two `describe()` snapshots. Disjoint from
- * `ObserveEvent` (the data-layer envelope).
- */
-type DescribeEvent = {
-    type: "node-added";
-    path: string;
-    node: DescribeNodeOutput;
-} | {
-    type: "node-removed";
-    path: string;
-} | {
-    type: "node-meta-changed";
-    path: string;
-    prevMeta: Meta;
-    nextMeta: Meta;
-} | {
-    type: "edge-added";
-    from: string;
-    to: string;
-} | {
-    type: "edge-removed";
-    from: string;
-    to: string;
-} | {
-    type: "subgraph-mounted";
-    path: string;
-} | {
-    type: "subgraph-unmounted";
-    path: string;
-};
-/**
- * Coalesced batch of {@link DescribeEvent}s emitted as a single DATA wave by
- * `Graph.describe({ reactive: "diff" })` per outermost batch flush.
- *
- * `flushedAt_ns` is monotonic (from `core/clock.ts`); compare against another
- * changeset's `flushedAt_ns` to order them. `events` is empty only when
- * `topologyDiff` is called with two structurally identical snapshots; reactive
- * variants suppress empty changesets so consumers don't see no-op DATA waves.
- */
-type DescribeChangeset = {
-    events: ReadonlyArray<DescribeEvent>;
-    flushedAt_ns: number;
-};
-/**
- * Pure topology delta from `prev` → `next`. No I/O, no node references — purely
- * over the JSON shape `Graph.describe()` returns.
- *
- * Event ordering within a changeset:
- *   1. `subgraph-mounted` (added subgraphs first — their nodes follow)
- *   2. `node-added`
- *   3. `node-meta-changed`
- *   4. `edge-added`
- *   5. `edge-removed`
- *   6. `node-removed`
- *   7. `subgraph-unmounted` (last — node removals already reported)
- *
- * Each group is emitted in code-point sort order on the path / `${from}->${to}`
- * key so the changeset is deterministic across runs (useful for snapshot
- * tests and golden-output assertions).
- */
-declare function topologyDiff(prev: GraphDescribeOutput, next: GraphDescribeOutput): DescribeChangeset;
-
-/**
- * Causal walkback over a {@link Graph.describe} snapshot (roadmap §9.2).
- *
- * `explainPath` finds the shortest dep-chain from `from` to `to` and returns a
- * step-by-step {@link CausalChain} enriched with each node's current value,
- * status, last-mutation actor, and any `graph.trace()` reasoning annotation.
- *
- * Pure function over the snapshot — peer to {@link reachable}. The
- * {@link Graph.explain} instance method auto-passes `describe({detail:"standard"})`
- * plus runtime annotations and `lastMutation` so callers get rich output by
- * default.
- *
- * @module
- */
-
-/** One node along the causal chain returned by {@link explainPath}. */
-interface CausalStep {
-    /** Qualified node path. */
-    path: string;
-    /** Node kind (`state` / `derived` / `producer` / etc.). */
-    type: DescribeNodeOutput["type"];
-    /** Status as of the source snapshot. */
-    status?: DescribeNodeOutput["status"];
-    /** Cached value at snapshot time (omitted when describe didn't include it). */
-    value?: unknown;
-    /** Hop distance from `from` (0 = `from`, N = `to`). */
-    hop: number;
-    /** Annotation set via `graph.trace(path, annotation)` or `graph.add(node, { name: path, annotation })`, when present. */
-    annotation?: string;
-    /** Most recent guarded mutation, when known. */
-    lastMutation?: Readonly<{
-        actor: Actor;
-        timestamp_ns: number;
-    }>;
-    /** V0/V1 versioning info, when present. */
-    v?: DescribeNodeOutput["v"];
-    /** Index of this step in the next step's `deps` (i.e. which dep slot fed forward). */
-    dep_index?: number;
-    /**
-     * All dep slots when the same dep appears multiple times in the next
-     * step's `deps`. Present only for multi-edge connections; `dep_index`
-     * always equals `dep_indices[0]` when set.
-     */
-    dep_indices?: number[];
-}
-/** Outcome of an {@link explainPath} call. */
-interface CausalChain {
-    from: string;
-    to: string;
-    /** True when a path was found. */
-    found: boolean;
-    /** Why the chain may be empty/incomplete. `"ok"` when `found` is true.
-     * `"pending"` is the reactive-explain sentinel emitted while reactive args
-     * are waiting for their first DATA (qa D5). */
-    reason: "ok" | "no-such-from" | "no-such-to" | "no-path" | "max-depth-exceeded" | "pending";
-    /** Ordered steps — first element is `from`, last is `to`. Empty when `!found`. */
-    steps: readonly CausalStep[];
-    /** Pretty multi-line rendering. Always present, even on failure (one-line message). */
-    text: string;
-    /** JSON-serializable form (drops `text` to keep payloads compact). */
-    toJSON(): {
-        from: string;
-        to: string;
-        found: boolean;
-        reason: CausalChain["reason"];
-        steps: readonly CausalStep[];
-    };
-}
-/** Options for {@link explainPath}. */
-interface ExplainPathOptions {
-    /** Maximum hop distance to search. Omit for unbounded. */
-    maxDepth?: number;
-    /** Per-path reasoning annotations (typically `graph.trace()` output map). */
-    annotations?: ReadonlyMap<string, string>;
-    /** Per-path `lastMutation` map (overrides describe-derived values). */
-    lastMutations?: ReadonlyMap<string, Readonly<{
-        actor: Actor;
-        timestamp_ns: number;
-    }>>;
-    /**
-     * When `true` and `from === to`, search for a non-trivial cycle (path
-     * back to `from` through ≥1 other node) instead of returning the trivial
-     * single-step. Use when debugging feedback loops (COMPOSITION-GUIDE §7).
-     * If no real cycle exists, falls back to the trivial single-step. Default
-     * `false` — backward-compatible.
-     */
-    findCycle?: boolean;
-}
-/**
- * Walks backward from `to` through `deps` to find the shortest path to `from`,
- * then assembles an ordered, enriched {@link CausalChain}.
- *
- * @param described - `graph.describe()` output (any detail level; richer detail → richer steps).
- * @param from - Path of the upstream node (the cause).
- * @param to - Path of the downstream node (the effect).
- * @param opts - Optional `maxDepth` and per-path annotation overlays.
- * @returns A {@link CausalChain} — `found:false` with a `reason` when no path exists.
- *
- * @example
- * ```ts
- * import { explainPath } from "@graphrefly/graphrefly-ts";
- * const chain = explainPath(graph.describe({ detail: "standard" }), "input", "result");
- * console.log(chain.text);
- * ```
- */
-declare function explainPath(described: GraphDescribeOutput, from: string, to: string, opts?: ExplainPathOptions): CausalChain;
-
-/**
- * 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;
-    /**
-     * Tier 1.5.3 Phase 2.5 (Session A.1 lock + Phase 2.5 design DG1=B, 2026-04-27).
-     * Top-level factory identifier for Graph-returning factories (`agentMemory`,
-     * `harnessLoop`, `pipelineGraph`, etc.). When set, `describe()` surfaces
-     * `factory` + `factoryArgs` at the top of `GraphDescribeOutput` so consumers
-     * can identify provenance, and `compileSpec` can delegate reconstruction to
-     * `catalog.graphFactories[factory]` with `factoryArgs`. Prefer the
-     * post-construction `Graph.prototype.tagFactory(name, args?)` mutator inside
-     * the factory body over passing here directly.
-     */
-    factory?: string;
-    /**
-     * JSON-serializable subset of the construction args. For non-JSON fields
-     * (LLMAdapter, callbacks, embedders), prefer the {@link placeholderArgs}
-     * helper which substitutes descriptive `"<Node>"` / `"<function>"` strings
-     * (DG2 = ii). Catalog `graphFactories` recipients receive this back during
-     * `compileSpec` to recreate the graph with the user-supplied runtime ctx.
-     */
-    factoryArgs?: unknown;
-    [key: string]: unknown;
-}
-/**
- * Options for {@link Graph.derived}. Forwarded to the underlying
- * {@link derived} primitive plus graph-level extras.
- *
- * - `keepAlive: true` — installs an internal subscription so the node
- *   stays activated and `.cache` stays current for **external consumers**
- *   (UI render, debug snapshot, audit log) with no real subscriber. The
- *   subscription self-prunes on the node's terminal (`COMPLETE` / `ERROR`
- *   / `TEARDOWN`) and is also drained by {@link Graph.destroy}, so
- *   repeated `graph.remove(name)` cycles do not accumulate stale
- *   disposers.
- *
- *   **Do not read `node.cache` from inside another reactive fn** (spec
- *   §5.12) — declare the node as a real dep instead. `keepAlive` is a
- *   convenience for *external* read patterns, not a shortcut around the
- *   message protocol.
- * - `signal` — when aborted, removes this node from the graph via
- *   {@link Graph.remove}, which sends `[[TEARDOWN]]` and drains cleanup
- *   hooks. Already-aborted signals trigger removal synchronously.
- * - `equals`, `initial`, `meta` — pass-through to {@link NodeOptions}.
- * - `annotation` — forwarded to {@link Graph.add} (see `graph.trace`).
- */
-interface GraphDerivedOptions<T> {
-    equals?: (a: T, b: T) => boolean;
-    initial?: T | null;
-    keepAlive?: boolean;
-    signal?: AbortSignal;
-    meta?: Record<string, unknown>;
-    annotation?: string;
-}
-/**
- * Options for {@link Graph.effect}.
- *
- * - `signal` — when aborted, removes this node from the graph via
- *   {@link Graph.remove} (fires the effect's `deactivate` cleanup).
- * - `meta` / `annotation` — same forwarding shape as
- *   {@link GraphDerivedOptions}.
- */
-interface GraphEffectOptions {
-    signal?: AbortSignal;
-    meta?: Record<string, unknown>;
-    annotation?: string;
-}
-/**
- * Options for {@link Graph.produce}.
- *
- * - `signal` — forwarded to the underlying {@link fromAny} for in-flight
- *   cancellation of `Promise` / `AsyncIterable` sources, AND triggers
- *   {@link Graph.remove} when aborted so the graph topology reflects the
- *   cancellation.
- * - `equals` / `meta` / `annotation` — same forwarding shape as
- *   {@link GraphDerivedOptions}.
- */
-interface GraphProduceOptions<T> {
-    equals?: (a: T, b: T) => boolean;
-    signal?: AbortSignal;
-    meta?: Record<string, unknown>;
-    annotation?: string;
-}
-/**
- * Source shapes accepted by {@link Graph.produce}. Excludes `Node<T>` —
- * Node→Node passthrough is rejected at the boundary because `fromAny`
- * passes Nodes through verbatim, which would silently drop `meta`/`equals`
- * options and bypass the `add()` registration's name semantics. For
- * Node→Node, use {@link Graph.derived} with `keepAlive: true` instead.
- */
-type GraphProduceInput<T> = PromiseLike<T> | AsyncIterable<T> | Iterable<T> | T;
-/** 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 = {
-    /**
-     * Scope `describe()` to what `actor` is allowed to observe. Accepts a
-     * static {@link Actor} (resolved at call time) or a `Node<Actor>` — when a
-     * Node is passed and `reactive: true` is set, the reactive describe handle
-     * subscribes to the actor node and re-derives whenever the actor changes,
-     * so harnesses that bind a reactive actor (e.g. per-turn `currentActor`
-     * state) get a single live describe Node instead of re-calling
-     * `describe({ actor })` per turn.
-     *
-     * **Cache-undefined semantics:** when a `Node<Actor>` is supplied whose
-     * `cache` is `undefined` (e.g. a `producer` that has not yet emitted),
-     * describe is treated identically to `actor: undefined` — i.e. **no
-     * scoping** (full visibility). This matches every other Node-cache read in
-     * the codebase, but means a not-yet-active actor node degrades to "describe
-     * everything." Activate the actor node (subscribe + emit, or seed via
-     * `state(initial)`) before calling `describe` if you rely on guard
-     * scoping. In `reactive: true` mode the describe re-derives once the
-     * actor node populates.
-     *
-     * **Terminal-type handling:** if the supplied `Node<Actor>` emits
-     * `COMPLETE`, `ERROR`, or `TEARDOWN`, the reactive describe releases the
-     * actor subscription and re-derives one last time against the final
-     * `actor.cache` value. Subsequent describe outputs reflect that frozen
-     * cache until `handle.dispose()` runs.
-     */
-    actor?: Actor | Node<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[];
-    /**
-     * Reactive describe (D2):
-     * - `true` — return `{ node, dispose }` where `node` emits a fresh
-     *   `GraphDescribeOutput` every time the graph state settles. Same
-     *   coalescing as {@link Graph.explain} with `{ reactive: true }`.
-     * - `"diff"` — return `{ node, dispose }` where `node` emits a
-     *   {@link DescribeChangeset} per topology change. Empty changesets are
-     *   suppressed; the initial cache is a synthetic full-add diff so a fresh
-     *   subscriber sees the current topology as adds via push-on-subscribe.
-     *   (Tier 1.5.1 — Session A.1 lock).
-     */
-    reactive?: boolean | "diff";
-    /** Reactive-only: name for the backing derived node (default `"describe"`). */
-    reactiveName?: string;
-};
-/** Handle returned by {@link Graph.describe} with `{ reactive: true }`. */
-interface ReactiveDescribeHandle<T> {
-    readonly node: Node<T>;
-    dispose(): void;
-}
-/** 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[];
-    /**
-     * Top-level factory identifier (Tier 1.5.3 Phase 2.5 — DG1=B). Present when
-     * the graph was constructed by a Graph-returning factory that called
-     * `Graph.prototype.tagFactory(name, args?)` (or set `GraphOptions.factory`).
-     * Used by `compileSpec` for catalog-based reconstruction via
-     * `catalog.graphFactories[factory]`.
-     */
-    factory?: string;
-    /** JSON-serializable construction args paired with `factory`. */
-    factoryArgs?: unknown;
-    /**
-     * 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 `SnapshotStorageTier.save`. Written by
- * {@link Graph.attachSnapshotStorage} 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 = {
-    name: string;
-    seq: number;
-    timestamp_ns: number;
-    format_version: number;
-} & ({
-    mode: "full";
-    snapshot: GraphPersistSnapshot;
-} | {
-    mode: "diff";
-    diff: GraphWALDiff;
-});
-/** Options for {@link Graph.attachSnapshotStorage}. */
-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
-     * `attachSnapshotStorage` 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: SnapshotStorageTier<GraphCheckpointRecord>) => void;
-};
-/**
- * Event emitted by {@link Graph.topology} on every structural change to the
- * graph's own registry. Does NOT include value mutations (use `observe()` for
- * those) or transitively nested subgraph events (subscribe to each mounted
- * child's `topology` for that).
- *
- * - `"added"` — `name` is the local key registered via {@link Graph.add}
- *   (`nodeKind: "node"`) or {@link Graph.mount} (`nodeKind: "mount"`).
- * - `"removed"` — emitted AFTER {@link Graph.remove} completes teardown.
- *   `audit` is the full {@link GraphRemoveAudit} returned to the caller.
- */
-type TopologyEvent = {
-    kind: "added";
-    name: string;
-    nodeKind: "node" | "mount";
-} | {
-    kind: "removed";
-    name: string;
-    nodeKind: "node" | "mount";
-    audit: GraphRemoveAudit;
-};
-/**
- * Direction options for diagram exports. Mirrors `DiagramDirection` from
- * `@graphrefly/graphrefly/extra/render` (the renderers consume their own
- * structurally-identical type) — re-exported here so callers building
- * options for `Graph` ergonomics don't need a separate import.
- */
-type GraphDiagramDirection = "TD" | "LR" | "BT" | "RL";
-/**
- * Snapshot format version (§3.8). Exported so the surface layer's
- * `saveSnapshot` writes the same `format_version` as
- * `Graph.attachSnapshotStorage` — one source of truth prevents silent wire
- * drift between auto-checkpoint and one-shot persistence paths.
- */
-declare const SNAPSHOT_VERSION = 1;
-/**
- * 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" | "stage-log";
-    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";
-/**
- * Tier name for {@link ObserveEvent} filtering. Aligns with spec §1.2 message
- * tier semantics — each `ObserveTier` corresponds to one or more protocol
- * message types. Used by {@link ObserveOptions.tiers} to scope observation to
- * a subset of event categories (e.g. `tiers: ["error", "complete", "teardown"]`
- * for failure-only health monitoring).
- */
-type ObserveTier = ObserveEvent["type"];
-/**
- * Coalesced batch of {@link ObserveEvent}s emitted as one DATA wave per
- * outermost batch flush by `Graph.observe({ reactive: true })`.
- *
- * Disjoint from `DescribeChangeset` (the topology-layer envelope). Each event
- * carries its own `path` so consumers route per-path without unwrapping the
- * envelope first. `flushedAt_ns` is monotonic via `core/clock.ts`.
- */
-type ObserveChangeset = {
-    events: ReadonlyArray<ObserveEvent>;
-    flushedAt_ns: number;
-};
-/** 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;
-    /**
-     * Filter observed events to these tiers only. When omitted, all event types
-     * are delivered. Applies to both the structured callback and the reactive
-     * variants (`observe({ reactive: true })`).
-     *
-     * Example: `tiers: ["error", "complete", "teardown"]` for failure-only
-     * health monitoring; `tiers: ["data"]` for value-flow tracking.
-     */
-    tiers?: readonly ObserveTier[];
-    /**
-     * Return a `Node<ObserveChangeset>` that emits one DATA wave per outermost
-     * batch flush, with all observed events for that flush coalesced into a
-     * single changeset. Auto-enables structured mode (the reactive variant
-     * delivers {@link ObserveEvent}s, not raw messages).
-     *
-     * Coalescing matches `describe({ reactive: true })`'s `registerBatchFlushHook`
-     * mechanism — N events in one batch → one changeset DATA wave at flush.
-     */
-    reactive?: boolean;
-    /** Optional name for the reactive changeset node when `reactive: true`. */
-    reactiveName?: string;
-    /**
-     * When set, auto-enables structured mode and attaches a logger.
-     * - `"pretty"` — colored one-line output per event.
-     * - `"json"` — one JSON object per event.
-     * - `"stage-log"` — pipeline-stage-labeled output for multi-node
-     *   observers. Auto-enables `timeline: true` so each line carries an
-     *   elapsed-seconds offset from the subscription. Provide a
-     *   {@link stageLabels} map to label each observed path; paths without a
-     *   mapping fall back to the path string.
-     */
-    format?: "pretty" | "json" | "stage-log";
-    /** 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;
-    /**
-     * Stage labels for `format: "stage-log"`. Keys are observe paths; values
-     * are short stage names (e.g. `{ "intake::latest": "INTAKE" }`). Paths
-     * without a mapping render under the path string itself. Ignored for
-     * other formats.
-     */
-    stageLabels?: Record<string, string>;
-    /**
-     * 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;
-    /**
-     * Attribution for `data`/`error` events (B9 — actor threading). When
-     * the originating `node.down(...)` call supplied an `actor` via
-     * `NodeTransportOptions`, it's forwarded here as read from
-     * `Node.lastMutation`. Internal / unattributed writes stamp the
-     * library's `DEFAULT_ACTOR` (`{type: "system", id: ""}`) rather than
-     * being silently dropped, so downstream policy/audit consumers can
-     * evaluate policies against a well-formed actor in every case.
-     *
-     * Not populated for tier-1/tier-2 protocol events (`dirty`, `resolved`,
-     * `pause`, `resume`, `invalidate`, `teardown`) — those don't carry
-     * caller attribution.
-     */
-    actor?: Actor;
-}
-/** 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(state(0, { name: "counter" }));
- * ```
- *
- * @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;
-    /** @internal Set in {@link destroy} / `_destroyClearOnly`; surfaced via {@link destroyed}. */
-    private _destroyed;
-    /**
-     * @internal Lazy `TopologyEvent` producer. Created on first `.topology`
-     * access. Zero cost until something subscribes — producer fn only runs when
-     * the first sink attaches, registering one handler into
-     * {@link Graph._topologyEmitters}.
-     */
-    private _topology;
-    /**
-     * @internal Active emit handlers for the topology producer. Each entry is
-     * the closure registered by the producer fn on activation; cleared on
-     * deactivation. `_emitTopology` broadcasts through every entry (there is at
-     * most one per activation cycle of the producer).
-     */
-    private readonly _topologyEmitters;
-    /**
-     * @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.
-     */
-    /** Tier 1.5.3 Phase 2.5 — top-level factory tag for Graph-returning factories. */
-    private _factory?;
-    private _factoryArgs?;
-    constructor(name: string, opts?: GraphOptions);
-    /**
-     * Tag this graph with its constructing factory's identifier and args.
-     * Used by Graph-returning factories (`agentMemory`, `harnessLoop`,
-     * `pipelineGraph`, etc.) so `describe()` exposes provenance and
-     * `compileSpec` can delegate reconstruction to
-     * `catalog.graphFactories[factory]`. Tier 1.5.3 Phase 2.5 (DG1=B).
-     *
-     * `factoryArgs` should be JSON-serializable. For non-JSON fields
-     * (LLMAdapter, callbacks, etc.), use {@link placeholderArgs} to
-     * substitute descriptive strings (DG2=ii).
-     *
-     * Returns `this` for fluent chaining inside factory bodies.
-     */
-    tagFactory(factory: string, factoryArgs?: unknown): this;
-    /**
-     * 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[];
-    /**
-     * Reactive stream of structural changes to this graph's own registry
-     * (add / mount / remove). Value mutations live on `observe()`; this
-     * companion only fires when the topology shape changes.
-     *
-     * Lazy: the underlying node is created on first access and activates when
-     * something subscribes. No emission replay — late subscribers do not
-     * receive historical events and should snapshot via {@link Graph.describe}
-     * before listening for incremental changes. Events that fire while the
-     * producer has zero subscribers are dropped (no retention).
-     *
-     * Own-graph only: a parent's `topology` does NOT emit for structural
-     * changes inside a mounted child. Transitive consumers subscribe to each
-     * child's topology separately (recurse through `topology`'s own "added"
-     * events with `nodeKind: "mount"` to discover new children).
-     *
-     * See {@link TopologyEvent} for payload shape.
-     *
-     * @category observability
-     */
-    get topology(): Node<TopologyEvent>;
-    /**
-     * @internal Fire a {@link TopologyEvent} to every active subscriber of
-     * `this.topology`. No-op when the topology node has never been accessed or
-     * currently has no sinks — zero cost for graphs nobody observes.
-     */
-    private _emitTopology;
-    /**
-     * 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(state(0, { name: "counter" }))`.
-     *
-     * **Signature:** `add(node, { name?, annotation? })`. Name lives in opts;
-     * falls back to `node.name` from the node's own options. Throws if neither
-     * is a non-empty string.
-     *
-     * The optional `opts.annotation` installs an initial
-     * `graph.trace(name, annotation)` entry — same effect as calling
-     * `graph.trace` right after, but reads naturally next to the registration.
-     *
-     * @param node - Node instance to own.
-     * @param opts - `{ name?, annotation? }`.
-     */
-    /**
-     * O(1) reverse lookup — returns the name the given Node was registered
-     * under via {@link Graph.add}, or `undefined` if it isn't registered here.
-     *
-     * Audit 2 (2026-04-24): replaces the orchestration's `findRegisteredNodePath`
-     * O(nodes²) describe-scan with direct `WeakMap<Node, string>` lookup.
-     */
-    nameOf(node: Node): string | undefined;
-    add<T extends Node>(node: T, opts?: {
-        name?: string;
-        annotation?: string;
-    }): 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;
-    /**
-     * Internal: register a self-pruning keepalive subscription. The sink
-     * watches for terminal messages (`COMPLETE`/`ERROR`/`TEARDOWN`) on `n`
-     * and removes the disposer from `_disposers` when one arrives, so
-     * repeated `graph.remove(name)` cycles do not accumulate stale
-     * disposers (qa B3).
-     */
-    private _registerSelfPruningKeepalive;
-    /**
-     * Internal: wire an `AbortSignal` so its abort triggers
-     * `graph.remove(name)`. Already-aborted signals trigger removal
-     * synchronously. The abort listener is itself registered as a graph
-     * disposer so it gets cleaned up if `destroy()` runs first (qa B4).
-     */
-    private _wireSignalToRemove;
-    /**
-     * Path-based reactive derivation. Resolves each entry in `depPaths` via
-     * {@link Graph.resolve}, builds a {@link derived} node, registers it via
-     * {@link Graph.add}, and returns the registered Node.
-     *
-     * **First-run gate inherited.** fn does not fire until every dep has
-     * delivered at least one real DATA — same gate as `derived()` (spec §2.7,
-     * `partial: false`). A SENTINEL dep holds activation; `null` is a real
-     * DATA value and releases the gate. **Empty `depPaths` is a vacuous
-     * gate** — fn fires once synchronously on first activation. Use this
-     * for one-shot constants only; for async sources prefer
-     * {@link Graph.produce}.
-     *
-     * **`keepAlive: true`** — installs an internal subscription so the node
-     * stays activated and `.cache` stays current for **external consumers**
-     * (UI render, debug snapshot, audit log). The subscription self-prunes
-     * on the node's terminal and is also drained by {@link Graph.destroy}.
-     *
-     * **Do not read `node.cache` from inside another reactive fn** — that
-     * is a §5.12 boundary violation regardless of `keepAlive`. Declare the
-     * node as a real dep instead so the edge appears in `describe()` and
-     * the message protocol carries the value.
-     *
-     * **`signal`** — when aborted, removes this node from the graph.
-     *
-     * @param name - Local registration name (must be unique on this graph).
-     * @param depPaths - `::`-qualified paths resolved at construction time.
-     * @param fn - Pure compute receiving sugar-unwrapped scalar dep values.
-     * @param opts - {@link GraphDerivedOptions}.
-     * @returns The registered `Node<T>`.
-     */
-    derived<T>(name: string, depPaths: readonly string[], fn: DerivedFn<T>, opts?: GraphDerivedOptions<T>): Node<T>;
-    /**
-     * Path-based managed side effect. Resolves each entry in `depPaths`,
-     * builds an {@link effect} node, registers it, and returns the
-     * registered Node. fn does not auto-emit — call `actions.emit(v)` /
-     * `actions.down(msgs)` explicitly to produce downstream messages.
-     *
-     * **Cleanup.** Return a cleanup function (`() => void`) or granular
-     * hooks (`{ beforeRun?, deactivate?, invalidate? }`) — fired on the
-     * matching transition by the underlying primitive (see
-     * {@link NodeFnCleanup}). Graph teardown propagates `[[TEARDOWN]]`
-     * which triggers `deactivate`.
-     *
-     * **`signal`** — when aborted, removes this node from the graph (fires
-     * the effect's `deactivate` cleanup).
-     *
-     * @param name - Local registration name (must be unique on this graph).
-     * @param depPaths - `::`-qualified paths resolved at construction time.
-     * @param fn - Side-effect receiving sugar-unwrapped scalar dep values.
-     * @param opts - {@link GraphEffectOptions}.
-     * @returns The registered `Node<unknown>`.
-     */
-    effect(name: string, depPaths: readonly string[], fn: EffectFn, opts?: GraphEffectOptions): Node<unknown>;
-    /**
-     * Wraps an external/async source as a named graph node via
-     * {@link fromAny}. Accepts {@link GraphProduceInput} shapes:
-     * `Promise`, `AsyncIterable`, `Iterable`, or scalar.
-     *
-     * **Node sources are rejected.** For `Node → Node`, use
-     * {@link Graph.derived} with `keepAlive: true` — `fromAny` would
-     * passthrough a Node verbatim and silently drop `meta`/`equals`
-     * options. The type signature excludes `Node<T>`; a runtime guard
-     * catches casts.
-     *
-     * **`undefined` is rejected.** `undefined` is the global SENTINEL;
-     * emitting it as DATA would corrupt downstream first-run gates.
-     * `null` (a valid DATA value) is accepted.
-     *
-     * **`signal`** — forwarded to {@link fromAny} for in-flight cancel of
-     * Promise/AsyncIterable sources, AND triggers {@link Graph.remove}
-     * when aborted so the topology reflects the cancellation.
-     *
-     * @param name - Local registration name (must be unique on this graph).
-     * @param source - Any {@link GraphProduceInput} shape.
-     * @param opts - {@link GraphProduceOptions}.
-     * @returns The registered `Node<T>`.
-     */
-    produce<T>(name: string, source: GraphProduceInput<T>, opts?: GraphProduceOptions<T>): Node<T>;
-    /**
-     * Atomic multi-mutation. Same semantics as core {@link batch}: DATA and
-     * RESOLVED emissions inside `fn` defer, DIRTY propagates immediately, and
-     * downstream consumers see one coalesced wave (spec §1.3 invariant 7).
-     * Exposed on `Graph` for discoverability and import hygiene — pattern
-     * authors can reach for `graph.batch(...)` without importing `batch` from
-     * the core entry. Shares one global frame with the core import; nesting
-     * either way is supported.
-     *
-     * **Caveat:** if `fn` throws, deferred DATA is discarded but DIRTY
-     * messages already propagated synchronously, leaving downstream nodes
-     * in `dirty` status with stale `.cache`. Catch and emit compensating
-     * INVALIDATE/RESET if you need to recover.
-     */
-    batch(fn: () => void): 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;
-    mount(name: string): Graph;
-    mount(name: string, builder: (sub: Graph) => void): Graph;
-    /**
-     * 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).
-     *
-     * Returns the {@link GraphDescribeOutput} object directly (or a
-     * `ReactiveDescribeHandle` when `{ reactive: true | "diff" }` is set).
-     *
-     * For formatted output (Mermaid / D2 / ASCII / pretty / JSON text), pass
-     * the snapshot to one of the pure renderers in
-     * `@graphrefly/graphrefly/extra/render`:
-     *
-     * ```ts
-     * import { toMermaid, toAscii } from "@graphrefly/graphrefly/extra/render";
-     *
-     * const mermaid = toMermaid(graph.describe());
-     * const ascii = toAscii(graph.describe(), { direction: "TD" });
-     * ```
-     *
-     * For live formatted output, compose with `derived`:
-     *
-     * ```ts
-     * import { derived } from "@graphrefly/graphrefly";
-     * import { toMermaid } from "@graphrefly/graphrefly/extra/render";
-     *
-     * const live = derived(
-     *   [graph.describe({ reactive: true }).node],
-     *   ([g]) => toMermaid(g),
-     * );
-     * ```
-     *
-     * For the spec projection (type + deps + meta, strip runtime status/value),
-     * pass `detail: "spec"`.
-     *
-     * @param options - Optional `actor` for guard-scoped visibility, `filter`
-     *   for selective output, `detail` / `fields` for projection, `reactive`
-     *   for the live handle.
-     *
-     * @example
-     * ```ts
-     * graph.describe()                                         // full snapshot object
-     * graph.describe({ filter: { status: "errored" } })        // filtered object
-     * graph.describe({ detail: "spec" })                       // GraphSpec projection
-     * graph.describe({ reactive: true })                       // live snapshot Node
-     * ```
-     */
-    describe(options: GraphDescribeOptions & {
-        reactive: "diff";
-    }): ReactiveDescribeHandle<DescribeChangeset>;
-    describe(options: GraphDescribeOptions & {
-        reactive: true;
-    }): ReactiveDescribeHandle<GraphDescribeOutput>;
-    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[];
-    /**
-     * Causal walkback: shortest dep-chain from `from` to `to`, enriched with
-     * each node's value, status, last-mutation actor, and reasoning annotation
-     * from {@link Graph.trace}. Wraps {@link explainPath} (roadmap §9.2).
-     *
-     * Same question, two answers:
-     * - **Static (default)** — `explain(from, to, opts?)` returns a single
-     *   {@link CausalChain} snapshot of the graph at call time. Reactive
-     *   args (any `Node<...>`) are resolved to their current cache once.
-     * - **Reactive** — `explain(from, to, { reactive: true, ... })` returns
-     *   `{ node: Node<CausalChain>; dispose: () => void }`. The node
-     *   recomputes whenever a `data` / `error` / `complete` / `teardown`
-     *   event fires anywhere on the graph's structured observe stream OR
-     *   any reactive arg (`Node<string>` for `from`/`to`,
-     *   `Node<number>` for `maxDepth`, `Node<boolean>` for `findCycle`)
-     *   emits. Replaces the former `reactiveExplainPath`.
-     *
-     * Tier 3.5 reactive-opt carve-out (F.9): `from`, `to`, `maxDepth`, and
-     * `findCycle` accept `Node<...>` in addition to their plain types. When
-     * mixed (some reactive, some static), the reactive variant subscribes only
-     * to the Node-typed args; static args pass through unchanged. The static
-     * call snapshots all reactive args at call time — for live re-walking, use
-     * `{ reactive: true }`.
-     *
-     * **File path-scoped observe is deferred** — the reactive variant
-     * subscribes to whole-graph observe today (a perf gap, not a spec
-     * violation). Tracked in `docs/optimizations.md` Tier 10.8 deferred
-     * follow-up: "reactiveExplainPath file-path-scoped observe".
-     *
-     * @param from - Upstream node path (the cause). `string | Node<string>`.
-     * @param to - Downstream node path (the effect). `string | Node<string>`.
-     * @param opts - Optional `maxDepth` (`number | Node<number>`) and
-     *   `findCycle` (`boolean | Node<boolean>`). When `findCycle:true`
-     *   and `from === to`, returns the shortest cycle through other nodes
-     *   (useful for diagnosing feedback loops, COMPOSITION-GUIDE §7).
-     *   When `reactive: true`, also accepts `name?`.
-     */
-    explain(from: string | Node<string>, to: string | Node<string>, opts?: {
-        /**
-         * DF13 (2026-04-29) — narrow the static overload to forbid
-         * `reactive: true`. A caller passing `{ reactive: true, ... }`
-         * is steered into the reactive overload instead of falling
-         * through to the implementation signature's union return.
-         */
-        reactive?: false;
-        maxDepth?: number | Node<number>;
-        findCycle?: boolean | Node<boolean>;
-    }): CausalChain;
-    explain(from: string | Node<string>, to: string | Node<string>, opts: {
-        reactive: true;
-        maxDepth?: number | Node<number>;
-        findCycle?: boolean | Node<boolean>;
-        name?: string;
-    }): {
-        node: Node<CausalChain>;
-        dispose: () => void;
-    };
-    private _explainStatic;
-    private _describeReactive;
-    /**
-     * Reactive topology-diff variant of `describe()`. Wraps `_describeReactive`'s
-     * snapshot stream and emits a `DescribeChangeset` per change, suppressing
-     * empty changesets. The initial cache is a synthetic full-add diff so a
-     * fresh subscriber sees the current topology as a single `node-added` /
-     * `edge-added` / `subgraph-mounted` payload via push-on-subscribe.
-     */
-    private _describeReactiveDiff;
-    private _explainReactive;
-    /**
-     * @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 & {
-        reactive: true;
-    }): Node<ObserveChangeset>;
-    observe(options: ObserveOptions & {
-        reactive: true;
-    }): Node<ObserveChangeset>;
-    observe(path: string, options?: ObserveOptions & StructuredTriggers): ObserveResult;
-    observe(path: string, options?: ObserveOptions): GraphObserveOne;
-    observe(options: ObserveOptions & StructuredTriggers): ObserveResult;
-    observe(options?: ObserveOptions): GraphObserveAll;
-    /**
-     * Reactive observe variant — wraps the structured observer and emits one
-     * `ObserveChangeset` DATA per outermost batch flush, with all observed
-     * events for that flush coalesced into a single envelope. Tier filter
-     * (`options.tiers`) drops out-of-scope events before accumulation.
-     *
-     * Cleanup is producer-bound: the structured observer is torn down when the
-     * last consumer of the returned node unsubscribes.
-     */
-    private _observeReactive;
-    /** 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;
-    /**
-     * `true` once {@link destroy} has run on this graph. Useful for reactive
-     * consumers that hold a Graph reference and want to fail fast / skip
-     * work if the graph went away mid-flight (e.g. a `switchMap` over a
-     * destroyable graph reference). Set after the destroy cascade completes;
-     * stays `true` even if the instance is later reused via {@link add}.
-     */
-    get destroyed(): boolean;
-    /**
-     * Clear structure after parent already signaled TEARDOWN through this subtree.
-     *
-     * Drains both `_disposers` and `_storageDisposers` to mirror the full
-     * {@link destroy} path — child mounts that registered disposers via
-     * {@link addDisposer} (audit trails, log dispose hooks, off-event
-     * callbacks, attached storage) would otherwise leak when destruction
-     * reaches the subtree via the parent's TEARDOWN cascade rather than a
-     * direct `destroy()` call (EH-2). Disposers run BEFORE structure clear
-     * so cleanups can still resolve node paths if needed.
-     */
-    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 SnapshotStorageTier}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.
-     */
-    attachSnapshotStorage(tiers: readonly SnapshotStorageTier<GraphCheckpointRecord>[], 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.attachSnapshotStorage}'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 SnapshotStorageTier<GraphCheckpointRecord>[], 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: SnapshotStorageTier<GraphCheckpointRecord>) => void;
-    }): Promise<Graph>;
-    private _annotations;
-    private readonly _traceRing;
-    /**
-     * Unified reasoning trace: write annotations or read the ring buffer.
-     *
-     * - `graph.trace("path", "annotation")` — attaches a reasoning annotation
-     *   to a node, capturing *why* an AI agent set a value. Overwrites the
-     *   current annotation (if any) and appends to the chronological ring.
-     *   Unknown paths are silently dropped (matching `observe` resilience).
-     *   No-op when `config.inspectorEnabled` is `false`.
-     * - `graph.trace("path")` — returns the current annotation for `path`,
-     *   or `undefined` if none. Precedence: most recent `trace(path, ...)`
-     *   wins; if no trace call, whatever `graph.add(node, { name: "path", annotation })`
-     *   installed; otherwise `undefined`.
-     * - `graph.trace()` — returns a chronological log of all write entries.
-     *   Returns `[]` when `config.inspectorEnabled` is `false`.
-     */
-    trace(path: string, annotation: string, opts?: {
-        actor?: Actor;
-    }): void;
-    trace(path: string): string | undefined;
-    trace(): readonly TraceEntry[];
-    /**
-     * Latest annotation attached to `path` — via {@link Graph.trace} or via
-     * {@link Graph.add}'s `{annotation}` option. Returns `undefined` if none.
-     * `describe()` surfaces this via the `annotation` field on each node entry
-     * (when present). Equivalent to `graph.trace(path)`.
-     */
-    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;
-    annotation: 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); `attachSnapshotStorage` 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 { type ObserveTheme as A, type ObserveThemeName as B, type CausalChain as C, type DescribeChangeset as D, type ExplainPathOptions as E, type ObserveTier as F, Graph as G, type ReachableOptions as H, type TraceEntry as I, diffForWAL as J, explainPath as K, graphProfile as L, type Meta as M, type NodeProfile as N, type ObserveChangeset as O, reachable as P, topologyDiff as Q, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, type GraphOptions as a, type GraphDescribeOutput as b, type CausalStep as c, type DescribeEvent as d, type DescribeFilter as e, GRAPH_META_SEGMENT as f, type GraphActorOptions as g, type GraphAttachStorageOptions as h, type GraphCheckpointRecord as i, type GraphDescribeOptions as j, type GraphDiagramDirection 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 GraphProfileOptions as s, type GraphProfileResult as t, type GraphVersionChange as u, type GraphWALDiff as v, type ObserveDetail as w, type ObserveEvent as x, type ObserveOptions as y, type ObserveResult as z };