@graphrefly/graphrefly 0.25.0 → 0.27.0

package/dist/graph/index.d.cts

@@ -1,5 +1,5 @@
-export { E as ENVELOPE_VERSION, a as EvictedSubgraphInfo, b as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, O as SIZEOF_OVERHEAD, S as SIZEOF_SYMBOL, W as WALEntry, c as createDagCborCodec, d as createDagCborZstdCodec, e as decodeEnvelope, f as encodeEnvelope, r as registerBuiltinCodecs, g as replayWAL, s as sizeof } from '../index-AMWewNDe.cjs';
-export { D as DescribeFilter, e as GRAPH_META_SEGMENT, G as Graph, f as GraphActorOptions, b as GraphAttachStorageOptions, g as GraphCheckpointRecord, h as GraphDescribeOptions, i as GraphDescribeOutput, j as GraphDiagramDirection, k as GraphDiagramOptions, l as GraphDiffChange, m as GraphDiffResult, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, r as GraphPersistSnapshot, d as GraphProfileOptions, c as GraphProfileResult, s as GraphVersionChange, t as GraphWALDiff, N as NodeProfile, O as ObserveDetail, u as ObserveEvent, v as ObserveOptions, w as ObserveResult, x as ObserveTheme, y as ObserveThemeName, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, A as diffForWAL, B as graphProfile, C as reachable } from '../graph-D-3JIQme.cjs';
-import '../node-B-f-Lu-k.cjs';
-import '../meta-DWbkoq1s.cjs';
-import '../storage-BuTdpCI1.cjs';
+export { E as ENVELOPE_VERSION, a as EvictedSubgraphInfo, b as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, O as SIZEOF_OVERHEAD, S as SIZEOF_SYMBOL, W as WALEntry, c as createDagCborCodec, d as createDagCborZstdCodec, e as decodeEnvelope, f as encodeEnvelope, r as registerBuiltinCodecs, g as replayWAL, s as sizeof, w as watchTopologyTree } from '../index-CO8uBlUh.cjs';
+export { C as CausalChain, h as CausalStep, D as DescribeFilter, E as ExplainPathOptions, i as GRAPH_META_SEGMENT, a as Graph, j as GraphActorOptions, k as GraphAttachStorageOptions, l as GraphCheckpointRecord, b as GraphDescribeOptions, c as GraphDescribeOutput, m as GraphDiagramDirection, n as GraphDiagramOptions, o as GraphDiffChange, g as GraphDiffResult, p as GraphFactoryContext, f as GraphNodeFactory, q as GraphObserveAll, r as GraphObserveOne, G as GraphOptions, s as GraphPersistSnapshot, e as GraphProfileOptions, d as GraphProfileResult, t as GraphVersionChange, u as GraphWALDiff, N as NodeProfile, O as ObserveDetail, v as ObserveEvent, w as ObserveOptions, x as ObserveResult, y as ObserveTheme, z as ObserveThemeName, R as ReachableDirection, A as ReachableOptions, S as SNAPSHOT_VERSION, T as TopologyEvent, B as TraceEntry, F as diffForWAL, H as explainPath, I as graphProfile, J as reachable } from '../graph-DNCrvZSn.cjs';
+import '../node-BmerH3kS.cjs';
+import '../meta-BxCA7rcr.cjs';
+import '../storage-DdWlZo6U.cjs';

package/dist/graph/index.d.ts

