@graphrefly/graphrefly 0.1.0

package/dist/graph/index.d.cts

@@ -0,0 +1,3 @@
+export { D as DeltaCheckpoint, E as EvictedSubgraphInfo, a as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, W as WALEntry, c as createDagCborCodec, b as createDagCborZstdCodec, n as negotiateCodec, r as replayWAL } from '../index-BvhgZRHK.cjs';
+export { A as AutoCheckpointAdapter, D as DescribeFilter, d as GRAPH_META_SEGMENT, G as Graph, e as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, f as GraphCheckpointRecord, g as GraphDescribeOutput, h as GraphDiagramDirection, i as GraphDiagramOptions, j as GraphDiffChange, k as GraphDiffResult, l as GraphDumpOptions, m as GraphFactoryContext, n as GraphNodeFactory, o as GraphObserveAll, p as GraphObserveOne, a as GraphOptions, q as GraphPersistSnapshot, r as GraphSpyHandle, s as GraphSpyOptions, t as GraphSpyTheme, u as GraphSpyThemeName, O as ObserveEvent, v as ObserveOptions, w as ObserveResult, R as ReachableDirection, x as ReachableOptions, T as TraceEntry, y as reachable } from '../graph-CL_ZDAj9.cjs';
+import '../meta-BsF6Sag9.cjs';

package/dist/graph/index.d.ts

@@ -0,0 +1,3 @@
+export { D as DeltaCheckpoint, E as EvictedSubgraphInfo, a as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, W as WALEntry, c as createDagCborCodec, b as createDagCborZstdCodec, n as negotiateCodec, r as replayWAL } from '../index-BtK55IE2.js';
+export { A as AutoCheckpointAdapter, D as DescribeFilter, d as GRAPH_META_SEGMENT, G as Graph, e as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, f as GraphCheckpointRecord, g as GraphDescribeOutput, h as GraphDiagramDirection, i as GraphDiagramOptions, j as GraphDiffChange, k as GraphDiffResult, l as GraphDumpOptions, m as GraphFactoryContext, n as GraphNodeFactory, o as GraphObserveAll, p as GraphObserveOne, a as GraphOptions, q as GraphPersistSnapshot, r as GraphSpyHandle, s as GraphSpyOptions, t as GraphSpyTheme, u as GraphSpyThemeName, O as ObserveEvent, v as ObserveOptions, w as ObserveResult, R as ReachableDirection, x as ReachableOptions, T as TraceEntry, y as reachable } from '../graph-D18qmsNm.js';
+import '../meta-BsF6Sag9.js';

package/dist/graph/index.js

@@ -0,0 +1,25 @@
+import {
+  JsonCodec,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  negotiateCodec,
+  replayWAL
+} from "../chunk-HP7OKEOE.js";
+import {
+  GRAPH_META_SEGMENT,
+  Graph,
+  reachable
+} from "../chunk-6W5SGIGB.js";
+import "../chunk-O3PI7W45.js";
+import "../chunk-5X3LAO3B.js";
+export {
+  GRAPH_META_SEGMENT,
+  Graph,
+  JsonCodec,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  negotiateCodec,
+  reachable,
+  replayWAL
+};
+//# sourceMappingURL=index.js.map

package/dist/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/graph-CL_ZDAj9.d.cts

