@graphrefly/graphrefly 0.27.0 → 0.28.0

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

@@ -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.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';
+import { A as Actor, o as GraphReFlyConfig, V as VersioningLevel, a as Node, b as Messages, K as NodeSink } from './node-Cc1TniY8.cjs';
+import { b as DescribeNodeOutput, D as DescribeDetail, a as DescribeField } from './meta-Cgj6zeji.cjs';
+import { StorageTier, StorageHandle } from './extra/storage-core.cjs';
 
 /**
  * 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,9 +274,12 @@ 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.
      */
-    format?: "spec" | "json" | "pretty" | "mermaid" | "d2";
+    format?: "spec" | "json" | "pretty" | "mermaid" | "mermaid-url" | "d2";
     /** Pretty/diagram render: direction for diagram formats (default `LR`). */
     direction?: GraphDiagramDirection;
     /** Pretty/JSON render: indent (default 2 for JSON, ignored for pretty). */
@@ -287,7 +290,23 @@ type GraphDescribeOptions = {
     includeEdges?: boolean;
     /** Pretty render: include a Subgraphs section (default `true`). */
     includeSubgraphs?: boolean;
+    /**
+     * 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 +428,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 +451,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 +496,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 +513,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 +576,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 +663,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 +752,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
@@ -887,7 +957,14 @@ declare class Graph {
      * ```
      */
     describe(options: GraphDescribeOptions & {
-        format: "json" | "pretty" | "mermaid" | "d2";
+        reactive: true;
+        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2";
+    }): ReactiveDescribeHandle<string>;
+    describe(options: GraphDescribeOptions & {
+        reactive: true;
+    }): ReactiveDescribeHandle<GraphDescribeOutput>;
+    describe(options: GraphDescribeOptions & {
+        format: "json" | "pretty" | "mermaid" | "mermaid-url" | "d2";
     }): string;
     describe(options?: GraphDescribeOptions): GraphDescribeOutput;
     private _collectSubgraphs;
@@ -913,18 +990,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 +1241,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 +1289,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 +1419,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 };

package/dist/index-8FSVk4Uf.d.ts