@@ -1,5 +1,5 @@
-export { E as ENVELOPE_VERSION, a as EvictedSubgraphInfo, b as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, O as SIZEOF_OVERHEAD, S as SIZEOF_SYMBOL, W as WALEntry, c as createDagCborCodec, d as createDagCborZstdCodec, e as decodeEnvelope, f as encodeEnvelope, r as registerBuiltinCodecs, g as replayWAL, s as sizeof } from '../index-CYkjxu3s.js';
-export { D as DescribeFilter, e as GRAPH_META_SEGMENT, G as Graph, f as GraphActorOptions, b as GraphAttachStorageOptions, g as GraphCheckpointRecord, h as GraphDescribeOptions, i as GraphDescribeOutput, j as GraphDiagramDirection, k as GraphDiagramOptions, l as GraphDiffChange, m as GraphDiffResult, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, r as GraphPersistSnapshot, d as GraphProfileOptions, c as GraphProfileResult, s as GraphVersionChange, t as GraphWALDiff, N as NodeProfile, O as ObserveDetail, u as ObserveEvent, v as ObserveOptions, w as ObserveResult, x as ObserveTheme, y as ObserveThemeName, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, A as diffForWAL, B as graphProfile, C as reachable } from '../graph-B6NFqv3z.js';
-import '../node-B-f-Lu-k.js';
-import '../meta-CnkLA_43.js';
-import '../storage-F2X1U1x0.js';
+export { E as ENVELOPE_VERSION, a as EvictedSubgraphInfo, b as EvictionPolicy, G as GraphCodec, J as JsonCodec, L as LazyGraphCodec, O as SIZEOF_OVERHEAD, S as SIZEOF_SYMBOL, W as WALEntry, c as createDagCborCodec, d as createDagCborZstdCodec, e as decodeEnvelope, f as encodeEnvelope, r as registerBuiltinCodecs, g as replayWAL, s as sizeof, w as watchTopologyTree } from '../index-B6D3QNSA.js';
+export { C as CausalChain, h as CausalStep, D as DescribeFilter, E as ExplainPathOptions, i as GRAPH_META_SEGMENT, a as Graph, j as GraphActorOptions, k as GraphAttachStorageOptions, l as GraphCheckpointRecord, b as GraphDescribeOptions, c as GraphDescribeOutput, m as GraphDiagramDirection, n as GraphDiagramOptions, o as GraphDiffChange, g as GraphDiffResult, p as GraphFactoryContext, f as GraphNodeFactory, q as GraphObserveAll, r as GraphObserveOne, G as GraphOptions, s as GraphPersistSnapshot, e as GraphProfileOptions, d as GraphProfileResult, t as GraphVersionChange, u as GraphWALDiff, N as NodeProfile, O as ObserveDetail, v as ObserveEvent, w as ObserveOptions, x as ObserveResult, y as ObserveTheme, z as ObserveThemeName, R as ReachableDirection, A as ReachableOptions, S as SNAPSHOT_VERSION, T as TopologyEvent, B as TraceEntry, F as diffForWAL, H as explainPath, I as graphProfile, J as reachable } from '../graph-CCwGKLCm.js';
+import '../node-BmerH3kS.js';
+import '../meta-CbznRPYJ.js';
+import '../storage-CMjUUuxn.js';

package/dist/graph/index.js

