@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/{graph-CCwGKLCm.d.ts → graph-Qjg9gWHI.d.ts}

@@ -1,6 +1,6 @@
-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';
+import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-Dd6wHSib.js';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-CckhhFRd.js';
+import { StorageTier, StorageHandle } from './extra/storage-core.js';
 
 /**
  * Causal walkback over a {@link Graph.describe} snapshot (roadmap §9.2).
@@ -29,8 +29,8 @@ interface CausalStep {
     value?: unknown;
     /** Hop distance from `from` (0 = `from`, N = `to`). */
     hop: number;
-    /** Reason annotation set via `graph.trace(path, reason)`, when present. */
-    reason?: string;
+    /** Annotation set via `graph.trace(path, annotation)` or `graph.add(node, { name: path, annotation })`, when present. */
+    annotation?: string;
     /** Most recent guarded mutation, when known. */
     lastMutation?: Readonly<{
         actor: Actor;
@@ -274,20 +274,54 @@ type GraphDescribeOptions = {
      * - `"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" | "d2";
+    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 render: optional logger hook; fires with the rendered text before return. */
+    /** 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): when `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 }` — one recompute per
+     * outermost drain via the batch-flush hook, so large batched mutations
+     * don't amplify describe work per event.
+     */
+    reactive?: boolean;
+    /** Reactive-only: name for the backing derived node (default `"describe"`). */
+    reactiveName?: string;
 };
+/** Handle returned by {@link Graph.describe} with `{ reactive: true }`. */
+interface ReactiveDescribeHandle<T> {
+    readonly node: Node<T>;
+    dispose(): void;
+}
 /** JSON snapshot from {@link Graph.describe} (GRAPHREFLY-SPEC §3.6, Appendix B). */
 type GraphDescribeOutput = {
     name: string;
@@ -409,6 +443,19 @@ 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};
@@ -419,7 +466,7 @@ type StructuredTriggers = {
     timeline?: true;
     causal?: true;
     derived?: true;
-    format?: "pretty" | "json";
+    format?: "pretty" | "json" | "stage-log";
     detail?: "minimal" | "full";
 };
 /** {@link Graph.observe} on a single node or meta path — sink receives plain message batches. */
@@ -464,9 +511,15 @@ type ObserveOptions = {
     detail?: ObserveDetail;
     /**
      * When set, auto-enables structured mode and attaches a logger.
-     * `"pretty"` renders colored one-line output; `"json"` emits one JSON object per event.
-     */
-    format?: "pretty" | "json";
+     * - `"pretty"` — colored one-line output per event.
+     * - `"json"` — one JSON object per event.
+     * - `"stage-log"` — pipeline-stage-labeled output for multi-node
+     *   observers. Auto-enables `timeline: true` so each line carries an
+     *   elapsed-seconds offset from the subscription. Provide a
+     *   {@link stageLabels} map to label each observed path; paths without a
+     *   mapping fall back to the path string.
+     */
+    format?: "pretty" | "json" | "stage-log";
     /** Sink for rendered lines (`console.log` by default). Only used when `format` is set. */
     logger?: (line: string, event: ObserveEvent) => void;
     /** Keep only these event types in formatted output. Only used when `format` is set. */
@@ -475,6 +528,13 @@ type ObserveOptions = {
     excludeTypes?: ObserveEvent["type"][];
     /** Built-in color preset (`ansi` default) or explicit color tokens. Only used when `format` is set. */
     theme?: ObserveThemeName | ObserveTheme;
+    /**
+     * Stage labels for `format: "stage-log"`. Keys are observe paths; values
+     * are short stage names (e.g. `{ "intake::latest": "INTAKE" }`). Paths
+     * without a mapping render under the path string itself. Ignored for
+     * other formats.
+     */
+    stageLabels?: Record<string, string>;
     /**
      * Cap the `events` buffer. When set, the result uses a {@link RingBuffer}
      * under the hood: oldest events are dropped on overflow. Unbounded when
@@ -531,6 +591,20 @@ interface ObserveEventBase {
     in_batch?: boolean;
     /** Monotonically increasing counter per subscribe-callback invocation. All events in one delivery share the same id. */
     batch_id?: number;
+    /**
+     * Attribution for `data`/`error` events (B9 — actor threading). When
+     * the originating `node.down(...)` call supplied an `actor` via
+     * `NodeTransportOptions`, it's forwarded here as read from
+     * `Node.lastMutation`. Internal / unattributed writes stamp the
+     * library's `DEFAULT_ACTOR` (`{type: "system", id: ""}`) rather than
+     * being silently dropped, so downstream policy/audit consumers can
+     * evaluate policies against a well-formed actor in every case.
+     *
+     * Not populated for tier-1/tier-2 protocol events (`dirty`, `resolved`,
+     * `pause`, `resume`, `invalidate`, `teardown`) — those don't carry
+     * caller attribution.
+     */
+    actor?: Actor;
 }
 /** Optional `causal` context present on `data`/`resolved`/`derived` events. */
 interface ObserveCausalContext {
@@ -604,7 +678,7 @@ type ObserveTheme = Partial<Record<ObserveEvent["type"] | "path" | "reset", stri
  * import { Graph, state } from "@graphrefly/graphrefly-ts";
  *
  * const g = new Graph("app");
- * g.add("counter", state(0));
+ * g.add(state(0, { name: "counter" }));
  * ```
  *
  * @category graph
@@ -693,12 +767,23 @@ declare class Graph {
      * the node is torn down.
      *
      * Returns the registered node so callers can chain:
-     * `const counter = g.add("counter", state(0))`.
+     * `const counter = g.add(state(0, { name: "counter" }))`.
+     *
+     * **Signature:** `add(node, { name?, annotation? })`. Name lives in opts;
+     * falls back to `node.name` from the node's own options. Throws if neither
+     * is a non-empty string.
+     *
+     * The optional `opts.annotation` installs an initial
+     * `graph.trace(name, annotation)` entry — same effect as calling
+     * `graph.trace` right after, but reads naturally next to the registration.
      *
-     * @param name - Local key (no `::`).
      * @param node - Node instance to own.
+     * @param opts - `{ name?, annotation? }`.
      */
-    add<T extends Node>(name: string, node: T): T;
+    add<T extends Node>(node: T, opts?: {
+        name?: string;
+        annotation?: string;
+    }): T;
     /**
      * Bulk-apply a minimum versioning level to every currently-registered node
      * in this graph (roadmap §6.0). `_applyVersioning` is monotonic — nodes
@@ -884,10 +969,18 @@ declare class Graph {
      * 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
      * ```
      */
     describe(options: GraphDescribeOptions & {
-        format: "json" | "pretty" | "mermaid" | "d2";
+        reactive: true;
+        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2" | "ascii";
+    }): ReactiveDescribeHandle<string>;
+    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;
@@ -913,18 +1006,38 @@ declare class Graph {
      * each node's value, status, last-mutation actor, and reasoning annotation
      * from {@link Graph.trace}. Wraps {@link explainPath} (roadmap §9.2).
      *
+     * Same question, two answers:
+     * - **Static (default)** — `explain(from, to, opts?)` returns a single
+     *   {@link CausalChain} snapshot of the graph at call time.
+     * - **Reactive** — `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`.
+     *
      * @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.
+     *   When `reactive: true`, also accepts `name?`.
      */
     explain(from: string, to: string, opts?: {
         maxDepth?: number;
         findCycle?: boolean;
     }): CausalChain;
+    explain(from: string, to: string, opts: {
+        reactive: true;
+        maxDepth?: number;
+        findCycle?: boolean;
+        name?: string;
+    }): {
+        node: Node<CausalChain>;
+        dispose: () => void;
+    };
+    private _explainStatic;
+    private _describeReactive;
+    private _explainReactive;
     /**
      * @internal Collect all qualified paths in this graph tree matching a
      * glob pattern. Used by scoped autoCheckpoint subscription.
@@ -1144,22 +1257,28 @@ declare class Graph {
     /**
      * Unified reasoning trace: write annotations or read the ring buffer.
      *
-     * Write: `graph.trace("path", "reason")` — attaches a reasoning annotation
-     * to a node, capturing *why* an AI agent set a value. Unknown paths are
-     * silently dropped (matching `observe` resilience). No-op when
-     * `config.inspectorEnabled` is `false`.
-     *
-     * Read: `graph.trace()` — returns a chronological log of all annotations.
-     * Returns `[]` when `config.inspectorEnabled` is `false`.
-     */
-    trace(path: string, reason: string, opts?: {
+     * - `graph.trace("path", "annotation")` — attaches a reasoning annotation
+     *   to a node, capturing *why* an AI agent set a value. Overwrites the
+     *   current annotation (if any) and appends to the chronological ring.
+     *   Unknown paths are silently dropped (matching `observe` resilience).
+     *   No-op when `config.inspectorEnabled` is `false`.
+     * - `graph.trace("path")` — returns the current annotation for `path`,
+     *   or `undefined` if none. Precedence: most recent `trace(path, ...)`
+     *   wins; if no trace call, whatever `graph.add(node, { name: "path", annotation })`
+     *   installed; otherwise `undefined`.
+     * - `graph.trace()` — returns a chronological log of all write entries.
+     *   Returns `[]` when `config.inspectorEnabled` is `false`.
+     */
+    trace(path: string, annotation: string, opts?: {
         actor?: Actor;
     }): void;
+    trace(path: string): string | undefined;
     trace(): readonly TraceEntry[];
     /**
-     * Latest reason annotation attached to `path` via {@link Graph.trace},
-     * or `undefined` if none. `describe()` surfaces this via the `reason`
-     * field on each node entry (when present).
+     * Latest annotation attached to `path` — via {@link Graph.trace} or via
+     * {@link Graph.add}'s `{annotation}` option. Returns `undefined` if none.
+     * `describe()` surfaces this via the `annotation` field on each node entry
+     * (when present). Equivalent to `graph.trace(path)`.
      */
     annotation(path: string): string | undefined;
     /**
@@ -1186,7 +1305,7 @@ declare class Graph {
 /** Entry in the reasoning trace ring buffer (roadmap 3.3). */
 type TraceEntry = {
     path: string;
-    reason: string;
+    annotation: string;
     timestamp_ns: number;
     /**
      * Actor that produced the annotation (optional). Enables multi-agent
@@ -1316,4 +1435,4 @@ declare function reachable(described: GraphDescribeOutput, from: string, directi
 }): ReachableResult;
 declare function reachable(described: GraphDescribeOutput, from: string, direction: ReachableDirection, options?: ReachableOptions): string[];
 
-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 };
+export { type ReachableOptions as A, type TraceEntry as B, type CausalChain as C, type DescribeFilter as D, type ExplainPathOptions as E, diffForWAL as F, Graph as G, explainPath as H, graphProfile as I, mermaidLiveUrl as J, reachable as K, type NodeProfile as N, type ObserveDetail as O, type ReachableDirection as R, SNAPSHOT_VERSION as S, type TopologyEvent as T, type GraphOptions as a, type GraphDescribeOptions as b, type GraphDescribeOutput as c, type GraphPersistSnapshot as d, type CausalStep as e, GRAPH_META_SEGMENT as f, type GraphActorOptions as g, type GraphAttachStorageOptions as h, type GraphCheckpointRecord 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 GraphProfileOptions as r, type GraphProfileResult 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 };