@graphrefly/graphrefly 0.25.0 → 0.27.0

package/dist/graph/index.cjs

@@ -26,16 +26,19 @@ __export(graph_exports, {
   JsonCodec: () => JsonCodec,
   SIZEOF_OVERHEAD: () => OVERHEAD,
   SIZEOF_SYMBOL: () => SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION: () => SNAPSHOT_VERSION,
   createDagCborCodec: () => createDagCborCodec,
   createDagCborZstdCodec: () => createDagCborZstdCodec,
   decodeEnvelope: () => decodeEnvelope,
   diffForWAL: () => diffForWAL,
   encodeEnvelope: () => encodeEnvelope,
+  explainPath: () => explainPath,
   graphProfile: () => graphProfile,
   reachable: () => reachable,
   registerBuiltinCodecs: () => registerBuiltinCodecs,
   replayWAL: () => replayWAL,
-  sizeof: () => sizeof
+  sizeof: () => sizeof,
+  watchTopologyTree: () => watchTopologyTree
 });
 module.exports = __toCommonJS(graph_exports);
 
@@ -317,6 +320,200 @@ function replayWAL(entries) {
   return result;
 }
 
+// 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 node3 = described.nodes[cur.path];
+      if (node3?.deps && node3.deps.length > 0) truncated = true;
+      continue;
+    }
+    const node2 = described.nodes[cur.path];
+    if (node2 == null) continue;
+    const deps = node2.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 node2 = described.nodes[entry.path];
+    const step = buildStep(entry.path, node2, 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, node2, hop, opts) {
+  const step = {
+    path,
+    type: node2.type,
+    hop
+  };
+  if (node2.status !== void 0) step.status = node2.status;
+  if ("value" in node2) step.value = node2.value;
+  if (node2.v != null) step.v = node2.v;
+  const annotation = opts.annotations?.get(path) ?? node2.reason;
+  if (annotation != null) step.reason = annotation;
+  const lastMutation = opts.lastMutations?.get(path) ?? node2.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/core/batch.ts
 var MAX_DRAIN_ITERATIONS = 1e3;
 var batchDepth = 0;
@@ -1077,6 +1274,12 @@ var NodeImpl = class _NodeImpl {
   _autoError;
   _pausable;
   _guard;
+  /**
+   * @internal Additional guards stacked at runtime via {@link NodeImpl._pushGuard}
+   * (e.g. by `policyEnforcer({ mode: "enforce" })`, roadmap §9.2). Effective
+   * write/signal/observe checks AND the original `_guard` with every entry here.
+   */
+  _extraGuards;
   _hashFn;
   _versioning;
   /**
@@ -1250,18 +1453,61 @@ var NodeImpl = class _NodeImpl {
       if (this._inspectorHooks?.size === 0) this._inspectorHooks = void 0;
     };
   }
+  /**
+   * @internal Push an additional guard onto this node. Effective enforcement
+   * is the AND of `_guard` and every guard pushed via this hook — any one
+   * rejecting throws {@link GuardDenied}. Returns a disposer that removes
+   * the pushed guard. Multiple guards may be stacked simultaneously.
+   *
+   * Used by `policyEnforcer({ mode: "enforce" })` (roadmap §9.2) to overlay
+   * runtime constraint enforcement onto an existing graph without rebuilding
+   * its nodes. Pre-1.0 internal API; not part of the public surface.
+   *
+   * **Identity semantics:** guards are tracked in a `Set`, so pushing the
+   * same `NodeGuard` reference twice is a single registration. Wrap each
+   * push in a unique closure if independent stacking is needed.
+   *
+   * **Iteration order:** insertion-ordered (`Set` semantics). Determinism
+   * follows from single-threaded JS execution; nested re-entry from inside
+   * a guard body (push/pop while iterating) is undefined-but-survivable.
+   */
+  _pushGuard(guard) {
+    if (this._extraGuards == null) this._extraGuards = /* @__PURE__ */ new Set();
+    this._extraGuards.add(guard);
+    return () => {
+      this._extraGuards?.delete(guard);
+      if (this._extraGuards?.size === 0) this._extraGuards = void 0;
+    };
+  }
   allowsObserve(actor) {
-    if (this._guard == null) return true;
-    return this._guard(normalizeActor(actor), "observe");
+    if (this._guard == null && this._extraGuards == null) return true;
+    const a = normalizeActor(actor);
+    if (this._guard != null && !this._guard(a, "observe")) return false;
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(a, "observe")) return false;
+      }
+    }
+    return true;
   }
   // --- Guard helper ---
   _checkGuard(options) {
-    if (options?.internal || this._guard == null) return;
+    if (options?.internal) return;
+    const hasGuard = this._guard != null || this._extraGuards != null;
+    const hasActor = options?.actor != null;
+    if (!hasGuard && !hasActor) return;
     const actor = normalizeActor(options?.actor);
     const action = options?.delivery === "signal" ? "signal" : "write";
-    if (!this._guard(actor, action)) {
+    if (this._guard != null && !this._guard(actor, action)) {
       throw new GuardDenied({ actor, action, nodeName: this.name });
     }
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(actor, action)) {
+          throw new GuardDenied({ actor, action, nodeName: this.name });
+        }
+      }
+    }
     this._lastMutation = { actor, timestamp_ns: wallClockNs() };
   }
   // --- Public transport ---