@@ -0,0 +1,135 @@
+import { P as PolicyRuleData, a as Node, A as Actor } from './node-Cc1TniY8.js';
+import { G as Graph, a as GraphOptions, b as GraphDescribeOptions, c as GraphDescribeOutput, D as DescribeFilter } from './graph-BZGRXwOm.js';
+import { P as PolicyEnforcerGraph, a as PolicyViolation } from './index-HDpJe9hX.js';
+import { T as TopicGraph } from './index-B0c4cmIO.js';
+
+/**
+ * Composable safety layer (roadmap §9.0b).
+ *
+ * {@link guardedExecution} wraps any {@link Graph} with:
+ *
+ * - {@link policyEnforcer} — reactive ABAC, policies stored as a `Node` so
+ *   LLMs / humans can update them at runtime. Now with full transitive
+ *   dynamic coverage via `watchTopologyTree`.
+ * - Scoped {@link GuardedExecutionGraph.scopedDescribe} — delegates to
+ *   `target.describe({actor})` so callers see only what the actor is
+ *   allowed to see.
+ * - The enforcer's `violations` topic is republished as `violations` on
+ *   the wrapper, composable with {@link graphLens}.`health` alerts.
+ *
+ * V1 scope: policies + actor + scoped describe. Budget-as-option is NOT
+ * in V1 — it requires a cost-tracking design that hasn't landed yet.
+ * Callers who need a budget limit today append a budget-aware
+ * {@link PolicyRuleData} to the policies list (check current cost and
+ * `deny` when exhausted).
+ *
+ * @module
+ */
+
+/** Options for {@link guardedExecution}. */
+interface GuardedExecutionOptions {
+    /**
+     * Policies enforced against every guarded write. Static list or a live
+     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
+     *
+     * **Deny-by-default gotcha:** the underlying `policyFromRules()` denies any
+     * action that matches no rule. An empty policies list in `mode: "enforce"`
+     * therefore blocks EVERY write AND every `observe` through the stacked
+     * guard — including `scopedDescribe()`. If you want a permissive base, add
+     * at least `{ effect: "allow", action: "*" }` and layer deny rules on top.
+     * In `mode: "audit"` no guards are stacked, so empty policies are safe.
+     */
+    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
+    /**
+     * Actor whose perspective drives {@link GuardedExecutionGraph.scopedDescribe}
+     * and {@link GuardedExecutionGraph.describe} — when omitted, callers must
+     * pass `{actor}` explicitly or they get the target's raw describe.
+     */
+    actor?: Actor;
+    /**
+     * `"enforce"` (default) — push guards onto target nodes so disallowed
+     * writes throw {@link GuardDenied}.
+     * `"audit"` — record would-be denials to the `violations` topic without
+     * blocking writes.
+     */
+    mode?: "audit" | "enforce";
+    /** Ring-buffer cap for the `violations` topic. Default 1000 (inherited from policyEnforcer). */
+    violationsLimit?: number;
+    /** Wrapper graph name. Default `${target.name}_guarded`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Wrapper over a target {@link Graph} providing reactive ABAC + scoped
+ * describe. Mounts a {@link PolicyEnforcerGraph} under `enforcer`.
+ *
+ * @category patterns
+ */
+declare class GuardedExecutionGraph extends Graph {
+    readonly enforcer: PolicyEnforcerGraph;
+    readonly violations: TopicGraph<PolicyViolation>;
+    private readonly _target;
+    private readonly _defaultActor;
+    constructor(target: Graph, opts: GuardedExecutionOptions);
+    /**
+     * Describe the **target** graph scoped to the configured actor. Returns
+     * only nodes the actor is permitted to see (via the target's node guards
+     * filtering `describe()` via `actor`).
+     *
+     * Pass `{actor}` in opts to override the configured actor for this call.
+     * Pass any standard {@link GraphDescribeOptions} fields (`detail`,
+     * `fields`, `filter`) — they apply to the target's describe.
+     *
+     * **Mode interaction:**
+     * - In `mode: "enforce"` (default), the enforcer stacks a policy-derived
+     *   guard on every target node. `scopedDescribe({actor})` then filters by
+     *   the AND of per-node guards AND the stacked policy guard.
+     * - In `mode: "audit"`, NO guards are stacked — `scopedDescribe` filters
+     *   purely by the target's pre-existing per-node guards. If a target has
+     *   no node-level guards, the policy rules you pass have no effect on
+     *   visibility (they only populate the `violations` topic on writes).
+     */
+    scopedDescribe(opts?: Omit<GraphDescribeOptions, "actor"> & {
+        actor?: Actor;
+    }): GraphDescribeOutput;
+    /** The wrapped graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wrap a {@link Graph} with {@link policyEnforcer} plus a scoped describe
+ * lens. Returns a {@link GuardedExecutionGraph} that can be mounted, diffed,
+ * or composed with {@link graphLens}.
+ *
+ * @param target - The graph to guard.
+ * @param opts - See {@link GuardedExecutionOptions}.
+ *
+ * @example
+ * ```ts
+ * const guarded = guardedExecution(app, {
+ *   actor: { type: "human", id: "alice" },
+ *   policies: [
+ *     { effect: "allow", action: "read", actorType: "human" },
+ *     { effect: "deny", action: "write", pathPattern: "system::*" },
+ *   ],
+ *   mode: "enforce",
+ * });
+ *
+ * const view = guarded.scopedDescribe({ detail: "standard" });
+ * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
+
+declare const index_DescribeFilter: typeof DescribeFilter;
+type index_GuardedExecutionGraph = GuardedExecutionGraph;
+declare const index_GuardedExecutionGraph: typeof GuardedExecutionGraph;
+type index_GuardedExecutionOptions = GuardedExecutionOptions;
+declare const index_guardedExecution: typeof guardedExecution;
+declare namespace index {
+  export { index_DescribeFilter as DescribeFilter, index_GuardedExecutionGraph as GuardedExecutionGraph, type index_GuardedExecutionOptions as GuardedExecutionOptions, index_guardedExecution as guardedExecution };
+}
+
+export { GuardedExecutionGraph as G, type GuardedExecutionOptions as a, guardedExecution as g, index as i };