@graphrefly/graphrefly 0.25.0 → 0.27.0

package/dist/{chunk-XOFWRC73.js → chunk-PF7GRZMW.js}

@@ -1,31 +1,229 @@
 import {
   describeNode,
   resolveDescribeFields
-} from "./chunk-H4RVA4VE.js";
+} from "./chunk-VYPWMZ6H.js";
 import {
   ResettableTimer,
   RingBuffer
 } from "./chunk-7TAQJHQV.js";
 import {
-  COMPLETE,
-  DATA,
-  DIRTY,
-  ERROR,
   GuardDenied,
-  INVALIDATE,
   NodeImpl,
-  PAUSE,
-  RESOLVED,
-  RESUME,
-  TEARDOWN,
   batch,
   decodeEnvelope,
   defaultConfig,
   encodeEnvelope,
   isBatching,
   monotonicNs,
-  state
-} from "./chunk-5DJTTKX3.js";
+  producer,
+  state,
+  wallClockNs
+} from "./chunk-PHOUUNK7.js";
+import {
+  COMPLETE,
+  DATA,
+  DIRTY,
+  ERROR,
+  INVALIDATE,
+  PAUSE,
+  RESOLVED,
+  RESUME,
+  TEARDOWN
+} from "./chunk-SX52TAR4.js";
+
+// src/graph/explain.ts
+function explainPath(described, from, to, opts = {}) {
+  const fromExists = from in described.nodes;
+  const toExists = to in described.nodes;
+  if (!fromExists) return makeFailure(from, to, "no-such-from");
+  if (!toExists) return makeFailure(from, to, "no-such-to");
+  const maxDepth = opts.maxDepth;
+  if (maxDepth != null && (!Number.isInteger(maxDepth) || maxDepth < 0)) {
+    throw new Error(`explainPath: maxDepth must be an integer >= 0`);
+  }
+  if (from === to) {
+    if (opts.findCycle === true) {
+      const cycle = findShortestCycle(described, from, opts);
+      if (cycle != null) return cycle;
+    }
+    const step = buildStep(from, described.nodes[from], 0, opts);
+    return makeSuccess(from, to, [step]);
+  }
+  if (maxDepth === 0) return makeFailure(from, to, "no-path");
+  const result = bfsShortestPath(described, from, to, maxDepth);
+  if (!result.found) {
+    return makeFailure(from, to, result.truncated ? "max-depth-exceeded" : "no-path");
+  }
+  return makeSuccess(from, to, materializeSteps(described, result.pathOrder, opts));
+}
+function bfsShortestPath(described, from, to, maxDepth) {
+  const pred = /* @__PURE__ */ new Map();
+  const queue = [{ path: to, depth: 0 }];
+  const visited = /* @__PURE__ */ new Set([to]);
+  let head = 0;
+  let truncated = false;
+  while (head < queue.length) {
+    const cur = queue[head++];
+    if (cur.path === from) break;
+    if (maxDepth != null && cur.depth >= maxDepth) {
+      const node2 = described.nodes[cur.path];
+      if (node2?.deps && node2.deps.length > 0) truncated = true;
+      continue;
+    }
+    const node = described.nodes[cur.path];
+    if (node == null) continue;
+    const deps = node.deps ?? [];
+    const slots = /* @__PURE__ */ new Map();
+    for (let i = 0; i < deps.length; i++) {
+      const dep = deps[i];
+      if (!dep) continue;
+      let arr = slots.get(dep);
+      if (arr == null) {
+        arr = [];
+        slots.set(dep, arr);
+      }
+      arr.push(i);
+    }
+    for (const [dep, indices] of slots) {
+      if (visited.has(dep)) continue;
+      visited.add(dep);
+      pred.set(dep, { from: cur.path, depIndices: indices });
+      queue.push({ path: dep, depth: cur.depth + 1 });
+    }
+  }
+  if (!pred.has(from)) {
+    return { found: false, pathOrder: [], truncated };
+  }
+  const pathOrder = [{ path: from }];
+  let cursor = from;
+  while (cursor !== to) {
+    const p = pred.get(cursor);
+    if (p == null) return { found: false, pathOrder: [], truncated: false };
+    pathOrder[pathOrder.length - 1].depIndices = p.depIndices;
+    pathOrder.push({ path: p.from });
+    cursor = p.from;
+  }
+  return { found: true, pathOrder, truncated: false };
+}
+function findShortestCycle(described, start, opts) {
+  const startNode = described.nodes[start];
+  if (startNode == null) return null;
+  const startDeps = startNode.deps ?? [];
+  const selfSlots = [];
+  for (let i = 0; i < startDeps.length; i++) if (startDeps[i] === start) selfSlots.push(i);
+  if (selfSlots.length > 0) {
+    const step0 = buildStep(start, startNode, 0, opts);
+    step0.dep_index = selfSlots[0];
+    const step1 = buildStep(start, startNode, 1, opts);
+    return makeSuccess(start, start, [step0, step1]);
+  }
+  let best = null;
+  for (let i = 0; i < startDeps.length; i++) {
+    const dep = startDeps[i];
+    if (!dep || dep === start) continue;
+    const sub = bfsShortestPath(described, dep, start, opts.maxDepth);
+    if (!sub.found) continue;
+    if (best == null || sub.pathOrder.length < best.pathOrder.length) {
+      best = sub;
+      best = {
+        found: true,
+        pathOrder: [{ path: start, depIndices: [i] }, ...sub.pathOrder],
+        truncated: false
+      };
+    }
+  }
+  if (best == null) return null;
+  return makeSuccess(start, start, materializeSteps(described, best.pathOrder, opts));
+}
+function materializeSteps(described, pathOrder, opts) {
+  return pathOrder.map((entry, i) => {
+    const node = described.nodes[entry.path];
+    const step = buildStep(entry.path, node, i, opts);
+    if (entry.depIndices != null && entry.depIndices.length > 0) {
+      step.dep_index = entry.depIndices[0];
+      if (entry.depIndices.length > 1) step.dep_indices = [...entry.depIndices];
+    }
+    return step;
+  });
+}
+function buildStep(path, node, hop, opts) {
+  const step = {
+    path,
+    type: node.type,
+    hop
+  };
+  if (node.status !== void 0) step.status = node.status;
+  if ("value" in node) step.value = node.value;
+  if (node.v != null) step.v = node.v;
+  const annotation = opts.annotations?.get(path) ?? node.reason;
+  if (annotation != null) step.reason = annotation;
+  const lastMutation = opts.lastMutations?.get(path) ?? node.lastMutation;
+  if (lastMutation != null) step.lastMutation = lastMutation;
+  return step;
+}
+function makeSuccess(from, to, steps) {
+  return finalize(from, to, true, "ok", steps);
+}
+function makeFailure(from, to, reason) {
+  return finalize(from, to, false, reason, []);
+}
+function finalize(from, to, found, reason, steps) {
+  const text = renderChain(from, to, found, reason, steps);
+  return {
+    from,
+    to,
+    found,
+    reason,
+    steps,
+    text,
+    toJSON() {
+      return { from, to, found, reason, steps };
+    }
+  };
+}
+function renderChain(from, to, found, reason, steps) {
+  if (!found) {
+    switch (reason) {
+      case "no-such-from":
+        return `explainPath: no node named "${from}"`;
+      case "no-such-to":
+        return `explainPath: no node named "${to}"`;
+      case "max-depth-exceeded":
+        return `explainPath: no path from "${from}" to "${to}" within maxDepth`;
+      default:
+        return `explainPath: no path from "${from}" to "${to}"`;
+    }
+  }
+  const lines = [`Causal path: ${from} \u2192 ${to} (${steps.length} step(s))`];
+  for (const step of steps) {
+    const arrow = step.hop === 0 ? "\xB7" : "\u2193";
+    const head = `  ${arrow} ${step.path} (${step.type}${step.status ? `/${step.status}` : ""})`;
+    lines.push(head);
+    if ("value" in step) {
+      lines.push(`      value: ${formatValue(step.value)}`);
+    }
+    if (step.reason != null) {
+      lines.push(`      reason: ${step.reason}`);
+    }
+    if (step.lastMutation != null) {
+      const a = step.lastMutation.actor;
+      lines.push(`      actor: ${a.type}${a.id ? `:${a.id}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatValue(v) {
+  if (v === void 0) return "<sentinel>";
+  if (v === null) return "null";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+  try {
+    const s = JSON.stringify(v);
+    return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+  } catch {
+    return String(v);
+  }
+}
 
 // src/extra/utils/sizeof.ts
 var OVERHEAD = {
@@ -660,6 +858,20 @@ var Graph = class _Graph {
   _parent = void 0;
   _storageDisposers = /* @__PURE__ */ new Set();
   _disposers = /* @__PURE__ */ new Set();
+  /**
+   * @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}.
+   */
+  _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).
+   */
+  _topologyEmitters = /* @__PURE__ */ new Set();
   /**
    * @param name - Non-empty graph id (must not contain `::` and must not
    *   equal the reserved meta segment `__meta__`).
@@ -699,6 +911,55 @@ var Graph = class _Graph {
     return out;
   }
   // ——————————————————————————————————————————————————————————————
+  //  Topology companion (structural-change event stream)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * 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() {
+    if (this._topology == null) {
+      this._topology = producer(
+        (actions) => {
+          const handler = (event) => {
+            actions.emit(event);
+          };
+          this._topologyEmitters.add(handler);
+          return () => {
+            this._topologyEmitters.delete(handler);
+          };
+        },
+        { name: `${this.name}_topology` }
+      );
+    }
+    return this._topology;
+  }
+  /**
+   * @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.
+   */
+  _emitTopology(event) {
+    if (this._topology == null || this._topologyEmitters.size === 0) return;
+    for (const h of this._topologyEmitters) h(event);
+  }
+  // ——————————————————————————————————————————————————————————————
   //  Node registry
   // ——————————————————————————————————————————————————————————————
   /**
@@ -728,6 +989,7 @@ var Graph = class _Graph {
     }
     this._nodes.set(name, node);
     this._nodeToName.set(node, name);
+    this._emitTopology({ kind: "added", name, nodeKind: "node" });
     return node;
   }
   /**
@@ -768,22 +1030,23 @@ var Graph = class _Graph {
     assertRegisterableName(name, this.name, "remove");
     const child = this._mounts.get(name);
     if (child) {
-      const audit = { kind: "mount", nodes: [], mounts: [] };
+      const audit2 = { kind: "mount", nodes: [], mounts: [] };
       const targets = [];
       child._collectObserveTargets("", targets);
       for (const [p, n] of targets) {
         if (!p.includes(`${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}`)) {
-          audit.nodes.push(p);
+          audit2.nodes.push(p);
         }
         void n;
       }
-      audit.nodes.sort();
-      audit.mounts.push(name);
-      audit.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
+      audit2.nodes.sort();
+      audit2.mounts.push(name);
+      audit2.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
       this._mounts.delete(name);
       child._parent = void 0;
       teardownMountedGraph(child);
-      return audit;
+      this._emitTopology({ kind: "removed", name, nodeKind: "mount", audit: audit2 });
+      return audit2;
     }
     const node = this._nodes.get(name);
     if (!node) {
@@ -792,7 +1055,9 @@ var Graph = class _Graph {
     this._nodes.delete(name);
     this._nodeToName.delete(node);
     node.down([[TEARDOWN]], { internal: true });
-    return { kind: "node", nodes: [name], mounts: [] };
+    const audit = { kind: "node", nodes: [name], mounts: [] };
+    this._emitTopology({ kind: "removed", name, nodeKind: "node", audit });
+    return audit;
   }
   /**
    * Bulk remove — invokes {@link Graph.remove} for every local name matching
@@ -1021,6 +1286,7 @@ var Graph = class _Graph {
     }
     this._mounts.set(name, child);
     child._parent = this;
+    this._emitTopology({ kind: "added", name, nodeKind: "mount" });
     return child;
   }
   /**
@@ -1311,6 +1577,33 @@ var Graph = class _Graph {
     }
     return reachable(this.describe(), from, direction, opts);
   }
+  /**
+   * 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, to, opts) {
+    const described = this.describe({ detail: "full" });
+    const annotations = new Map(this._annotations);
+    const lastMutations = /* @__PURE__ */ new Map();
+    for (const [path, n] of Object.entries(described.nodes)) {
+      if (n.lastMutation != null) lastMutations.set(path, n.lastMutation);
+    }
+    return explainPath(described, from, to, {
+      ...opts?.maxDepth != null ? { maxDepth: opts.maxDepth } : {},
+      ...opts?.findCycle === true ? { findCycle: true } : {},
+      annotations,
+      lastMutations
+    });
+  }
   /**
    * @internal Collect all qualified paths in this graph tree matching a
    * glob pattern. Used by scoped autoCheckpoint subscription.
@@ -1989,7 +2282,7 @@ var Graph = class _Graph {
         return;
       }
       const nextSeq = s.seq + 1;
-      const timestamp_ns = monotonicNs();
+      const timestamp_ns = wallClockNs();
       const isFirst = s.lastSnapshot == null;
       const shouldCompact = isFirst || nextSeq % s.compactEvery === 0;
       const record = shouldCompact ? {
@@ -2405,13 +2698,15 @@ function reachable(described, from, direction, options = {}) {
 }
 
 export {
+  explainPath,
   OVERHEAD,
   SIZEOF_SYMBOL,
   sizeof,
   graphProfile,
   GRAPH_META_SEGMENT,
+  SNAPSHOT_VERSION,
   Graph,
   diffForWAL,
   reachable
 };
-//# sourceMappingURL=chunk-XOFWRC73.js.map
+//# sourceMappingURL=chunk-PF7GRZMW.js.map