@@ -2275,6 +2521,10 @@ function describeNode(node2, includeFields) {
 function state(initial, opts) {
   return node([], { ...opts, initial });
 }
+function producer(fn, opts) {
+  const wrapped = (_data, actions, ctx) => fn(actions, ctx) ?? void 0;
+  return node(wrapped, { describeKind: "producer", ...opts });
+}
 
 // src/extra/timer.ts
 var ResettableTimer = class {
@@ -2871,6 +3121,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__`).
@@ -2910,6 +3174,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
   // ——————————————————————————————————————————————————————————————
   /**
@@ -2939,6 +3252,7 @@ var Graph = class _Graph {
     }
     this._nodes.set(name, node2);
     this._nodeToName.set(node2, name);
+    this._emitTopology({ kind: "added", name, nodeKind: "node" });
     return node2;
   }
   /**
@@ -2979,22 +3293,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 node2 = this._nodes.get(name);
     if (!node2) {
@@ -3003,7 +3318,9 @@ var Graph = class _Graph {
     this._nodes.delete(name);
     this._nodeToName.delete(node2);
     node2.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
@@ -3232,6 +3549,7 @@ var Graph = class _Graph {
     }
     this._mounts.set(name, child);
     child._parent = this;
+    this._emitTopology({ kind: "added", name, nodeKind: "mount" });
     return child;
   }
   /**
@@ -3522,6 +3840,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.
@@ -4200,7 +4545,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 ? {
@@ -4614,6 +4959,52 @@ function reachable(described, from, direction, options = {}) {
   if (options.withDetail) return { paths, depths, truncated };
   return paths;
 }
+
+// src/graph/topology-tree.ts
+function watchTopologyTree(graph, cb) {
+  const subs = /* @__PURE__ */ new Map();
+  const wire = (g, prefix) => {
+    if (subs.has(g)) return;
+    const placeholder = { off: () => {
+    }, prefix };
+    subs.set(g, placeholder);
+    const off = g.topology.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] !== DATA) continue;
+        const event = m[1];
+        cb(event, g, prefix);
+        if (event.kind === "added" && event.nodeKind === "mount") {
+          const child = g._mounts.get(event.name);
+          if (child instanceof Graph) {
+            const childPrefix = `${prefix}${event.name}::`;
+            wire(child, childPrefix);
+          }
+        } else if (event.kind === "removed" && event.nodeKind === "mount") {
+          const removedPrefix = `${prefix}${event.name}::`;
+          for (const [trackedGraph, trackedEntry] of Array.from(subs.entries())) {
+            if (trackedGraph === graph) continue;
+            if (trackedEntry.prefix.startsWith(removedPrefix)) {
+              trackedEntry.off();
+              subs.delete(trackedGraph);
+            }
+          }
+        }
+      }
+    });
+    placeholder.off = off;
+    for (const [mountName, child] of g._mounts) {
+      if (child instanceof Graph) {
+        const childPrefix = `${prefix}${mountName}::`;
+        wire(child, childPrefix);
+      }
+    }
+  };
+  wire(graph, "");
+  return () => {
+    for (const entry of subs.values()) entry.off();
+    subs.clear();
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ENVELOPE_VERSION,
@@ -4622,15 +5013,18 @@ function reachable(described, from, direction, options = {}) {
   JsonCodec,
   SIZEOF_OVERHEAD,
   SIZEOF_SYMBOL,
+  SNAPSHOT_VERSION,
   createDagCborCodec,
   createDagCborZstdCodec,
   decodeEnvelope,
   diffForWAL,
   encodeEnvelope,
+  explainPath,
   graphProfile,
   reachable,
   registerBuiltinCodecs,
   replayWAL,
-  sizeof
+  sizeof,
+  watchTopologyTree
 });
 //# sourceMappingURL=index.cjs.map