@graphrefly/graphrefly 0.38.0 → 0.40.0

package/dist/{graph-BjW1taJl.d.ts → graph-BkIkog4h.d.ts}

@@ -1,5 +1,5 @@
-import { A as Actor, p as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-fSc-hCv8.js';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-BYqlATmg.js';
+import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-BYInONRr.js';
+import { D as DescribeNodeOutput, a as DescribeDetail, b as DescribeField } from './meta-D8OyedKp.js';
 import { StorageHandle } from './extra/storage-core.js';
 import { SnapshotStorageTier } from './extra/storage-tiers.js';
 
@@ -143,8 +143,10 @@ interface CausalChain {
     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";
+    /** 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). */
@@ -400,51 +402,11 @@ type GraphDescribeOptions = {
      * Dotted paths like `"meta.label"` select specific meta keys.
      */
     fields?: DescribeField[];
-    /**
-     * Output format.
-     * - `undefined` / omitted — return the full {@link GraphDescribeOutput} object.
-     * - `"spec"` — GraphSpec input format (object; no status/value, deps as edges).
-     * - `"json"` — stable JSON **text** with sorted keys.
-     * - `"pretty"` — human-readable plaintext (optionally colorized; see
-     *   `colorize` / `indent` / `logger` / `includeEdges` / `includeSubgraphs`).
-     * - `"mermaid"` — Mermaid flowchart text.
-     * - `"mermaid-url"` — `https://mermaid.live/edit#base64:…` deep link (one
-     *   clickable URL, opens the `"mermaid"` source in the mermaid.live editor).
-     *   No network calls — the payload is encoded into the URL fragment.
-     * - `"d2"` — D2 diagram text.
-     * - `"ascii"` — stdout-native DAG flowchart rendered with Unicode
-     *   box-drawing glyphs (or `asciiCharset: "ascii"` for pure ASCII).
-     *   Graph-size independent: proper Sugiyama layout handles wide + deep
-     *   DAGs. Supports `direction: "LR" | "TD"`.
-     */
-    format?: "spec" | "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
-    /** Pretty/diagram render: direction for diagram formats (default `LR`). */
-    direction?: GraphDiagramDirection;
-    /** Pretty/JSON render: indent (default 2 for JSON, ignored for pretty). */
-    indent?: number;
-    /** Pretty/ASCII render: optional logger hook; fires with the rendered text before return. */
-    logger?: (text: string) => void;
-    /** Pretty render: include an Edges section (default `true`). */
-    includeEdges?: boolean;
-    /** Pretty render: include a Subgraphs section (default `true`). */
-    includeSubgraphs?: boolean;
-    /**
-     * ASCII render: per-box label cell cap; longer labels are truncated with `…`.
-     * Default `24`. Applies only to `format: "ascii"`.
-     */
-    maxLabelWidth?: number;
-    /**
-     * ASCII render: Unicode box-drawing glyphs (`"unicode"`, default) or a
-     * plain ASCII fallback (`"ascii"`, uses `-|+<>v`). Applies only to
-     * `format: "ascii"`.
-     */
-    asciiCharset?: "unicode" | "ascii";
     /**
      * Reactive describe (D2):
      * - `true` — return `{ node, dispose }` where `node` emits a fresh
-     *   `GraphDescribeOutput` (or format string, if `format` is set) every time
-     *   the graph state settles. Same coalescing as {@link Graph.explain} with
-     *   `{ reactive: true }`.
+     *   `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
@@ -572,19 +534,13 @@ type TopologyEvent = {
     nodeKind: "node" | "mount";
     audit: GraphRemoveAudit;
 };
-/** Direction options for diagram export helpers. */
+/**
+ * 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";
-/** 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;
-};
 /**
  * Snapshot format version (§3.8). Exported so the surface layer's
  * `saveSnapshot` writes the same `format_version` as
@@ -592,19 +548,6 @@ type GraphDiagramOptions = {
  * drift between auto-checkpoint and one-shot persistence paths.
  */
 declare const SNAPSHOT_VERSION = 1;
-/**
- * Encode a mermaid source string to a `https://mermaid.live/edit#base64:…`
- * deep link. Round-trip with the mermaid.live editor's `/edit#base64:`
- * share format — payload is `base64url(JSON({code, mermaid: {theme}, ...}))`.
- *
- * Exported so callers that already have rendered mermaid text (e.g. from
- * `describe({ format: "mermaid" })`) can upgrade to a live-editor URL
- * without re-rendering. Pairs with `describe({ format: "mermaid-url" })`.
- */
-declare function mermaidLiveUrl(mermaidSrc: string, opts?: {
-    theme?: "default" | "dark" | "forest" | "neutral" | "base";
-    autoSync?: boolean;
-}): string;
 /**
  * Option shapes that trigger structured-mode dispatch in {@link Graph.observe}.
  * Presence of any of these fields (truthy) → returns {@link ObserveResult};
@@ -1174,36 +1117,53 @@ declare class Graph {
     /**
      * Static structure snapshot: qualified node keys, edges, mount names (GRAPHREFLY-SPEC §3.6, Appendix B).
      *
-     * `format` controls the return type:
-     * - omitted or `"spec"` → {@link GraphDescribeOutput} object.
-     * - `"json"` / `"pretty"` / `"mermaid"` / `"d2"` → rendered string.
+     * 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, or `format` to render.
+     * @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({ format: "pretty" })                     // human-readable text
-     * graph.describe({ format: "mermaid" })                    // Mermaid flowchart
-     * graph.describe({ format: "d2", direction: "TD" })        // D2 top-down
-     * graph.describe({ format: "ascii" })                      // stdout DAG flowchart
+     * graph.describe({ detail: "spec" })                       // GraphSpec projection
+     * graph.describe({ reactive: true })                       // live snapshot Node
      * ```
      */
-    describe(options: GraphDescribeOptions & {
-        reactive: true;
-        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
-    }): ReactiveDescribeHandle<string>;
     describe(options: GraphDescribeOptions & {
         reactive: "diff";
     }): ReactiveDescribeHandle<DescribeChangeset>;
     describe(options: GraphDescribeOptions & {
         reactive: true;
     }): ReactiveDescribeHandle<GraphDescribeOutput>;
-    describe(options: GraphDescribeOptions & {
-        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
-    }): string;
     describe(options?: GraphDescribeOptions): GraphDescribeOutput;
     private _collectSubgraphs;
     /**
@@ -1230,28 +1190,44 @@ declare class Graph {
      *
      * Same question, two answers:
      * - **Static (default)** — `explain(from, to, opts?)` returns a single
-     *   {@link CausalChain} snapshot of the graph at call time.
+     *   {@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, so
-     *   the chain stays live. Replaces the former `reactiveExplainPath`.
+     *   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 (the cause).
-     * @param to - Downstream node (the effect).
-     * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+     * @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, to: string, opts?: {
-        maxDepth?: number;
-        findCycle?: boolean;
+    explain(from: string | Node<string>, to: string | Node<string>, opts?: {
+        maxDepth?: number | Node<number>;
+        findCycle?: boolean | Node<boolean>;
     }): CausalChain;
-    explain(from: string, to: string, opts: {
+    explain(from: string | Node<string>, to: string | Node<string>, opts: {
         reactive: true;
-        maxDepth?: number;
-        findCycle?: boolean;
+        maxDepth?: number | Node<number>;
+        findCycle?: boolean | Node<boolean>;
         name?: string;
     }): {
         node: Node<CausalChain>;
@@ -1689,4 +1665,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): 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 DescribeFilter as D, type ExplainPathOptions as E, type ReachableOptions as F, Graph as G, type TraceEntry as H, diffForWAL as I, explainPath as J, graphProfile as K, mermaidLiveUrl as L, type Meta as M, type NodeProfile as N, type ObserveDetail 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 GraphPersistSnapshot as b, type GraphDescribeOptions as c, type GraphDescribeOutput as d, type CausalStep as e, type DescribeChangeset as f, type DescribeEvent as g, GRAPH_META_SEGMENT as h, type GraphActorOptions as i, type GraphAttachStorageOptions as j, type GraphCheckpointRecord as k, type GraphDiagramDirection as l, type GraphDiagramOptions as m, type GraphDiffChange as n, type GraphDiffResult as o, type GraphFactoryContext as p, type GraphNodeFactory as q, type GraphObserveAll as r, type GraphObserveOne as s, type GraphProfileOptions as t, type GraphProfileResult as u, type GraphVersionChange as v, type GraphWALDiff as w, type ObserveEvent as x, type ObserveOptions as y, type ObserveResult as z };
+export { type ObserveTheme as A, type ObserveThemeName as B, type CausalChain as C, type DescribeFilter 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 GraphPersistSnapshot as c, type GraphDescribeOptions as d, type CausalStep as e, type DescribeChangeset as f, type DescribeEvent as g, GRAPH_META_SEGMENT as h, type GraphActorOptions as i, type GraphAttachStorageOptions as j, type GraphCheckpointRecord as k, type GraphDiagramDirection as l, type GraphDiffChange as m, type GraphDiffResult as n, type GraphFactoryContext as o, type GraphNodeFactory as p, type GraphObserveAll as q, type GraphObserveOne 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 };

package/dist/{graph-CHsVwf9S.d.cts → graph-E6likq7w.d.cts}

@@ -1,5 +1,5 @@
-import { A as Actor, p as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-fSc-hCv8.cjs';
-import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-DreaEM_a.cjs';
+import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, N as Node, M as Messages, K as NodeSink } from './node-BYInONRr.cjs';
+import { D as DescribeNodeOutput, a as DescribeDetail, b as DescribeField } from './meta-Ct9nqQS5.cjs';
 import { StorageHandle } from './extra/storage-core.cjs';
 import { SnapshotStorageTier } from './extra/storage-tiers.cjs';
 
@@ -143,8 +143,10 @@ interface CausalChain {
     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";
+    /** 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). */
@@ -400,51 +402,11 @@ type GraphDescribeOptions = {
      * Dotted paths like `"meta.label"` select specific meta keys.
      */
     fields?: DescribeField[];
-    /**
-     * Output format.
-     * - `undefined` / omitted — return the full {@link GraphDescribeOutput} object.
-     * - `"spec"` — GraphSpec input format (object; no status/value, deps as edges).
-     * - `"json"` — stable JSON **text** with sorted keys.
-     * - `"pretty"` — human-readable plaintext (optionally colorized; see
-     *   `colorize` / `indent` / `logger` / `includeEdges` / `includeSubgraphs`).
-     * - `"mermaid"` — Mermaid flowchart text.
-     * - `"mermaid-url"` — `https://mermaid.live/edit#base64:…` deep link (one
-     *   clickable URL, opens the `"mermaid"` source in the mermaid.live editor).
-     *   No network calls — the payload is encoded into the URL fragment.
-     * - `"d2"` — D2 diagram text.
-     * - `"ascii"` — stdout-native DAG flowchart rendered with Unicode
-     *   box-drawing glyphs (or `asciiCharset: "ascii"` for pure ASCII).
-     *   Graph-size independent: proper Sugiyama layout handles wide + deep
-     *   DAGs. Supports `direction: "LR" | "TD"`.
-     */
-    format?: "spec" | "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
-    /** Pretty/diagram render: direction for diagram formats (default `LR`). */
-    direction?: GraphDiagramDirection;
-    /** Pretty/JSON render: indent (default 2 for JSON, ignored for pretty). */
-    indent?: number;
-    /** Pretty/ASCII render: optional logger hook; fires with the rendered text before return. */
-    logger?: (text: string) => void;
-    /** Pretty render: include an Edges section (default `true`). */
-    includeEdges?: boolean;
-    /** Pretty render: include a Subgraphs section (default `true`). */
-    includeSubgraphs?: boolean;
-    /**
-     * ASCII render: per-box label cell cap; longer labels are truncated with `…`.
-     * Default `24`. Applies only to `format: "ascii"`.
-     */
-    maxLabelWidth?: number;
-    /**
-     * ASCII render: Unicode box-drawing glyphs (`"unicode"`, default) or a
-     * plain ASCII fallback (`"ascii"`, uses `-|+<>v`). Applies only to
-     * `format: "ascii"`.
-     */
-    asciiCharset?: "unicode" | "ascii";
     /**
      * Reactive describe (D2):
      * - `true` — return `{ node, dispose }` where `node` emits a fresh
-     *   `GraphDescribeOutput` (or format string, if `format` is set) every time
-     *   the graph state settles. Same coalescing as {@link Graph.explain} with
-     *   `{ reactive: true }`.
+     *   `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
@@ -572,19 +534,13 @@ type TopologyEvent = {
     nodeKind: "node" | "mount";
     audit: GraphRemoveAudit;
 };
-/** Direction options for diagram export helpers. */
+/**
+ * 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";
-/** 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;
-};
 /**
  * Snapshot format version (§3.8). Exported so the surface layer's
  * `saveSnapshot` writes the same `format_version` as
@@ -592,19 +548,6 @@ type GraphDiagramOptions = {
  * drift between auto-checkpoint and one-shot persistence paths.
  */
 declare const SNAPSHOT_VERSION = 1;
-/**
- * Encode a mermaid source string to a `https://mermaid.live/edit#base64:…`
- * deep link. Round-trip with the mermaid.live editor's `/edit#base64:`
- * share format — payload is `base64url(JSON({code, mermaid: {theme}, ...}))`.
- *
- * Exported so callers that already have rendered mermaid text (e.g. from
- * `describe({ format: "mermaid" })`) can upgrade to a live-editor URL
- * without re-rendering. Pairs with `describe({ format: "mermaid-url" })`.
- */
-declare function mermaidLiveUrl(mermaidSrc: string, opts?: {
-    theme?: "default" | "dark" | "forest" | "neutral" | "base";
-    autoSync?: boolean;
-}): string;
 /**
  * Option shapes that trigger structured-mode dispatch in {@link Graph.observe}.
  * Presence of any of these fields (truthy) → returns {@link ObserveResult};
@@ -1174,36 +1117,53 @@ declare class Graph {
     /**
      * Static structure snapshot: qualified node keys, edges, mount names (GRAPHREFLY-SPEC §3.6, Appendix B).
      *
-     * `format` controls the return type:
-     * - omitted or `"spec"` → {@link GraphDescribeOutput} object.
-     * - `"json"` / `"pretty"` / `"mermaid"` / `"d2"` → rendered string.
+     * 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, or `format` to render.
+     * @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({ format: "pretty" })                     // human-readable text
-     * graph.describe({ format: "mermaid" })                    // Mermaid flowchart
-     * graph.describe({ format: "d2", direction: "TD" })        // D2 top-down
-     * graph.describe({ format: "ascii" })                      // stdout DAG flowchart
+     * graph.describe({ detail: "spec" })                       // GraphSpec projection
+     * graph.describe({ reactive: true })                       // live snapshot Node
      * ```
      */
-    describe(options: GraphDescribeOptions & {
-        reactive: true;
-        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
-    }): ReactiveDescribeHandle<string>;
     describe(options: GraphDescribeOptions & {
         reactive: "diff";
     }): ReactiveDescribeHandle<DescribeChangeset>;
     describe(options: GraphDescribeOptions & {
         reactive: true;
     }): ReactiveDescribeHandle<GraphDescribeOutput>;
-    describe(options: GraphDescribeOptions & {
-        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
-    }): string;
     describe(options?: GraphDescribeOptions): GraphDescribeOutput;
     private _collectSubgraphs;
     /**
@@ -1230,28 +1190,44 @@ declare class Graph {
      *
      * Same question, two answers:
      * - **Static (default)** — `explain(from, to, opts?)` returns a single
-     *   {@link CausalChain} snapshot of the graph at call time.
+     *   {@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, so
-     *   the chain stays live. Replaces the former `reactiveExplainPath`.
+     *   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 (the cause).
-     * @param to - Downstream node (the effect).
-     * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+     * @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, to: string, opts?: {
-        maxDepth?: number;
-        findCycle?: boolean;
+    explain(from: string | Node<string>, to: string | Node<string>, opts?: {
+        maxDepth?: number | Node<number>;
+        findCycle?: boolean | Node<boolean>;
     }): CausalChain;
-    explain(from: string, to: string, opts: {
+    explain(from: string | Node<string>, to: string | Node<string>, opts: {
         reactive: true;
-        maxDepth?: number;
-        findCycle?: boolean;
+        maxDepth?: number | Node<number>;
+        findCycle?: boolean | Node<boolean>;
         name?: string;
     }): {
         node: Node<CausalChain>;
@@ -1689,4 +1665,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): 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 DescribeFilter as D, type ExplainPathOptions as E, type ReachableOptions as F, Graph as G, type TraceEntry as H, diffForWAL as I, explainPath as J, graphProfile as K, mermaidLiveUrl as L, type Meta as M, type NodeProfile as N, type ObserveDetail 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 GraphPersistSnapshot as b, type GraphDescribeOptions as c, type GraphDescribeOutput as d, type CausalStep as e, type DescribeChangeset as f, type DescribeEvent as g, GRAPH_META_SEGMENT as h, type GraphActorOptions as i, type GraphAttachStorageOptions as j, type GraphCheckpointRecord as k, type GraphDiagramDirection as l, type GraphDiagramOptions as m, type GraphDiffChange as n, type GraphDiffResult as o, type GraphFactoryContext as p, type GraphNodeFactory as q, type GraphObserveAll as r, type GraphObserveOne as s, type GraphProfileOptions as t, type GraphProfileResult as u, type GraphVersionChange as v, type GraphWALDiff as w, type ObserveEvent as x, type ObserveOptions as y, type ObserveResult as z };
+export { type ObserveTheme as A, type ObserveThemeName as B, type CausalChain as C, type DescribeFilter 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 GraphPersistSnapshot as c, type GraphDescribeOptions as d, type CausalStep as e, type DescribeChangeset as f, type DescribeEvent as g, GRAPH_META_SEGMENT as h, type GraphActorOptions as i, type GraphAttachStorageOptions as j, type GraphCheckpointRecord as k, type GraphDiagramDirection as l, type GraphDiffChange as m, type GraphDiffResult as n, type GraphFactoryContext as o, type GraphNodeFactory as p, type GraphObserveAll as q, type GraphObserveOne 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 };

package/dist/{index-CIcu6fIR.d.ts → index-2n8Eai6M.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.js';
+import { N as Node } from './node-BYInONRr.js';
 
 /**
  * Subscribe to a read-only `Node<T>` as a React value. Re-renders on node value settlement.

package/dist/{index-BwOsJfLJ.d.ts → index-3k4Gg6-n.d.ts}

@@ -1,6 +1,6 @@
-import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-D-tRiNhg.js';
-import { a as Node } from './node-fSc-hCv8.js';
-import { G as Graph } from './graph-BjW1taJl.js';
+import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-KJj4E2dT.js';
+import { N as Node } from './node-BYInONRr.js';
+import { G as Graph } from './graph-BkIkog4h.js';
 
 /**
  * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).

package/dist/{index-BUFCHvOR.d.ts → index-40ZT4MHj.d.ts}

@@ -1,6 +1,6 @@
-import { a as Node } from './node-fSc-hCv8.js';
-import { G as Graph, a as GraphOptions } from './graph-BjW1taJl.js';
-import { R as ReactiveLogBundle } from './reactive-log-BgWSA1fg.js';
+import { N as Node } from './node-BYInONRr.js';
+import { G as Graph, a as GraphOptions } from './graph-BkIkog4h.js';
+import { a as ReactiveLogBundle } from './reactive-log-BlAsPLl2.js';
 import { AppendLogStorageTier } from './extra/storage-tiers.js';
 
 type TopicOptions = {