@@ -0,0 +1,605 @@
+import { f as DescribeNodeOutput, N as Node, u as VersioningLevel, A as Actor, i as Messages, l as NodeSink } from './meta-BsF6Sag9.cjs';
+
+/**
+ * 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} (reserved for future hooks). */
+type GraphOptions = Record<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;
+};
+/** 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[];
+};
+/**
+ * Persisted graph snapshot: {@link GraphDescribeOutput} plus optional format version
+ * ({@link Graph.snapshot}, {@link Graph.restore}, {@link Graph.fromSnapshot}, {@link Graph.toJSON},
+ * {@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;
+type AutoCheckpointAdapter = {
+    save(data: unknown): void;
+};
+type GraphCheckpointRecord = {
+    mode: "full";
+    snapshot: GraphPersistSnapshot;
+    seq: number;
+} | {
+    mode: "diff";
+    diff: GraphDiffResult;
+    snapshot: GraphPersistSnapshot;
+    seq: number;
+};
+type GraphAutoCheckpointOptions = {
+    debounceMs?: number;
+    compactEvery?: number;
+    filter?: (name: string, described: DescribeNodeOutput) => boolean;
+    onError?: (error: unknown) => void;
+};
+type GraphAutoCheckpointHandle = {
+    dispose(): 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;
+};
+/** {@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;
+};
+/** 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;
+};
+/** Accumulated observation result (structured mode). */
+type ObserveResult<T = unknown> = {
+    /** 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;
+    /** All events in order. */
+    readonly events: ObserveEvent[];
+    /** True if COMPLETE received without prior ERROR. */
+    readonly completedCleanly: boolean;
+    /** True if ERROR received. */
+    readonly errored: boolean;
+    /** Stop observing. */
+    dispose(): void;
+};
+/** A single event in the structured observation log. */
+type ObserveEvent = {
+    type: "data" | "dirty" | "resolved" | "complete" | "error" | "derived";
+    path?: string;
+    data?: unknown;
+    timestamp_ns?: number;
+    in_batch?: boolean;
+    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;
+    };
+    dep_values?: unknown[];
+};
+/** Built-in color presets for {@link Graph.spy}. */
+type GraphSpyThemeName = "none" | "ansi";
+/** ANSI/style overrides for {@link Graph.spy} event rendering. */
+type GraphSpyTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", string>>;
+/** Options for {@link Graph.spy}. */
+type GraphSpyOptions = ObserveOptions & {
+    /** Observe one path; omit for graph-wide mode. */
+    path?: string;
+    /** Keep only these event types in spy output. */
+    includeTypes?: ObserveEvent["type"][];
+    /** Exclude these event types from spy output. */
+    excludeTypes?: ObserveEvent["type"][];
+    /** Built-in color preset (`ansi` default) or explicit color tokens. */
+    theme?: GraphSpyThemeName | GraphSpyTheme;
+    /** One-line `pretty` output (default) or JSON-per-event. */
+    format?: "pretty" | "json";
+    /** Optional sink for rendered lines (`console.log` by default). */
+    logger?: (line: string, event: ObserveEvent) => void;
+};
+/** Handle returned by {@link Graph.spy}. */
+type GraphSpyHandle = {
+    readonly result: ObserveResult;
+    dispose(): void;
+};
+/** Options for {@link Graph.dumpGraph}. */
+type GraphDumpOptions = {
+    actor?: Actor;
+    filter?: DescribeFilter;
+    format?: "pretty" | "json";
+    indent?: number;
+    includeEdges?: boolean;
+    includeSubgraphs?: boolean;
+    logger?: (text: string) => void;
+};
+/**
+ * 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 {
+    private static readonly _factories;
+    readonly name: string;
+    readonly opts: Readonly<GraphOptions>;
+    /** @internal — exposed for {@link teardownMountedGraph} and cross-graph helpers. */
+    readonly _nodes: Map<string, Node<unknown>>;
+    private readonly _edges;
+    /** @internal — exposed for {@link teardownMountedGraph}. */
+    readonly _mounts: Map<string, Graph>;
+    private readonly _autoCheckpointDisposers;
+    private _defaultVersioningLevel;
+    static registerFactory(pattern: string, factory: GraphNodeFactory): void;
+    static unregisterFactory(pattern: string): void;
+    /**
+     * @param name - Non-empty graph id (must not contain `::`).
+     * @param opts - Reserved for future hooks; currently unused.
+     */
+    constructor(name: string, opts?: GraphOptions);
+    private static _factoryForPath;
+    private static _ownerForPath;
+    /**
+     * Graphs reachable from this instance via nested {@link Graph.mount} (includes `this`).
+     */
+    private _graphsReachableViaMounts;
+    /**
+     * Resolve an endpoint: returns `[owningGraph, localName, node]`.
+     * Accepts both local names and `::` qualified paths.
+     */
+    private _resolveEndpoint;
+    private _resolveEndpointFromSegments;
+    /**
+     * Registers a node under a local name. Fails if the name is already used,
+     * reserved by a mount, or the same node instance is already registered.
+     *
+     * @param name - Local key (no `::`).
+     * @param node - Node instance to own.
+     */
+    add(name: string, node: Node): void;
+    /**
+     * Set a default versioning level for all nodes added to this graph (roadmap §6.0).
+     *
+     * Nodes already registered are retroactively upgraded. Nodes added later via
+     * {@link add} will inherit this level unless they already have versioning.
+     *
+     * **Scope:** Does not propagate to mounted subgraphs. Call `setVersioning`
+     * on each child graph separately if needed.
+     *
+     * @param level - `0` for V0, `1` for V1, or `undefined` to clear.
+     */
+    setVersioning(level: VersioningLevel | undefined): void;
+    /**
+     * Unregisters a node or unmounts a subgraph, drops incident edges, and sends
+     * `[[TEARDOWN]]` to the removed node or recursively through the mounted subtree (§3.2).
+     *
+     * @param name - Local mount or node name.
+     */
+    remove(name: string): void;
+    /**
+     * 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;
+    /**
+     * Record a wire from `fromPath` → `toPath` (§3.3). Accepts local names or
+     * `::` qualified paths. The target must be a {@link NodeImpl} whose `_deps`
+     * includes the source node (same reference). Idempotent.
+     *
+     * Same-owner edges are stored on the owning child graph; cross-subgraph edges
+     * are stored on this (parent) graph's registry.
+     *
+     * @param fromPath - Source endpoint (local or qualified).
+     * @param toPath - Target endpoint whose deps already include the source node.
+     */
+    connect(fromPath: string, toPath: string): void;
+    /**
+     * Remove a registered edge (§3.3). Accepts local names or `::` qualified paths.
+     *
+     * **Registry-only (§C resolved):** This drops the edge from the graph's edge
+     * registry only. It does **not** mutate the target node's constructor-time
+     * dependency list, bitmasks, or upstream subscriptions. Message flow follows
+     * constructor-time deps, not the edge registry. For runtime dep rewiring, use
+     * {@link dynamicNode}.
+     *
+     * @param fromPath - Registered edge tail.
+     * @param toPath - Registered edge head.
+     */
+    disconnect(fromPath: string, toPath: string): void;
+    /**
+     * Returns registered `[from, to]` edge pairs (read-only snapshot).
+     *
+     * @returns Edge pairs recorded on this graph instance’s local `_edges` set.
+     */
+    edges(): 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.
+     */
+    mount(name: string, child: Graph): void;
+    /**
+     * 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"`).
+     *
+     * @param path - Qualified `::` path or local name.
+     * @returns The resolved `Node`.
+     */
+    resolve(path: string): Node;
+    private _resolveFromSegments;
+    /**
+     * Resolve `::__meta__::key` segments from a registered primary node (possibly chained).
+     */
+    private _resolveMetaChainFromNode;
+    private _resolveMetaEndpointKeys;
+    /**
+     * 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).
+     *
+     * Companion `meta` nodes receive the same batch for control-plane types (e.g.
+     * PAUSE) that the primary does not forward. **TEARDOWN-only** batches skip the
+     * extra meta pass — the primary’s `down()` already cascades TEARDOWN to meta.
+     *
+     * @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).
+     *
+     * @param options - Optional `actor` for guard-scoped visibility and/or `filter` for selective output.
+     * @returns JSON-shaped describe payload for this graph tree.
+     *
+     * @example
+     * ```ts
+     * graph.describe()                                         // full snapshot
+     * graph.describe({ actor: llm })                           // guard-scoped
+     * graph.describe({ filter: { status: "errored" } })        // only errored nodes
+     * graph.describe({ filter: (n) => n.type === "state" })    // predicate filter
+     * ```
+     */
+    describe(options?: {
+        actor?: Actor;
+        filter?: DescribeFilter;
+    }): GraphDescribeOutput;
+    private _collectSubgraphs;
+    private _collectAllEdges;
+    private _qualifyEdgeEndpoint;
+    private _collectObserveTargets;
+    private _appendMetaObserveTargets;
+    /**
+     * Live message stream from one node (or meta path), or from the whole graph (§3.6).
+     *
+     * Overloads: `(path, options?)` for one node; `(options?)` for all nodes. Whole-graph mode
+     * subscribes in **sorted path order** (code-point order). With structured options
+     * (`structured`, `timeline`, `causal`, `derived`), returns an {@link ObserveResult}.
+     * Inspector-gated extras (`causal` / `derived`) require {@link Graph.inspectorEnabled}.
+     *
+     * @param pathOrOpts - Qualified `path` string, or omit and pass only `options` for graph-wide observation.
+     * @param options - Optional `actor`, `structured`, `causal`, `timeline` (inspector-gated).
+     * @returns `GraphObserveOne`, `GraphObserveAll`, or `ObserveResult` depending on overload/options.
+     */
+    observe(path: string, options?: ObserveOptions & {
+        structured?: true;
+        timeline?: true;
+        causal?: true;
+        derived?: true;
+    }): ObserveResult;
+    observe(path: string, options?: ObserveOptions): GraphObserveOne;
+    observe(options: ObserveOptions & {
+        structured?: true;
+        timeline?: true;
+        causal?: true;
+        derived?: true;
+    }): ObserveResult;
+    observe(options?: ObserveOptions): GraphObserveAll;
+    private _createObserveResult;
+    private _createObserveResultForAll;
+    /**
+     * Convenience live debugger over {@link Graph.observe}. Logs protocol events as they flow.
+     *
+     * Supports one-node (`path`) and graph-wide modes, event filtering, and JSON/pretty rendering.
+     * Color themes are built in (`ansi` / `none`) to avoid external dependencies.
+     *
+     * @param options - Spy configuration.
+     * @returns Disposable handle plus a structured observation accumulator.
+     */
+    spy(options?: GraphSpyOptions): GraphSpyHandle;
+    /**
+     * CLI/debug-friendly graph dump built on {@link Graph.describe}.
+     *
+     * @param options - Optional actor/filter/format toggles.
+     * @returns Rendered graph text.
+     */
+    dumpGraph(options?: GraphDumpOptions): string;
+    /**
+     * Sends `[[TEARDOWN]]` to all nodes, then 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.
+     *
+     * @returns Persistable snapshot with sorted keys.
+     */
+    snapshot(): GraphPersistSnapshot;
+    /**
+     * Apply persisted values onto an existing graph whose topology matches the snapshot
+     * (§3.8). Only {@link DescribeNodeOutput.type} `state` and `producer` entries with a
+     * `value` field are written; `derived` / `operator` / `effect` are skipped so deps
+     * drive recomputation. 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[];
+    }): 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 build - Optional callback to construct topology before values are applied.
+     * @returns Hydrated `Graph` instance.
+     */
+    static fromSnapshot(data: GraphPersistSnapshot, build?: (g: Graph) => void): Graph;
+    /**
+     * Plain snapshot with **recursively sorted object keys** for deterministic serialization (§3.8).
+     *
+     * @remarks
+     * ECMAScript `JSON.stringify(graph)` invokes this method; it must return a plain object, not an
+     * already-stringified JSON string (otherwise the graph would be double-encoded).
+     * For a single UTF-8 string with a trailing newline (convenient for git), use {@link Graph.toJSONString}.
+     *
+     * @returns Same object as {@link Graph.snapshot}.
+     */
+    toJSON(): GraphPersistSnapshot;
+    /**
+     * Deterministic JSON **text**: `JSON.stringify` of {@link Graph.toJSON} plus a trailing newline (§3.8).
+     *
+     * @returns Stable string suitable for diffs.
+     */
+    toJSONString(): string;
+    /**
+     * Debounced persistence wired to graph-wide observe stream (spec §3.8 auto-checkpoint).
+     *
+     * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 2 messages
+     * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1 control waves.
+     */
+    autoCheckpoint(adapter: AutoCheckpointAdapter, options?: GraphAutoCheckpointOptions): GraphAutoCheckpointHandle;
+    /**
+     * Export the current graph topology as Mermaid flowchart text.
+     *
+     * Renders qualified node paths and registered edges from {@link Graph.describe}.
+     *
+     * @param options - Optional diagram direction (`LR` by default).
+     * @returns Mermaid flowchart source.
+     */
+    toMermaid(options?: GraphDiagramOptions): string;
+    /**
+     * Export the current graph topology as D2 diagram text.
+     *
+     * Renders qualified node paths, constructor deps, and registered edges from {@link Graph.describe}.
+     *
+     * @param options - Optional diagram direction (`LR` by default).
+     * @returns D2 source text.
+     */
+    toD2(options?: GraphDiagramOptions): string;
+    /**
+     * When `false`, structured observation options (`causal`, `timeline`),
+     * `annotate()`, and `traceLog()` are no-ops. Raw `observe()` always works.
+     *
+     * Default: `true` outside production (`process.env.NODE_ENV !== "production"`).
+     */
+    static inspectorEnabled: boolean;
+    private _annotations;
+    private _traceRing;
+    /**
+     * Attaches a reasoning annotation to a node — captures *why* an AI agent set a value.
+     *
+     * No-op when {@link Graph.inspectorEnabled} is `false`.
+     *
+     * @param path - Qualified node path.
+     * @param reason - Free-text note stored in the trace ring buffer.
+     */
+    annotate(path: string, reason: string): void;
+    /**
+     * Returns a chronological log of all reasoning annotations (ring buffer).
+     *
+     * @returns `[]` when {@link Graph.inspectorEnabled} is `false`.
+     */
+    traceLog(): readonly TraceEntry[];
+    /**
+     * 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;
+};
+/** Result of {@link Graph.diff}. */
+type GraphDiffResult = {
+    nodesAdded: string[];
+    nodesRemoved: string[];
+    nodesChanged: GraphDiffChange[];
+    edgesAdded: Array<{
+        from: string;
+        to: string;
+    }>;
+    edgesRemoved: Array<{
+        from: string;
+        to: string;
+    }>;
+    subgraphsAdded: string[];
+    subgraphsRemoved: string[];
+};
+/** A single field change within a diff. */
+type GraphDiffChange = {
+    path: string;
+    field: string;
+    from: unknown;
+    to: unknown;
+};
+/** 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;
+};
+/**
+ * Reachability query over a {@link Graph.describe} snapshot.
+ *
+ * Traversal combines dependency links (`deps`) and explicit graph edges (`edges`):
+ * - `upstream`: follows `deps` plus incoming edges.
+ * - `downstream`: follows reverse-`deps` plus outgoing edges.
+ *
+ * @param described - `graph.describe()` output to traverse.
+ * @param from - Start path (qualified node path).
+ * @param direction - Traversal direction.
+ * @param options - Optional max depth bound.
+ * @returns Sorted list of reachable paths (excluding `from`).
+ *
+ * @example
+ * ```ts
+ * import { Graph, reachable } from "@graphrefly/graphrefly-ts";
+ *
+ * const g = new Graph("app");
+ * const a = g.register("a");
+ * const b = g.register("b", [a]);
+ * const described = g.describe();
+ *
+ * reachable(described, "app.a", "downstream"); // ["app.b"]
+ * reachable(described, "app.b", "upstream");   // ["app.a"]
+ * ```
+ */
+declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
+
+export { type AutoCheckpointAdapter as A, type DescribeFilter as D, Graph as G, type ObserveEvent as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAutoCheckpointHandle as b, type GraphAutoCheckpointOptions as c, GRAPH_META_SEGMENT as d, type GraphActorOptions as e, type GraphCheckpointRecord as f, type GraphDescribeOutput as g, type GraphDiagramDirection as h, type GraphDiagramOptions as i, type GraphDiffChange as j, type GraphDiffResult as k, type GraphDumpOptions as l, type GraphFactoryContext as m, type GraphNodeFactory as n, type GraphObserveAll as o, type GraphObserveOne as p, type GraphPersistSnapshot as q, type GraphSpyHandle as r, type GraphSpyOptions as s, type GraphSpyTheme as t, type GraphSpyThemeName as u, type ObserveOptions as v, type ObserveResult as w, type ReachableOptions as x, reachable as y };