@@ -1,15 +1,19 @@
-import "../chunk-MW4VAKAO.js";
+import {
+  watchTopologyTree
+} from "../chunk-OU5CQKNW.js";
 import {
   GRAPH_META_SEGMENT,
   Graph,
   OVERHEAD,
   SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION,
   diffForWAL,
+  explainPath,
   graphProfile,
   reachable,
   sizeof
-} from "../chunk-XOFWRC73.js";
-import "../chunk-H4RVA4VE.js";
+} from "../chunk-PF7GRZMW.js";
+import "../chunk-VYPWMZ6H.js";
 import "../chunk-7TAQJHQV.js";
 import {
   ENVELOPE_VERSION,
@@ -20,7 +24,8 @@ import {
   encodeEnvelope,
   registerBuiltinCodecs,
   replayWAL
-} from "../chunk-5DJTTKX3.js";
+} from "../chunk-PHOUUNK7.js";
+import "../chunk-SX52TAR4.js";
 export {
   ENVELOPE_VERSION,
   GRAPH_META_SEGMENT,
@@ -28,15 +33,18 @@ export {
   JsonCodec,
   OVERHEAD as SIZEOF_OVERHEAD,
   SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION,
   createDagCborCodec,
   createDagCborZstdCodec,
   decodeEnvelope,
   diffForWAL,
   encodeEnvelope,
+  explainPath,
   graphProfile,
   reachable,
   registerBuiltinCodecs,
   replayWAL,
-  sizeof
+  sizeof,
+  watchTopologyTree
 };
 //# sourceMappingURL=index.js.map

package/dist/{graph-D-3JIQme.d.cts → graph-CCwGKLCm.d.ts}

@@ -1,6 +1,111 @@
-import { k as GraphReFlyConfig, a6 as VersioningLevel, N as Node, A as Actor, t as Messages, K as NodeSink } from './node-B-f-Lu-k.cjs';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-DWbkoq1s.cjs';
-import { a as StorageTier, S as StorageHandle } from './storage-BuTdpCI1.cjs';
+import { A as Actor, j as GraphReFlyConfig, a6 as VersioningLevel, N as Node, s as Messages, K as NodeSink } from './node-BmerH3kS.js';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-CbznRPYJ.js';
+import { S as StorageTier, a as StorageHandle } from './storage-CMjUUuxn.js';
+
+/**
+ * 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;
+    /** Reason annotation set via `graph.trace(path, reason)`, when present. */
+    reason?: 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. */
+    reason: "ok" | "no-such-from" | "no-such-to" | "no-path" | "max-depth-exceeded";
+    /** 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.
@@ -263,6 +368,27 @@ type GraphAttachStorageOptions = {
     /** Surfaced on tier save errors and autoRestore failures. */
     onError?: (error: unknown, tier: StorageTier) => 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 export helpers. */
 type GraphDiagramDirection = "TD" | "LR" | "BT" | "RL";
 /** Options for {@link Graph.toMermaid} / {@link Graph.toD2}. */
@@ -276,6 +402,13 @@ type GraphDiagramOptions = {
      */
     direction?: GraphDiagramDirection;
 };
+/**
+ * Snapshot format version (§3.8). Exported so the surface layer's
+ * `saveSnapshot` writes the same `format_version` as
+ * `Graph.attachStorage` — 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};
@@ -500,6 +633,20 @@ declare class Graph {
     _parent: Graph | undefined;
     private readonly _storageDisposers;
     private readonly _disposers;
+    /**
+     * @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__`).
@@ -513,6 +660,33 @@ declare class Graph {
      * @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
@@ -734,6 +908,23 @@ declare class Graph {
         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).
+     *
+     * @param from - Upstream node (the cause).
+     * @param to - Downstream node (the effect).
+     * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+     *   and `from === to`, returns the shortest cycle through other nodes
+     *   (useful for diagnosing feedback loops, COMPOSITION-GUIDE §7).
+     *   Annotations and lastMutations are collected automatically from the
+     *   live graph.
+     */
+    explain(from: string, to: string, opts?: {
+        maxDepth?: number;
+        findCycle?: boolean;
+    }): CausalChain;
     /**
      * @internal Collect all qualified paths in this graph tree matching a
      * glob pattern. Used by scoped autoCheckpoint subscription.
@@ -1125,4 +1316,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): ReachableResult;
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-export { diffForWAL as A, graphProfile as B, reachable as C, type DescribeFilter as D, Graph as G, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAttachStorageOptions as b, type GraphProfileResult as c, type GraphProfileOptions as d, GRAPH_META_SEGMENT as e, type GraphActorOptions as f, type GraphCheckpointRecord as g, type GraphDescribeOptions as h, type GraphDescribeOutput as i, type GraphDiagramDirection as j, type GraphDiagramOptions as k, type GraphDiffChange as l, type GraphDiffResult as m, type GraphFactoryContext as n, type GraphNodeFactory as o, type GraphObserveAll as p, type GraphObserveOne as q, type GraphPersistSnapshot as r, type GraphVersionChange as s, type GraphWALDiff as t, type ObserveEvent as u, type ObserveOptions as v, type ObserveResult as w, type ObserveTheme as x, type ObserveThemeName as y, type ReachableOptions as z };
+export { type ReachableOptions as A, type TraceEntry as B, type CausalChain as C, type DescribeFilter as D, type ExplainPathOptions as E, diffForWAL as F, type GraphOptions as G, explainPath as H, graphProfile as I, reachable as J, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, Graph as a, type GraphDescribeOptions as b, type GraphDescribeOutput as c, type GraphProfileResult as d, type GraphProfileOptions as e, type GraphNodeFactory as f, type GraphDiffResult as g, type CausalStep as h, GRAPH_META_SEGMENT as i, type GraphActorOptions as j, type GraphAttachStorageOptions as k, type GraphCheckpointRecord as l, type GraphDiagramDirection as m, type GraphDiagramOptions as n, type GraphDiffChange as o, type GraphFactoryContext as p, type GraphObserveAll as q, type GraphObserveOne as r, type GraphPersistSnapshot as s, type GraphVersionChange as t, type GraphWALDiff as u, type ObserveEvent as v, type ObserveOptions as w, type ObserveResult as x, type ObserveTheme as y, type ObserveThemeName as z };

package/dist/{graph-B6NFqv3z.d.ts → graph-DNCrvZSn.d.cts}

@@ -1,6 +1,111 @@
-import { k as GraphReFlyConfig, a6 as VersioningLevel, N as Node, A as Actor, t as Messages, K as NodeSink } from './node-B-f-Lu-k.js';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-CnkLA_43.js';
-import { a as StorageTier, S as StorageHandle } from './storage-F2X1U1x0.js';
+import { A as Actor, j as GraphReFlyConfig, a6 as VersioningLevel, N as Node, s as Messages, K as NodeSink } from './node-BmerH3kS.cjs';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-BxCA7rcr.cjs';
+import { S as StorageTier, a as StorageHandle } from './storage-DdWlZo6U.cjs';
+
+/**
+ * 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;
+    /** Reason annotation set via `graph.trace(path, reason)`, when present. */
+    reason?: 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. */
+    reason: "ok" | "no-such-from" | "no-such-to" | "no-path" | "max-depth-exceeded";
+    /** 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.
@@ -263,6 +368,27 @@ type GraphAttachStorageOptions = {
     /** Surfaced on tier save errors and autoRestore failures. */
     onError?: (error: unknown, tier: StorageTier) => 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 export helpers. */
 type GraphDiagramDirection = "TD" | "LR" | "BT" | "RL";
 /** Options for {@link Graph.toMermaid} / {@link Graph.toD2}. */
@@ -276,6 +402,13 @@ type GraphDiagramOptions = {
      */
     direction?: GraphDiagramDirection;
 };
+/**
+ * Snapshot format version (§3.8). Exported so the surface layer's
+ * `saveSnapshot` writes the same `format_version` as
+ * `Graph.attachStorage` — 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};
@@ -500,6 +633,20 @@ declare class Graph {
     _parent: Graph | undefined;
     private readonly _storageDisposers;
     private readonly _disposers;
+    /**
+     * @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__`).
@@ -513,6 +660,33 @@ declare class Graph {
      * @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
@@ -734,6 +908,23 @@ declare class Graph {
         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).
+     *
+     * @param from - Upstream node (the cause).
+     * @param to - Downstream node (the effect).
+     * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+     *   and `from === to`, returns the shortest cycle through other nodes
+     *   (useful for diagnosing feedback loops, COMPOSITION-GUIDE §7).
+     *   Annotations and lastMutations are collected automatically from the
+     *   live graph.
+     */
+    explain(from: string, to: string, opts?: {
+        maxDepth?: number;
+        findCycle?: boolean;
+    }): CausalChain;
     /**
      * @internal Collect all qualified paths in this graph tree matching a
      * glob pattern. Used by scoped autoCheckpoint subscription.
@@ -1125,4 +1316,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): ReachableResult;
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-export { diffForWAL as A, graphProfile as B, reachable as C, type DescribeFilter as D, Graph as G, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, type TraceEntry as T, type GraphOptions as a, type GraphAttachStorageOptions as b, type GraphProfileResult as c, type GraphProfileOptions as d, GRAPH_META_SEGMENT as e, type GraphActorOptions as f, type GraphCheckpointRecord as g, type GraphDescribeOptions as h, type GraphDescribeOutput as i, type GraphDiagramDirection as j, type GraphDiagramOptions as k, type GraphDiffChange as l, type GraphDiffResult as m, type GraphFactoryContext as n, type GraphNodeFactory as o, type GraphObserveAll as p, type GraphObserveOne as q, type GraphPersistSnapshot as r, type GraphVersionChange as s, type GraphWALDiff as t, type ObserveEvent as u, type ObserveOptions as v, type ObserveResult as w, type ObserveTheme as x, type ObserveThemeName as y, type ReachableOptions as z };
+export { type ReachableOptions as A, type TraceEntry as B, type CausalChain as C, type DescribeFilter as D, type ExplainPathOptions as E, diffForWAL as F, type GraphOptions as G, explainPath as H, graphProfile as I, reachable as J, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, Graph as a, type GraphDescribeOptions as b, type GraphDescribeOutput as c, type GraphProfileResult as d, type GraphProfileOptions as e, type GraphNodeFactory as f, type GraphDiffResult as g, type CausalStep as h, GRAPH_META_SEGMENT as i, type GraphActorOptions as j, type GraphAttachStorageOptions as k, type GraphCheckpointRecord as l, type GraphDiagramDirection as m, type GraphDiagramOptions as n, type GraphDiffChange as o, type GraphFactoryContext as p, type GraphObserveAll as q, type GraphObserveOne as r, type GraphPersistSnapshot as s, type GraphVersionChange as t, type GraphWALDiff as u, type ObserveEvent as v, type ObserveOptions as w, type ObserveResult as x, type ObserveTheme as y, type ObserveThemeName as z };

package/dist/index-3lsddbbS.d.ts

@@ -0,0 +1,86 @@
+import { N as Node } from './node-BmerH3kS.js';
+
+/**
+ * Options for creating an atom.
+ *
+ * @category compat
+ */
+interface AtomOptions {
+    /** Optional identifier for the underlying node. */
+    name?: string;
+    /** Optional companion meta nodes. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * A read-only Jotai-compatible atom.
+ *
+ * @category compat
+ */
+interface ReadableAtom<T> {
+    /** Returns the current cached value. */
+    get(): T;
+    /** Subscribes to value changes. Returns an unsubscribe function. */
+    subscribe(callback: (value: T) => void): () => void;
+    /** Access to companion meta nodes. */
+    readonly meta: Record<string, Node>;
+    /** @internal The underlying GraphReFly node. */
+    _node: Node<T>;
+}
+/**
+ * A writable Jotai-compatible atom.
+ *
+ * @category compat
+ */
+interface WritableAtom<T> extends ReadableAtom<T> {
+    /** Sets a new value. */
+    set(value: T): void;
+    /** Updates the value using a transformation function. */
+    update(fn: (current: T) => T): void;
+}
+/** Function type for reading other atoms inside a derived atom. */
+type GetFn = <V>(a: ReadableAtom<V>) => V;
+/** Function type for writing to other atoms inside a writable derived atom. */
+type SetFn = <V>(a: WritableAtom<V>, value: V) => void;
+/** Function that computes the atom's value. */
+type ReadFn<T> = (get: GetFn) => T;
+/** Function that handles writes to the atom. */
+type WriteFn<T> = (get: GetFn, set: SetFn, value: T) => void;
+/**
+ * Creates a Jotai-compatible atom built on GraphReFly primitives.
+ *
+ * Supports three overloads:
+ * 1. `atom(initial)` — Writable primitive atom (wraps `state()`).
+ * 2. `atom(read)` — Read-only derived atom (wraps `dynamicNode()`).
+ * 3. `atom(read, write)` — Writable derived atom.
+ *
+ * @param initialOrRead - Initial value or a read function.
+ * @param writeOrOptions - Write function or options object.
+ * @param options - Optional configuration.
+ * @returns WritableAtom or ReadableAtom.
+ *
+ * @example
+ * ```ts
+ * const count = atom(0);
+ * count.set(1);
+ * const doubled = atom((get) => get(count)! * 2);
+ * ```
+ *
+ * @category compat
+ */
+declare function atom<T>(initial: T, options?: AtomOptions): WritableAtom<T>;
+declare function atom<T>(read: ReadFn<T>, options?: AtomOptions): ReadableAtom<T>;
+declare function atom<T>(read: ReadFn<T>, write: WriteFn<T>, options?: AtomOptions): WritableAtom<T>;
+
+type index_AtomOptions = AtomOptions;
+type index_GetFn = GetFn;
+type index_ReadFn<T> = ReadFn<T>;
+type index_ReadableAtom<T> = ReadableAtom<T>;
+type index_SetFn = SetFn;
+type index_WritableAtom<T> = WritableAtom<T>;
+type index_WriteFn<T> = WriteFn<T>;
+declare const index_atom: typeof atom;
+declare namespace index {
+  export { type index_AtomOptions as AtomOptions, type index_GetFn as GetFn, type index_ReadFn as ReadFn, type index_ReadableAtom as ReadableAtom, type index_SetFn as SetFn, type index_WritableAtom as WritableAtom, type index_WriteFn as WriteFn, index_atom as atom };
+}
+
+export { type AtomOptions as A, type GetFn as G, type ReadFn as R, type SetFn as S, type WritableAtom as W, type ReadableAtom as a, type WriteFn as b, atom as c, index as i };