@graphrefly/graphrefly 0.1.0

package/dist/chunk-6W5SGIGB.js

@@ -0,0 +1,1793 @@
+import {
+  describeNode
+} from "./chunk-O3PI7W45.js";
+import {
+  COMPLETE,
+  DATA,
+  DIRTY,
+  ERROR,
+  GuardDenied,
+  INVALIDATE,
+  NodeImpl,
+  RESOLVED,
+  TEARDOWN,
+  isBatching,
+  messageTier,
+  monotonicNs,
+  state
+} from "./chunk-5X3LAO3B.js";
+
+// src/graph/graph.ts
+var PATH_SEP = "::";
+var GRAPH_META_SEGMENT = "__meta__";
+var SNAPSHOT_VERSION = 1;
+function parseSnapshotEnvelope(data) {
+  if (data.version !== SNAPSHOT_VERSION) {
+    throw new Error(
+      `unsupported snapshot version ${String(data.version)} (expected ${SNAPSHOT_VERSION})`
+    );
+  }
+  for (const key of ["name", "nodes", "edges", "subgraphs"]) {
+    if (!(key in data)) {
+      throw new Error(`snapshot missing required key "${key}"`);
+    }
+  }
+  if (typeof data.name !== "string") {
+    throw new TypeError(`snapshot 'name' must be a string`);
+  }
+  if (typeof data.nodes !== "object" || data.nodes === null || Array.isArray(data.nodes)) {
+    throw new TypeError(`snapshot 'nodes' must be an object`);
+  }
+  if (!Array.isArray(data.edges)) {
+    throw new TypeError(`snapshot 'edges' must be an array`);
+  }
+  if (!Array.isArray(data.subgraphs)) {
+    throw new TypeError(`snapshot 'subgraphs' must be an array`);
+  }
+}
+function sortJsonValue(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const out = {};
+  for (const k of keys) {
+    out[k] = sortJsonValue(obj[k]);
+  }
+  return out;
+}
+function stableJsonStringify(value) {
+  return `${JSON.stringify(sortJsonValue(value))}
+`;
+}
+function escapeMermaidLabel(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+function escapeD2Label(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+function d2DirectionFromGraphDirection(direction) {
+  if (direction === "TD") return "down";
+  if (direction === "BT") return "up";
+  if (direction === "RL") return "left";
+  return "right";
+}
+function collectDiagramArrows(described) {
+  const seen = /* @__PURE__ */ new Set();
+  const arrows = [];
+  function add(from, to) {
+    const key = `${from}\0${to}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    arrows.push([from, to]);
+  }
+  for (const [path, info] of Object.entries(described.nodes)) {
+    const deps = info.deps;
+    if (deps) {
+      for (const dep of deps) add(dep, path);
+    }
+  }
+  for (const edge of described.edges) add(edge.from, edge.to);
+  return arrows;
+}
+function normalizeDiagramDirection(direction) {
+  if (direction === void 0) return "LR";
+  if (direction === "TD" || direction === "LR" || direction === "BT" || direction === "RL") {
+    return direction;
+  }
+  throw new Error(
+    `invalid diagram direction ${String(direction)}; expected one of: TD, LR, BT, RL`
+  );
+}
+function escapeRegexLiteral(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function globToRegex(pattern) {
+  let re = "^";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      re += ".*";
+      continue;
+    }
+    if (ch === "?") {
+      re += ".";
+      continue;
+    }
+    if (ch === "[") {
+      const end = pattern.indexOf("]", i + 1);
+      if (end <= i + 1) {
+        re += "\\[";
+        continue;
+      }
+      let cls = pattern.slice(i + 1, end);
+      if (cls.startsWith("!")) cls = `^${cls.slice(1)}`;
+      cls = cls.replace(/\\/g, "\\\\");
+      re += `[${cls}]`;
+      i = end;
+      continue;
+    }
+    re += escapeRegexLiteral(ch);
+  }
+  re += "$";
+  return new RegExp(re);
+}
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.buf = new Array(capacity);
+  }
+  buf;
+  head = 0;
+  _size = 0;
+  get size() {
+    return this._size;
+  }
+  push(item) {
+    const idx = (this.head + this._size) % this.capacity;
+    this.buf[idx] = item;
+    if (this._size < this.capacity) this._size++;
+    else this.head = (this.head + 1) % this.capacity;
+  }
+  toArray() {
+    const result = [];
+    for (let i = 0; i < this._size; i++) result.push(this.buf[(this.head + i) % this.capacity]);
+    return result;
+  }
+};
+var SPY_ANSI_THEME = {
+  data: "\x1B[32m",
+  dirty: "\x1B[33m",
+  resolved: "\x1B[36m",
+  complete: "\x1B[34m",
+  error: "\x1B[31m",
+  derived: "\x1B[35m",
+  path: "\x1B[90m",
+  reset: "\x1B[0m"
+};
+var SPY_NO_COLOR_THEME = {
+  data: "",
+  dirty: "",
+  resolved: "",
+  complete: "",
+  error: "",
+  derived: "",
+  path: "",
+  reset: ""
+};
+function describeData(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || value == null)
+    return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function resolveSpyTheme(theme) {
+  if (theme === "none") return SPY_NO_COLOR_THEME;
+  if (theme === "ansi" || theme == null) return SPY_ANSI_THEME;
+  return {
+    data: theme.data ?? "",
+    dirty: theme.dirty ?? "",
+    resolved: theme.resolved ?? "",
+    complete: theme.complete ?? "",
+    error: theme.error ?? "",
+    derived: theme.derived ?? "",
+    path: theme.path ?? "",
+    reset: theme.reset ?? ""
+  };
+}
+function assertLocalName(name, graphName, label) {
+  if (name === "") {
+    throw new Error(`Graph "${graphName}": ${label} name must be non-empty`);
+  }
+}
+function assertNoPathSep(name, graphName, label) {
+  if (name.includes(PATH_SEP)) {
+    throw new Error(
+      `Graph "${graphName}": ${label} "${name}" must not contain '${PATH_SEP}' (path separator)`
+    );
+  }
+}
+function assertNotReservedMetaSegment(name, graphName, label) {
+  if (name === GRAPH_META_SEGMENT) {
+    throw new Error(
+      `Graph "${graphName}": ${label} name "${GRAPH_META_SEGMENT}" is reserved for meta companion paths`
+    );
+  }
+}
+function assertConnectPathNotMeta(path, graphName) {
+  if (path.split(PATH_SEP).includes(GRAPH_META_SEGMENT)) {
+    throw new Error(
+      `Graph "${graphName}": connect/disconnect endpoints must be registered graph nodes, not meta paths (got "${path}")`
+    );
+  }
+}
+function splitPath(path, graphName) {
+  if (path === "") {
+    throw new Error(`Graph "${graphName}": resolve path must be non-empty`);
+  }
+  const segments = path.split(PATH_SEP);
+  for (const s of segments) {
+    if (s === "") {
+      throw new Error(`Graph "${graphName}": resolve path has empty segment`);
+    }
+  }
+  return segments;
+}
+function edgeKey(from, to) {
+  return `${from}	${to}`;
+}
+function parseEdgeKey(key) {
+  const i = key.indexOf("	");
+  return [key.slice(0, i), key.slice(i + 1)];
+}
+var META_FILTERED_TYPES = /* @__PURE__ */ new Set([TEARDOWN, INVALIDATE, COMPLETE, ERROR]);
+function filterMetaMessages(messages) {
+  const kept = messages.filter((m) => !META_FILTERED_TYPES.has(m[0]));
+  return kept;
+}
+function teardownMountedGraph(root) {
+  for (const child of root._mounts.values()) {
+    teardownMountedGraph(child);
+  }
+  for (const n of root._nodes.values()) {
+    n.down([[TEARDOWN]], { internal: true });
+  }
+}
+var Graph = class _Graph {
+  static _factories = [];
+  name;
+  opts;
+  /** @internal — exposed for {@link teardownMountedGraph} and cross-graph helpers. */
+  _nodes = /* @__PURE__ */ new Map();
+  _edges = /* @__PURE__ */ new Set();
+  /** @internal — exposed for {@link teardownMountedGraph}. */
+  _mounts = /* @__PURE__ */ new Map();
+  _autoCheckpointDisposers = /* @__PURE__ */ new Set();
+  _defaultVersioningLevel;
+  static registerFactory(pattern, factory) {
+    if (!pattern) {
+      throw new Error("Graph.registerFactory requires a non-empty pattern");
+    }
+    _Graph.unregisterFactory(pattern);
+    _Graph._factories.push({ pattern, re: globToRegex(pattern), factory });
+  }
+  static unregisterFactory(pattern) {
+    const i = _Graph._factories.findIndex((entry) => entry.pattern === pattern);
+    if (i >= 0) _Graph._factories.splice(i, 1);
+  }
+  /**
+   * @param name - Non-empty graph id (must not contain `::`).
+   * @param opts - Reserved for future hooks; currently unused.
+   */
+  constructor(name, opts) {
+    if (name === "") {
+      throw new Error("Graph name must be non-empty");
+    }
+    if (name.includes(PATH_SEP)) {
+      throw new Error(`Graph name must not contain '${PATH_SEP}' (got "${name}")`);
+    }
+    this.name = name;
+    this.opts = opts ?? {};
+  }
+  static _factoryForPath(path) {
+    for (let i = _Graph._factories.length - 1; i >= 0; i -= 1) {
+      const entry = _Graph._factories[i];
+      if (entry.re.test(path)) return entry.factory;
+    }
+    return void 0;
+  }
+  static _ownerForPath(root, path) {
+    const segments = path.split(PATH_SEP);
+    const local = segments.pop();
+    if (local == null || local.length === 0) {
+      throw new Error(`invalid snapshot path "${path}"`);
+    }
+    let owner = root;
+    for (const seg of segments) {
+      const next = owner._mounts.get(seg);
+      if (!next) throw new Error(`unknown mount "${seg}" in path "${path}"`);
+      owner = next;
+    }
+    return [owner, local];
+  }
+  /**
+   * Graphs reachable from this instance via nested {@link Graph.mount} (includes `this`).
+   */
+  _graphsReachableViaMounts(seen = /* @__PURE__ */ new Set()) {
+    if (seen.has(this)) return seen;
+    seen.add(this);
+    for (const child of this._mounts.values()) {
+      child._graphsReachableViaMounts(seen);
+    }
+    return seen;
+  }
+  /**
+   * Resolve an endpoint: returns `[owningGraph, localName, node]`.
+   * Accepts both local names and `::` qualified paths.
+   */
+  _resolveEndpoint(path) {
+    if (!path.includes(PATH_SEP)) {
+      const n = this._nodes.get(path);
+      if (!n) {
+        throw new Error(`Graph "${this.name}": unknown node "${path}"`);
+      }
+      return [this, path, n];
+    }
+    const segments = splitPath(path, this.name);
+    return this._resolveEndpointFromSegments(segments, path);
+  }
+  _resolveEndpointFromSegments(segments, fullPath) {
+    const head = segments[0];
+    const rest = segments.slice(1);
+    if (rest.length === 0) {
+      const n = this._nodes.get(head);
+      if (n) return [this, head, n];
+      throw new Error(`Graph "${this.name}": unknown node "${head}" (from path "${fullPath}")`);
+    }
+    const localN = this._nodes.get(head);
+    if (localN && rest.length > 0 && rest[0] === GRAPH_META_SEGMENT) {
+      return this._resolveMetaEndpointKeys(localN, head, rest, fullPath);
+    }
+    const child = this._mounts.get(head);
+    if (!child) {
+      if (this._nodes.has(head)) {
+        throw new Error(
+          `Graph "${this.name}": "${head}" is a node; trailing path "${rest.join(PATH_SEP)}" is invalid`
+        );
+      }
+      throw new Error(`Graph "${this.name}": unknown mount or node "${head}"`);
+    }
+    return child._resolveEndpointFromSegments(rest, fullPath);
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Node registry
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Registers a node under a local name. Fails if the name is already used,
+   * reserved by a mount, or the same node instance is already registered.
+   *
+   * @param name - Local key (no `::`).
+   * @param node - Node instance to own.
+   */
+  add(name, node) {
+    assertLocalName(name, this.name, "add");
+    assertNoPathSep(name, this.name, "add");
+    assertNotReservedMetaSegment(name, this.name, "node");
+    if (this._mounts.has(name)) {
+      throw new Error(`Graph "${this.name}": name "${name}" is already a mount point`);
+    }
+    if (this._nodes.has(name)) {
+      throw new Error(`Graph "${this.name}": node "${name}" already exists`);
+    }
+    for (const [existingName, existing] of this._nodes) {
+      if (existing === node) {
+        throw new Error(
+          `Graph "${this.name}": node instance already registered as "${existingName}"`
+        );
+      }
+    }
+    this._nodes.set(name, node);
+    if (node instanceof NodeImpl) {
+      node._assignRegistryName(name);
+      if (this._defaultVersioningLevel != null) {
+        node._applyVersioning(this._defaultVersioningLevel);
+      }
+    }
+  }
+  /**
+   * Set a default versioning level for all nodes added to this graph (roadmap §6.0).
+   *
+   * Nodes already registered are retroactively upgraded. Nodes added later via
+   * {@link add} will inherit this level unless they already have versioning.
+   *
+   * **Scope:** Does not propagate to mounted subgraphs. Call `setVersioning`
+   * on each child graph separately if needed.
+   *
+   * @param level - `0` for V0, `1` for V1, or `undefined` to clear.
+   */
+  setVersioning(level) {
+    this._defaultVersioningLevel = level;
+    if (level == null) return;
+    for (const n of this._nodes.values()) {
+      if (n instanceof NodeImpl) {
+        n._applyVersioning(level);
+      }
+    }
+  }
+  /**
+   * Unregisters a node or unmounts a subgraph, drops incident edges, and sends
+   * `[[TEARDOWN]]` to the removed node or recursively through the mounted subtree (§3.2).
+   *
+   * @param name - Local mount or node name.
+   */
+  remove(name) {
+    assertLocalName(name, this.name, "remove");
+    assertNoPathSep(name, this.name, "remove");
+    const child = this._mounts.get(name);
+    if (child) {
+      this._mounts.delete(name);
+      const prefix = `${name}${PATH_SEP}`;
+      for (const key of [...this._edges]) {
+        const [from, to] = parseEdgeKey(key);
+        if (from === name || to === name || from.startsWith(prefix) || to.startsWith(prefix)) {
+          this._edges.delete(key);
+        }
+      }
+      teardownMountedGraph(child);
+      return;
+    }
+    const node = this._nodes.get(name);
+    if (!node) {
+      throw new Error(`Graph "${this.name}": unknown node or mount "${name}"`);
+    }
+    this._nodes.delete(name);
+    for (const key of [...this._edges]) {
+      const [from, to] = parseEdgeKey(key);
+      if (from === name || to === name) this._edges.delete(key);
+    }
+    node.down([[TEARDOWN]], { internal: true });
+  }
+  /**
+   * Returns a node by local name or `::` qualified path.
+   * Local names are looked up directly; paths with `::` delegate to {@link resolve}.
+   *
+   * @param name - Local name or qualified path.
+   */
+  node(name) {
+    if (name === "") {
+      throw new Error(`Graph "${this.name}": node name must be non-empty`);
+    }
+    if (name.includes(PATH_SEP)) {
+      return this.resolve(name);
+    }
+    const n = this._nodes.get(name);
+    if (!n) {
+      throw new Error(`Graph "${this.name}": unknown node "${name}"`);
+    }
+    return n;
+  }
+  /**
+   * Reads `graph.node(name).get()` — accepts `::` qualified paths (§3.2).
+   *
+   * @param name - Local name or qualified path.
+   * @returns Cached value or `undefined`.
+   */
+  get(name) {
+    return this.node(name).get();
+  }
+  /**
+   * Shorthand for `graph.node(name).down([[DATA, value]], { actor })` — accepts `::` qualified paths (§3.2).
+   *
+   * @param name - Local name or qualified path.
+   * @param value - Next `DATA` payload.
+   * @param options - Optional `actor` and `internal` guard bypass.
+   */
+  set(name, value, options) {
+    const internal = options?.internal === true;
+    this.node(name).down([[DATA, value]], {
+      actor: options?.actor,
+      internal,
+      delivery: "write"
+    });
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Edges
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Record a wire from `fromPath` → `toPath` (§3.3). Accepts local names or
+   * `::` qualified paths. The target must be a {@link NodeImpl} whose `_deps`
+   * includes the source node (same reference). Idempotent.
+   *
+   * Same-owner edges are stored on the owning child graph; cross-subgraph edges
+   * are stored on this (parent) graph's registry.
+   *
+   * @param fromPath - Source endpoint (local or qualified).
+   * @param toPath - Target endpoint whose deps already include the source node.
+   */
+  connect(fromPath, toPath) {
+    if (!fromPath || !toPath) {
+      throw new Error(`Graph "${this.name}": connect paths must be non-empty`);
+    }
+    assertConnectPathNotMeta(fromPath, this.name);
+    assertConnectPathNotMeta(toPath, this.name);
+    const [fromGraph, fromLocal, fromNode] = this._resolveEndpoint(fromPath);
+    const [toGraph, toLocal, toNode] = this._resolveEndpoint(toPath);
+    if (fromNode === toNode) {
+      throw new Error(`Graph "${this.name}": cannot connect a node to itself`);
+    }
+    if (!(toNode instanceof NodeImpl)) {
+      throw new Error(
+        `Graph "${this.name}": connect(${fromPath}, ${toPath}) requires the target to be a graphrefly NodeImpl so deps can be validated`
+      );
+    }
+    if (!toNode._deps.includes(fromNode)) {
+      throw new Error(
+        `Graph "${this.name}": connect(${fromPath}, ${toPath}) \u2014 target must include source in its constructor deps (same node reference)`
+      );
+    }
+    if (fromGraph === toGraph) {
+      const key = edgeKey(fromLocal, toLocal);
+      fromGraph._edges.add(key);
+    } else {
+      const key = edgeKey(fromPath, toPath);
+      this._edges.add(key);
+    }
+  }
+  /**
+   * Remove a registered edge (§3.3). Accepts local names or `::` qualified paths.
+   *
+   * **Registry-only (§C resolved):** This drops the edge from the graph's edge
+   * registry only. It does **not** mutate the target node's constructor-time
+   * dependency list, bitmasks, or upstream subscriptions. Message flow follows
+   * constructor-time deps, not the edge registry. For runtime dep rewiring, use
+   * {@link dynamicNode}.
+   *
+   * @param fromPath - Registered edge tail.
+   * @param toPath - Registered edge head.
+   */
+  disconnect(fromPath, toPath) {
+    if (!fromPath || !toPath) {
+      throw new Error(`Graph "${this.name}": disconnect paths must be non-empty`);
+    }
+    assertConnectPathNotMeta(fromPath, this.name);
+    assertConnectPathNotMeta(toPath, this.name);
+    const [fromGraph, fromLocal] = this._resolveEndpoint(fromPath);
+    const [toGraph, toLocal] = this._resolveEndpoint(toPath);
+    if (fromGraph === toGraph) {
+      const key = edgeKey(fromLocal, toLocal);
+      if (!fromGraph._edges.delete(key)) {
+        throw new Error(`Graph "${this.name}": no registered edge ${fromPath} \u2192 ${toPath}`);
+      }
+    } else {
+      const key = edgeKey(fromPath, toPath);
+      if (!this._edges.delete(key)) {
+        throw new Error(`Graph "${this.name}": no registered edge ${fromPath} \u2192 ${toPath}`);
+      }
+    }
+  }
+  /**
+   * Returns registered `[from, to]` edge pairs (read-only snapshot).
+   *
+   * @returns Edge pairs recorded on this graph instance’s local `_edges` set.
+   */
+  edges() {
+    const result = [];
+    for (const key of this._edges) {
+      result.push(parseEdgeKey(key));
+    }
+    return result;
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Composition
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Embed a child graph at a local mount name (§3.4). Child nodes are reachable via
+   * {@link Graph.resolve} using `::` delimited paths (§3.5). Lifecycle
+   * {@link Graph.signal} visits mounted subgraphs recursively.
+   *
+   * Rejects: same name as existing node or mount, self-mount, mount cycles,
+   * and the same child graph instance mounted twice on one parent.
+   *
+   * @param name - Local mount point.
+   * @param child - Nested `Graph` instance.
+   */
+  mount(name, child) {
+    assertLocalName(name, this.name, "mount");
+    assertNoPathSep(name, this.name, "mount");
+    assertNotReservedMetaSegment(name, this.name, "mount");
+    if (this._nodes.has(name)) {
+      throw new Error(
+        `Graph "${this.name}": cannot mount at "${name}" \u2014 node with that name exists`
+      );
+    }
+    if (this._mounts.has(name)) {
+      throw new Error(`Graph "${this.name}": mount "${name}" already exists`);
+    }
+    if (child === this) {
+      throw new Error(`Graph "${this.name}": cannot mount a graph into itself`);
+    }
+    for (const existing of this._mounts.values()) {
+      if (existing === child) {
+        throw new Error(`Graph "${this.name}": this child graph is already mounted on this graph`);
+      }
+    }
+    if (child._graphsReachableViaMounts().has(this)) {
+      throw new Error(`Graph "${this.name}": mount("${name}", \u2026) would create a mount cycle`);
+    }
+    this._mounts.set(name, child);
+  }
+  /**
+   * Look up a node by qualified path (§3.5). Segments are separated by `::`.
+   *
+   * If the first segment equals this graph's {@link Graph.name}, it is stripped
+   * (so `root.resolve("app::a")` works when `root.name === "app"`).
+   *
+   * @param path - Qualified `::` path or local name.
+   * @returns The resolved `Node`.
+   */
+  resolve(path) {
+    let segments = splitPath(path, this.name);
+    if (segments[0] === this.name) {
+      segments = segments.slice(1);
+      if (segments.length === 0) {
+        throw new Error(`Graph "${this.name}": resolve path ends at graph name only`);
+      }
+    }
+    return this._resolveFromSegments(segments);
+  }
+  _resolveFromSegments(segments) {
+    const head = segments[0];
+    const rest = segments.slice(1);
+    if (rest.length === 0) {
+      const n = this._nodes.get(head);
+      if (n) return n;
+      if (this._mounts.has(head)) {
+        throw new Error(
+          `Graph "${this.name}": path ends at subgraph "${head}" \u2014 not a node (GRAPHREFLY-SPEC \xA73.5)`
+        );
+      }
+      throw new Error(`Graph "${this.name}": unknown name "${head}"`);
+    }
+    const localN = this._nodes.get(head);
+    if (localN && rest.length > 0 && rest[0] === GRAPH_META_SEGMENT) {
+      return this._resolveMetaChainFromNode(localN, rest, segments.join(PATH_SEP));
+    }
+    const child = this._mounts.get(head);
+    if (!child) {
+      if (this._nodes.has(head)) {
+        throw new Error(
+          `Graph "${this.name}": "${head}" is a node; trailing path "${rest.join(PATH_SEP)}" is invalid`
+        );
+      }
+      throw new Error(`Graph "${this.name}": unknown mount or node "${head}"`);
+    }
+    return child.resolve(rest.join(PATH_SEP));
+  }
+  /**
+   * Resolve `::__meta__::key` segments from a registered primary node (possibly chained).
+   */
+  _resolveMetaChainFromNode(n, parts, fullPath) {
+    let current = n;
+    let i = 0;
+    const p = [...parts];
+    while (i < p.length) {
+      if (p[i] !== GRAPH_META_SEGMENT) {
+        throw new Error(
+          `Graph "${this.name}": expected ${GRAPH_META_SEGMENT} segment in meta path "${fullPath}"`
+        );
+      }
+      if (i + 1 >= p.length) {
+        throw new Error(
+          `Graph "${this.name}": meta path requires a key after ${GRAPH_META_SEGMENT} in "${fullPath}"`
+        );
+      }
+      const key = p[i + 1];
+      const next = current.meta[key];
+      if (!next) {
+        throw new Error(`Graph "${this.name}": unknown meta "${key}" in path "${fullPath}"`);
+      }
+      current = next;
+      i += 2;
+    }
+    return current;
+  }
+  _resolveMetaEndpointKeys(baseNode, baseLocalKey, parts, fullPath) {
+    let current = baseNode;
+    let localKey = baseLocalKey;
+    let i = 0;
+    const p = [...parts];
+    while (i < p.length) {
+      if (p[i] !== GRAPH_META_SEGMENT) {
+        throw new Error(
+          `Graph "${this.name}": expected ${GRAPH_META_SEGMENT} segment in meta path "${fullPath}"`
+        );
+      }
+      if (i + 1 >= p.length) {
+        throw new Error(
+          `Graph "${this.name}": meta path requires a key after ${GRAPH_META_SEGMENT} in "${fullPath}"`
+        );
+      }
+      const metaKey = p[i + 1];
+      const next = current.meta[metaKey];
+      if (!next) {
+        throw new Error(
+          `Graph "${this.name}": unknown meta "${metaKey}" on node (in "${fullPath}")`
+        );
+      }
+      localKey = `${localKey}${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}${metaKey}`;
+      current = next;
+      i += 2;
+    }
+    return [this, localKey, current];
+  }
+  /**
+   * Deliver a message batch to every registered node in this graph and, recursively,
+   * in mounted child graphs (§3.7). Recurses into mounts first, then delivers to
+   * local nodes (sorted by name). Each {@link Node} receives at most one delivery
+   * per call (deduped by reference).
+   *
+   * Companion `meta` nodes receive the same batch for control-plane types (e.g.
+   * PAUSE) that the primary does not forward. **TEARDOWN-only** batches skip the
+   * extra meta pass — the primary’s `down()` already cascades TEARDOWN to meta.
+   *
+   * @param messages - Batch to deliver to every registered node (and mounts, recursively).
+   * @param options - Optional `actor` / `internal` for transport.
+   */
+  signal(messages, options) {
+    this._signalDeliver(messages, options ?? {}, /* @__PURE__ */ new Set());
+  }
+  _signalDeliver(messages, opts, vis) {
+    for (const sub of this._mounts.values()) {
+      sub._signalDeliver(messages, opts, vis);
+    }
+    const internal = opts.internal === true;
+    const downOpts = internal ? { internal: true } : { actor: opts.actor, delivery: "signal" };
+    const metaMessages = filterMetaMessages(messages);
+    for (const localName of [...this._nodes.keys()].sort()) {
+      const n = this._nodes.get(localName);
+      if (vis.has(n)) continue;
+      vis.add(n);
+      n.down(messages, downOpts);
+      if (metaMessages.length === 0) continue;
+      this._signalMetaSubtree(n, metaMessages, vis, downOpts);
+    }
+  }
+  _signalMetaSubtree(root, messages, vis, downOpts) {
+    for (const mk of Object.keys(root.meta).sort()) {
+      const mnode = root.meta[mk];
+      if (vis.has(mnode)) continue;
+      vis.add(mnode);
+      mnode.down(messages, downOpts);
+      this._signalMetaSubtree(mnode, messages, vis, downOpts);
+    }
+  }
+  /**
+   * Static structure snapshot: qualified node keys, edges, mount names (GRAPHREFLY-SPEC §3.6, Appendix B).
+   *
+   * @param options - Optional `actor` for guard-scoped visibility and/or `filter` for selective output.
+   * @returns JSON-shaped describe payload for this graph tree.
+   *
+   * @example
+   * ```ts
+   * graph.describe()                                         // full snapshot
+   * graph.describe({ actor: llm })                           // guard-scoped
+   * graph.describe({ filter: { status: "errored" } })        // only errored nodes
+   * graph.describe({ filter: (n) => n.type === "state" })    // predicate filter
+   * ```
+   */
+  describe(options) {
+    const actor = options?.actor;
+    const filter = options?.filter;
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    const nodeToPath = /* @__PURE__ */ new Map();
+    for (const [p, n] of targets) {
+      nodeToPath.set(n, p);
+    }
+    const nodes = {};
+    for (const [p, n] of targets) {
+      if (actor != null && !n.allowsObserve(actor)) continue;
+      const raw = describeNode(n);
+      const deps = n instanceof NodeImpl ? n._deps.map((d) => nodeToPath.get(d) ?? d.name ?? "") : [];
+      const { name: _name, ...rest } = raw;
+      const entry = { ...rest, deps };
+      if (filter != null) {
+        if (typeof filter === "function") {
+          const fn = filter;
+          const pass = fn.length >= 2 ? fn(p, entry) : fn(entry);
+          if (!pass) continue;
+        } else {
+          let match = true;
+          for (const [fk, fv] of Object.entries(filter)) {
+            const normalizedKey = fk === "deps_includes" ? "depsIncludes" : fk === "meta_has" ? "metaHas" : fk;
+            if (normalizedKey === "depsIncludes") {
+              if (!entry.deps.includes(String(fv))) {
+                match = false;
+                break;
+              }
+              continue;
+            }
+            if (normalizedKey === "metaHas") {
+              if (!Object.hasOwn(entry.meta, String(fv))) {
+                match = false;
+                break;
+              }
+              continue;
+            }
+            if (entry[normalizedKey] !== fv) {
+              match = false;
+              break;
+            }
+          }
+          if (!match) continue;
+        }
+      }
+      nodes[p] = entry;
+    }
+    const nodeKeys = new Set(Object.keys(nodes));
+    let edges = this._collectAllEdges("");
+    if (actor != null || filter != null) {
+      edges = edges.filter((e) => nodeKeys.has(e.from) && nodeKeys.has(e.to));
+    }
+    edges.sort((a, b) => {
+      if (a.from < b.from) return -1;
+      if (a.from > b.from) return 1;
+      if (a.to < b.to) return -1;
+      if (a.to > b.to) return 1;
+      return 0;
+    });
+    const allSubgraphs = this._collectSubgraphs("");
+    const subgraphs = actor != null || filter != null ? allSubgraphs.filter((sg) => {
+      const prefix = `${sg}${PATH_SEP}`;
+      return [...nodeKeys].some((k) => k === sg || k.startsWith(prefix));
+    }) : allSubgraphs;
+    return {
+      name: this.name,
+      nodes,
+      edges,
+      subgraphs
+    };
+  }
+  _collectSubgraphs(prefix) {
+    const out = [];
+    for (const m of [...this._mounts.keys()].sort()) {
+      const q = prefix === "" ? m : `${prefix}${m}`;
+      out.push(q);
+      out.push(...this._mounts.get(m)._collectSubgraphs(`${q}${PATH_SEP}`));
+    }
+    return out;
+  }
+  _collectAllEdges(prefix) {
+    const out = [];
+    for (const m of [...this._mounts.keys()].sort()) {
+      const p2 = prefix === "" ? m : `${prefix}${PATH_SEP}${m}`;
+      out.push(...this._mounts.get(m)._collectAllEdges(p2));
+    }
+    for (const [f, t] of this.edges()) {
+      out.push({
+        from: this._qualifyEdgeEndpoint(f, prefix),
+        to: this._qualifyEdgeEndpoint(t, prefix)
+      });
+    }
+    return out;
+  }
+  _qualifyEdgeEndpoint(part, prefix) {
+    if (part.includes(PATH_SEP)) return part;
+    return prefix === "" ? part : `${prefix}${PATH_SEP}${part}`;
+  }
+  _collectObserveTargets(prefix, out) {
+    for (const m of [...this._mounts.keys()].sort()) {
+      const p2 = prefix === "" ? m : `${prefix}${PATH_SEP}${m}`;
+      this._mounts.get(m)._collectObserveTargets(p2, out);
+    }
+    for (const loc of [...this._nodes.keys()].sort()) {
+      const n = this._nodes.get(loc);
+      const p = prefix === "" ? loc : `${prefix}${PATH_SEP}${loc}`;
+      out.push([p, n]);
+      this._appendMetaObserveTargets(p, n, out);
+    }
+  }
+  _appendMetaObserveTargets(basePath, n, out) {
+    for (const mk of Object.keys(n.meta).sort()) {
+      const m = n.meta[mk];
+      const mp = `${basePath}${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}${mk}`;
+      out.push([mp, m]);
+      this._appendMetaObserveTargets(mp, m, out);
+    }
+  }
+  observe(pathOrOpts, options) {
+    if (typeof pathOrOpts === "string") {
+      const path = pathOrOpts;
+      const actor2 = options?.actor;
+      const target = this.resolve(path);
+      if (actor2 != null && !target.allowsObserve(actor2)) {
+        throw new GuardDenied({ actor: actor2, action: "observe", nodeName: path });
+      }
+      const wantsStructured2 = options?.structured === true || options?.timeline === true || options?.causal === true || options?.derived === true;
+      if (wantsStructured2 && _Graph.inspectorEnabled) {
+        return this._createObserveResult(path, target, options);
+      }
+      return {
+        subscribe(sink) {
+          return target.subscribe(sink);
+        },
+        up(messages) {
+          try {
+            target.up?.(messages);
+          } catch (err) {
+            if (err instanceof GuardDenied) return;
+            throw err;
+          }
+        }
+      };
+    }
+    const opts = pathOrOpts;
+    const actor = opts?.actor;
+    const wantsStructured = opts?.structured === true || opts?.timeline === true || opts?.causal === true || opts?.derived === true;
+    if (wantsStructured && _Graph.inspectorEnabled) {
+      return this._createObserveResultForAll(opts ?? {});
+    }
+    return {
+      subscribe: (sink) => {
+        const targets = [];
+        this._collectObserveTargets("", targets);
+        targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+        const picked = actor == null ? targets : targets.filter(([, nd]) => nd.allowsObserve(actor));
+        const unsubs = picked.map(
+          ([p, nd]) => nd.subscribe((msgs) => {
+            sink(p, msgs);
+          })
+        );
+        return () => {
+          for (const u of unsubs) u();
+        };
+      },
+      up: (upPath, messages) => {
+        try {
+          const nd = this.resolve(upPath);
+          nd.up?.(messages);
+        } catch (err) {
+          if (err instanceof GuardDenied) return;
+          throw err;
+        }
+      }
+    };
+  }
+  _createObserveResult(path, target, options) {
+    const timeline = options.timeline === true;
+    const causal = options.causal === true;
+    const derived = options.derived === true;
+    const result = {
+      values: {},
+      dirtyCount: 0,
+      resolvedCount: 0,
+      events: [],
+      completedCleanly: false,
+      errored: false
+    };
+    let lastTriggerDepIndex;
+    let lastRunDepValues;
+    let detachInspectorHook;
+    if ((causal || derived) && target instanceof NodeImpl) {
+      detachInspectorHook = target._setInspectorHook((event) => {
+        if (event.kind === "dep_message") {
+          lastTriggerDepIndex = event.depIndex;
+          return;
+        }
+        lastRunDepValues = [...event.depValues];
+        if (derived) {
+          result.events.push({
+            type: "derived",
+            path,
+            dep_values: [...event.depValues],
+            ...timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {}
+          });
+        }
+      });
+    }
+    const unsub = target.subscribe((msgs) => {
+      for (const m of msgs) {
+        const t = m[0];
+        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+        const withCausal = causal && lastRunDepValues != null ? (() => {
+          const triggerDep = lastTriggerDepIndex != null && lastTriggerDepIndex >= 0 && target instanceof NodeImpl ? target._deps[lastTriggerDepIndex] : void 0;
+          const tv = triggerDep?.v;
+          return {
+            trigger_dep_index: lastTriggerDepIndex,
+            trigger_dep_name: triggerDep?.name,
+            ...tv != null ? { trigger_version: { id: tv.id, version: tv.version } } : {},
+            dep_values: [...lastRunDepValues]
+          };
+        })() : {};
+        if (t === DATA) {
+          result.values[path] = m[1];
+          result.events.push({ type: "data", path, data: m[1], ...base, ...withCausal });
+        } else if (t === DIRTY) {
+          result.dirtyCount++;
+          result.events.push({ type: "dirty", path, ...base });
+        } else if (t === RESOLVED) {
+          result.resolvedCount++;
+          result.events.push({ type: "resolved", path, ...base, ...withCausal });
+        } else if (t === COMPLETE) {
+          if (!result.errored) result.completedCleanly = true;
+          result.events.push({ type: "complete", path, ...base });
+        } else if (t === ERROR) {
+          result.errored = true;
+          result.events.push({ type: "error", path, data: m[1], ...base });
+        }
+      }
+    });
+    return {
+      get values() {
+        return result.values;
+      },
+      get dirtyCount() {
+        return result.dirtyCount;
+      },
+      get resolvedCount() {
+        return result.resolvedCount;
+      },
+      get events() {
+        return result.events;
+      },
+      get completedCleanly() {
+        return result.completedCleanly;
+      },
+      get errored() {
+        return result.errored;
+      },
+      dispose() {
+        unsub();
+        detachInspectorHook?.();
+      }
+    };
+  }
+  _createObserveResultForAll(options) {
+    const timeline = options.timeline === true;
+    const result = {
+      values: {},
+      dirtyCount: 0,
+      resolvedCount: 0,
+      events: [],
+      completedCleanly: false,
+      errored: false
+    };
+    const actor = options.actor;
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const picked = actor == null ? targets : targets.filter(([, nd]) => nd.allowsObserve(actor));
+    const unsubs = picked.map(
+      ([path, nd]) => nd.subscribe((msgs) => {
+        for (const m of msgs) {
+          const t = m[0];
+          const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+          if (t === DATA) {
+            result.values[path] = m[1];
+            result.events.push({ type: "data", path, data: m[1], ...base });
+          } else if (t === DIRTY) {
+            result.dirtyCount++;
+            result.events.push({ type: "dirty", path, ...base });
+          } else if (t === RESOLVED) {
+            result.resolvedCount++;
+            result.events.push({ type: "resolved", path, ...base });
+          } else if (t === COMPLETE) {
+            if (!result.errored) result.completedCleanly = true;
+            result.events.push({ type: "complete", path, ...base });
+          } else if (t === ERROR) {
+            result.errored = true;
+            result.events.push({ type: "error", path, data: m[1], ...base });
+          }
+        }
+      })
+    );
+    return {
+      get values() {
+        return result.values;
+      },
+      get dirtyCount() {
+        return result.dirtyCount;
+      },
+      get resolvedCount() {
+        return result.resolvedCount;
+      },
+      get events() {
+        return result.events;
+      },
+      get completedCleanly() {
+        return result.completedCleanly;
+      },
+      get errored() {
+        return result.errored;
+      },
+      dispose() {
+        for (const u of unsubs) u();
+      }
+    };
+  }
+  /**
+   * Convenience live debugger over {@link Graph.observe}. Logs protocol events as they flow.
+   *
+   * Supports one-node (`path`) and graph-wide modes, event filtering, and JSON/pretty rendering.
+   * Color themes are built in (`ansi` / `none`) to avoid external dependencies.
+   *
+   * @param options - Spy configuration.
+   * @returns Disposable handle plus a structured observation accumulator.
+   */
+  spy(options = {}) {
+    const include = options.includeTypes ? new Set(options.includeTypes) : null;
+    const exclude = options.excludeTypes ? new Set(options.excludeTypes) : null;
+    const theme = resolveSpyTheme(options.theme);
+    const format = options.format ?? "pretty";
+    const logger = options.logger ?? ((line) => console.log(line));
+    const shouldLog = (type) => {
+      if (include?.has(type) === false) return false;
+      if (exclude?.has(type) === true) return false;
+      return true;
+    };
+    const renderEvent = (event) => {
+      if (format === "json") {
+        try {
+          return JSON.stringify(event);
+        } catch {
+          return JSON.stringify({
+            type: event.type,
+            path: event.path,
+            data: "[unserializable]"
+          });
+        }
+      }
+      const color = theme[event.type] ?? "";
+      const pathPart = event.path ? `${theme.path}${event.path}${theme.reset} ` : "";
+      const dataPart = event.data !== void 0 ? ` ${describeData(event.data)}` : "";
+      const triggerPart = event.trigger_dep_name != null ? ` <- ${event.trigger_dep_name}` : event.trigger_dep_index != null ? ` <- #${event.trigger_dep_index}` : "";
+      const batchPart = event.in_batch ? " [batch]" : "";
+      return `${pathPart}${color}${event.type.toUpperCase()}${theme.reset}${dataPart}${triggerPart}${batchPart}`;
+    };
+    if (!_Graph.inspectorEnabled) {
+      const timeline = options.timeline ?? true;
+      const acc = {
+        values: {},
+        dirtyCount: 0,
+        resolvedCount: 0,
+        events: [],
+        completedCleanly: false,
+        errored: false
+      };
+      let stop2 = () => {
+      };
+      const result2 = {
+        get values() {
+          return acc.values;
+        },
+        get dirtyCount() {
+          return acc.dirtyCount;
+        },
+        get resolvedCount() {
+          return acc.resolvedCount;
+        },
+        get events() {
+          return acc.events;
+        },
+        get completedCleanly() {
+          return acc.completedCleanly;
+        },
+        get errored() {
+          return acc.errored;
+        },
+        dispose() {
+          stop2();
+        }
+      };
+      const pushEvent = (path, message) => {
+        const t = message[0];
+        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+        let event;
+        if (t === DATA) {
+          if (path != null) acc.values[path] = message[1];
+          event = { type: "data", ...path != null ? { path } : {}, data: message[1], ...base };
+        } else if (t === DIRTY) {
+          acc.dirtyCount += 1;
+          event = { type: "dirty", ...path != null ? { path } : {}, ...base };
+        } else if (t === RESOLVED) {
+          acc.resolvedCount += 1;
+          event = { type: "resolved", ...path != null ? { path } : {}, ...base };
+        } else if (t === COMPLETE) {
+          if (!acc.errored) acc.completedCleanly = true;
+          event = { type: "complete", ...path != null ? { path } : {}, ...base };
+        } else if (t === ERROR) {
+          acc.errored = true;
+          event = {
+            type: "error",
+            ...path != null ? { path } : {},
+            data: message[1],
+            ...base
+          };
+        }
+        if (!event) return;
+        acc.events.push(event);
+        if (!shouldLog(event.type)) return;
+        logger(renderEvent(event), event);
+      };
+      if (options.path != null) {
+        const stream2 = this.observe(options.path, {
+          actor: options.actor,
+          structured: false
+        });
+        stop2 = stream2.subscribe((messages) => {
+          for (const m of messages) {
+            pushEvent(options.path, m);
+          }
+        });
+      } else {
+        const stream2 = this.observe({ actor: options.actor, structured: false });
+        stop2 = stream2.subscribe((path, messages) => {
+          for (const m of messages) {
+            pushEvent(path, m);
+          }
+        });
+      }
+      return {
+        result: result2,
+        dispose() {
+          result2.dispose();
+        }
+      };
+    }
+    const structuredObserveOptions = {
+      actor: options.actor,
+      structured: true,
+      ...options.timeline !== false ? { timeline: true } : {},
+      ...options.causal ? { causal: true } : {},
+      ...options.derived ? { derived: true } : {}
+    };
+    const result = options.path != null ? this.observe(options.path, structuredObserveOptions) : this.observe(structuredObserveOptions);
+    let cursor = 0;
+    const flushNewEvents = () => {
+      const nextEvents = result.events.slice(cursor);
+      cursor = result.events.length;
+      for (const event of nextEvents) {
+        if (!shouldLog(event.type)) continue;
+        logger(renderEvent(event), event);
+      }
+    };
+    const stream = options.path != null ? this.observe(options.path, { actor: options.actor, structured: false }) : this.observe({ actor: options.actor, structured: false });
+    const stop = options.path != null ? stream.subscribe((messages) => {
+      if (messages.length > 0) {
+        flushNewEvents();
+      }
+    }) : stream.subscribe((_path, messages) => {
+      if (messages.length > 0) {
+        flushNewEvents();
+      }
+    });
+    return {
+      result,
+      dispose() {
+        stop();
+        flushNewEvents();
+        result.dispose();
+      }
+    };
+  }
+  /**
+   * CLI/debug-friendly graph dump built on {@link Graph.describe}.
+   *
+   * @param options - Optional actor/filter/format toggles.
+   * @returns Rendered graph text.
+   */
+  dumpGraph(options = {}) {
+    const described = this.describe({
+      actor: options.actor,
+      filter: options.filter
+    });
+    const includeEdges = options.includeEdges ?? true;
+    const includeSubgraphs = options.includeSubgraphs ?? true;
+    if (options.format === "json") {
+      const payload = {
+        name: described.name,
+        nodes: described.nodes,
+        edges: includeEdges ? described.edges : [],
+        subgraphs: includeSubgraphs ? described.subgraphs : []
+      };
+      const text2 = JSON.stringify(sortJsonValue(payload), null, options.indent ?? 2);
+      options.logger?.(text2);
+      return text2;
+    }
+    const lines = [];
+    lines.push(`Graph ${described.name}`);
+    lines.push("Nodes:");
+    for (const path of Object.keys(described.nodes).sort()) {
+      const n = described.nodes[path];
+      lines.push(`- ${path} (${n.type}/${n.status}): ${describeData(n.value)}`);
+    }
+    if (includeEdges) {
+      lines.push("Edges:");
+      for (const edge of described.edges) {
+        lines.push(`- ${edge.from} -> ${edge.to}`);
+      }
+    }
+    if (includeSubgraphs) {
+      lines.push("Subgraphs:");
+      for (const sg of described.subgraphs) {
+        lines.push(`- ${sg}`);
+      }
+    }
+    const text = lines.join("\n");
+    options.logger?.(text);
+    return text;
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Lifecycle & persistence (§3.7–§3.8)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Sends `[[TEARDOWN]]` to all nodes, then clears registries on this graph and every
+   * mounted subgraph (§3.7). The instance is left empty and may be reused with {@link Graph.add}.
+   */
+  destroy() {
+    this.signal([[TEARDOWN]], { internal: true });
+    for (const dispose of [...this._autoCheckpointDisposers]) {
+      try {
+        dispose();
+      } catch {
+      }
+    }
+    this._autoCheckpointDisposers.clear();
+    for (const child of [...this._mounts.values()]) {
+      child._destroyClearOnly();
+    }
+    this._mounts.clear();
+    this._nodes.clear();
+    this._edges.clear();
+  }
+  /** Clear structure after parent already signaled TEARDOWN through this subtree. */
+  _destroyClearOnly() {
+    for (const child of [...this._mounts.values()]) {
+      child._destroyClearOnly();
+    }
+    this._mounts.clear();
+    this._nodes.clear();
+    this._edges.clear();
+  }
+  /**
+   * Serializes structure and current values to JSON-shaped data (§3.8). Same information
+   * as {@link Graph.describe} plus a `version` field for format evolution.
+   *
+   * @returns Persistable snapshot with sorted keys.
+   */
+  snapshot() {
+    const d = this.describe();
+    const sortedNodes = {};
+    for (const key of Object.keys(d.nodes).sort()) {
+      sortedNodes[key] = d.nodes[key];
+    }
+    const sortedSubgraphs = [...d.subgraphs].sort();
+    return { ...d, version: 1, nodes: sortedNodes, subgraphs: sortedSubgraphs };
+  }
+  /**
+   * Apply persisted values onto an existing graph whose topology matches the snapshot
+   * (§3.8). Only {@link DescribeNodeOutput.type} `state` and `producer` entries with a
+   * `value` field are written; `derived` / `operator` / `effect` are skipped so deps
+   * drive recomputation. Unknown paths are ignored.
+   *
+   * @param data - Snapshot envelope with matching `name` and node slices.
+   * @throws If `data.name` does not equal {@link Graph.name}.
+   */
+  restore(data, options) {
+    parseSnapshotEnvelope(data);
+    if (data.name !== this.name) {
+      throw new Error(
+        `Graph "${this.name}": restore snapshot name "${data.name}" does not match this graph`
+      );
+    }
+    const onlyPatterns = options?.only == null ? null : (Array.isArray(options.only) ? options.only : [options.only]).map((p) => globToRegex(p));
+    for (const path of Object.keys(data.nodes).sort()) {
+      if (onlyPatterns !== null && !onlyPatterns.some((re) => re.test(path))) continue;
+      const slice = data.nodes[path];
+      if (slice === void 0 || slice.value === void 0) continue;
+      if (slice.type === "derived" || slice.type === "operator" || slice.type === "effect") {
+        continue;
+      }
+      try {
+        this.set(path, slice.value);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Creates a graph named from the snapshot, optionally runs `build` to register nodes
+   * and mounts, then {@link Graph.restore} values (§3.8).
+   *
+   * @param data - Snapshot envelope (`version` checked).
+   * @param build - Optional callback to construct topology before values are applied.
+   * @returns Hydrated `Graph` instance.
+   */
+  static fromSnapshot(data, build) {
+    parseSnapshotEnvelope(data);
+    const g = new _Graph(data.name);
+    if (build) {
+      build(g);
+      g.restore(data);
+      return g;
+    }
+    for (const mount of [...data.subgraphs].sort((a, b) => {
+      const da = a.split(PATH_SEP).length;
+      const db = b.split(PATH_SEP).length;
+      if (da !== db) return da - db;
+      if (a < b) return -1;
+      if (a > b) return 1;
+      return 0;
+    })) {
+      const parts = mount.split(PATH_SEP);
+      let target = g;
+      for (const seg of parts) {
+        if (!target._mounts.has(seg)) {
+          target.mount(seg, new _Graph(seg));
+        }
+        target = target._mounts.get(seg);
+      }
+    }
+    const primaryEntries = Object.entries(data.nodes).filter(([path]) => !path.includes(`${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}`)).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const pending = new Map(primaryEntries);
+    const created = /* @__PURE__ */ new Map();
+    let progressed = true;
+    while (pending.size > 0 && progressed) {
+      progressed = false;
+      for (const [path, slice] of [...pending.entries()]) {
+        const deps = slice?.deps ?? [];
+        if (!deps.every((dep) => created.has(dep))) continue;
+        const [owner, localName] = _Graph._ownerForPath(g, path);
+        const meta = { ...slice?.meta ?? {} };
+        const factory = _Graph._factoryForPath(path);
+        let node;
+        if (slice?.type === "state") {
+          node = state(slice.value, { meta });
+        } else {
+          if (factory == null) continue;
+          node = factory(localName, {
+            path,
+            type: slice.type,
+            value: slice.value,
+            meta,
+            deps,
+            resolvedDeps: deps.map((dep) => created.get(dep))
+          });
+        }
+        owner.add(localName, node);
+        created.set(path, node);
+        pending.delete(path);
+        progressed = true;
+      }
+    }
+    if (pending.size > 0) {
+      const unresolved = [...pending.keys()].sort().join(", ");
+      throw new Error(
+        `Graph.fromSnapshot could not reconstruct nodes without build callback: ${unresolved}. Register matching factories with Graph.registerFactory(pattern, factory).`
+      );
+    }
+    for (const edge of data.edges) {
+      try {
+        g.connect(edge.from, edge.to);
+      } catch {
+      }
+    }
+    g.restore(data);
+    return g;
+  }
+  /**
+   * Plain snapshot with **recursively sorted object keys** for deterministic serialization (§3.8).
+   *
+   * @remarks
+   * ECMAScript `JSON.stringify(graph)` invokes this method; it must return a plain object, not an
+   * already-stringified JSON string (otherwise the graph would be double-encoded).
+   * For a single UTF-8 string with a trailing newline (convenient for git), use {@link Graph.toJSONString}.
+   *
+   * @returns Same object as {@link Graph.snapshot}.
+   */
+  toJSON() {
+    return this.snapshot();
+  }
+  /**
+   * Deterministic JSON **text**: `JSON.stringify` of {@link Graph.toJSON} plus a trailing newline (§3.8).
+   *
+   * @returns Stable string suitable for diffs.
+   */
+  toJSONString() {
+    return stableJsonStringify(this.snapshot());
+  }
+  /**
+   * Debounced persistence wired to graph-wide observe stream (spec §3.8 auto-checkpoint).
+   *
+   * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 2 messages
+   * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1 control waves.
+   */
+  autoCheckpoint(adapter, options = {}) {
+    const debounceMs = Math.max(0, options.debounceMs ?? 500);
+    const compactEvery = Math.max(1, options.compactEvery ?? 10);
+    let timer;
+    let seq = 0;
+    let pending = false;
+    let lastDescribe;
+    const flush = () => {
+      timer = void 0;
+      if (!pending) return;
+      pending = false;
+      try {
+        const described = this.describe();
+        const snapshot = { ...described, version: SNAPSHOT_VERSION };
+        seq += 1;
+        const shouldCompact = lastDescribe == null || seq % compactEvery === 0;
+        if (shouldCompact) {
+          adapter.save({ mode: "full", snapshot, seq });
+        } else {
+          const previous = lastDescribe;
+          if (previous == null) return;
+          adapter.save({
+            mode: "diff",
+            diff: _Graph.diff(previous, described),
+            snapshot,
+            seq
+          });
+        }
+        lastDescribe = described;
+      } catch (error) {
+        options.onError?.(error);
+      }
+    };
+    const schedule = () => {
+      pending = true;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = setTimeout(flush, debounceMs);
+    };
+    const off = this.observe().subscribe((path, messages) => {
+      const triggeredByTier = messages.some((m) => messageTier(m[0]) >= 2);
+      if (!triggeredByTier) return;
+      if (options.filter) {
+        const described = this.describe().nodes[path];
+        if (described == null || !options.filter(path, described)) return;
+      }
+      schedule();
+    });
+    const dispose = () => {
+      off();
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      this._autoCheckpointDisposers.delete(dispose);
+    };
+    this._autoCheckpointDisposers.add(dispose);
+    return { dispose };
+  }
+  /**
+   * Export the current graph topology as Mermaid flowchart text.
+   *
+   * Renders qualified node paths and registered edges from {@link Graph.describe}.
+   *
+   * @param options - Optional diagram direction (`LR` by default).
+   * @returns Mermaid flowchart source.
+   */
+  toMermaid(options) {
+    const direction = normalizeDiagramDirection(options?.direction);
+    const described = this.describe();
+    const paths = Object.keys(described.nodes).sort();
+    const ids = /* @__PURE__ */ new Map();
+    for (let i = 0; i < paths.length; i += 1) {
+      ids.set(paths[i], `n${i}`);
+    }
+    const lines = [`flowchart ${direction}`];
+    for (const path of paths) {
+      const id = ids.get(path);
+      lines.push(`  ${id}["${escapeMermaidLabel(path)}"]`);
+    }
+    for (const [from, to] of collectDiagramArrows(described)) {
+      const fromId = ids.get(from);
+      const toId = ids.get(to);
+      if (!fromId || !toId) continue;
+      lines.push(`  ${fromId} --> ${toId}`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Export the current graph topology as D2 diagram text.
+   *
+   * Renders qualified node paths, constructor deps, and registered edges from {@link Graph.describe}.
+   *
+   * @param options - Optional diagram direction (`LR` by default).
+   * @returns D2 source text.
+   */
+  toD2(options) {
+    const direction = normalizeDiagramDirection(options?.direction);
+    const described = this.describe();
+    const paths = Object.keys(described.nodes).sort();
+    const ids = /* @__PURE__ */ new Map();
+    for (let i = 0; i < paths.length; i += 1) {
+      ids.set(paths[i], `n${i}`);
+    }
+    const lines = [`direction: ${d2DirectionFromGraphDirection(direction)}`];
+    for (const path of paths) {
+      const id = ids.get(path);
+      lines.push(`${id}: "${escapeD2Label(path)}"`);
+    }
+    for (const [from, to] of collectDiagramArrows(described)) {
+      const fromId = ids.get(from);
+      const toId = ids.get(to);
+      if (!fromId || !toId) continue;
+      lines.push(`${fromId} -> ${toId}`);
+    }
+    return lines.join("\n");
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Inspector (roadmap 3.3) — reasoning trace, overhead gating
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * When `false`, structured observation options (`causal`, `timeline`),
+   * `annotate()`, and `traceLog()` are no-ops. Raw `observe()` always works.
+   *
+   * Default: `true` outside production (`process.env.NODE_ENV !== "production"`).
+   */
+  static inspectorEnabled = !(typeof process !== "undefined" && process.env?.NODE_ENV === "production");
+  _annotations = /* @__PURE__ */ new Map();
+  _traceRing = new RingBuffer(1e3);
+  /**
+   * Attaches a reasoning annotation to a node — captures *why* an AI agent set a value.
+   *
+   * No-op when {@link Graph.inspectorEnabled} is `false`.
+   *
+   * @param path - Qualified node path.
+   * @param reason - Free-text note stored in the trace ring buffer.
+   */
+  annotate(path, reason) {
+    if (!_Graph.inspectorEnabled) return;
+    this.resolve(path);
+    this._annotations.set(path, reason);
+    this._traceRing.push({ path, reason, timestamp_ns: monotonicNs() });
+  }
+  /**
+   * Returns a chronological log of all reasoning annotations (ring buffer).
+   *
+   * @returns `[]` when {@link Graph.inspectorEnabled} is `false`.
+   */
+  traceLog() {
+    if (!_Graph.inspectorEnabled) return [];
+    return this._traceRing.toArray();
+  }
+  /**
+   * Computes structural + value diff between two {@link Graph.describe} snapshots.
+   *
+   * @param a - Earlier describe output.
+   * @param b - Later describe output.
+   * @returns Added/removed nodes, changed fields, and edge deltas.
+   */
+  static diff(a, b) {
+    const aKeys = new Set(Object.keys(a.nodes));
+    const bKeys = new Set(Object.keys(b.nodes));
+    const nodesAdded = [...bKeys].filter((k) => !aKeys.has(k)).sort();
+    const nodesRemoved = [...aKeys].filter((k) => !bKeys.has(k)).sort();
+    const nodesChanged = [];
+    for (const key of aKeys) {
+      if (!bKeys.has(key)) continue;
+      const na = a.nodes[key];
+      const nb = b.nodes[key];
+      const av = na.v;
+      const bv = nb.v;
+      if (av != null && bv != null && av.id === bv.id && av.version === bv.version) {
+        for (const field of ["type", "status"]) {
+          const va = na[field];
+          const vb = nb[field];
+          if (va !== vb) {
+            nodesChanged.push({ path: key, field, from: va, to: vb });
+          }
+        }
+        continue;
+      }
+      for (const field of ["type", "status", "value"]) {
+        const va = na[field];
+        const vb = nb[field];
+        if (!Object.is(va, vb) && JSON.stringify(va) !== JSON.stringify(vb)) {
+          nodesChanged.push({ path: key, field, from: va, to: vb });
+        }
+      }
+    }
+    const edgeKey2 = (e) => `${e.from}	${e.to}`;
+    const aEdges = new Set(a.edges.map(edgeKey2));
+    const bEdges = new Set(b.edges.map(edgeKey2));
+    const edgesAdded = b.edges.filter((e) => !aEdges.has(edgeKey2(e)));
+    const edgesRemoved = a.edges.filter((e) => !bEdges.has(edgeKey2(e)));
+    const aSubgraphs = new Set(a.subgraphs);
+    const bSubgraphs = new Set(b.subgraphs);
+    const subgraphsAdded = [...bSubgraphs].filter((s) => !aSubgraphs.has(s)).sort();
+    const subgraphsRemoved = [...aSubgraphs].filter((s) => !bSubgraphs.has(s)).sort();
+    return {
+      nodesAdded,
+      nodesRemoved,
+      nodesChanged,
+      edgesAdded,
+      edgesRemoved,
+      subgraphsAdded,
+      subgraphsRemoved
+    };
+  }
+};
+function reachable(described, from, direction, options = {}) {
+  if (!from) return [];
+  if (direction !== "upstream" && direction !== "downstream") {
+    throw new Error(`reachable: direction must be "upstream" or "downstream"`);
+  }
+  const maxDepth = options.maxDepth;
+  if (maxDepth != null && (!Number.isInteger(maxDepth) || maxDepth < 0)) {
+    throw new Error(`reachable: maxDepth must be an integer >= 0`);
+  }
+  if (maxDepth === 0) return [];
+  const depsByPath = /* @__PURE__ */ new Map();
+  const reverseDeps = /* @__PURE__ */ new Map();
+  const incomingEdges = /* @__PURE__ */ new Map();
+  const outgoingEdges = /* @__PURE__ */ new Map();
+  const universe = /* @__PURE__ */ new Set();
+  const nodesRaw = described != null && typeof described === "object" && "nodes" in described && typeof described.nodes === "object" && described.nodes !== null && !Array.isArray(described.nodes) ? described.nodes : {};
+  const edgesRaw = described != null && typeof described === "object" && "edges" in described && Array.isArray(described.edges) ? described.edges : [];
+  for (const [path, node] of Object.entries(nodesRaw)) {
+    if (!path) continue;
+    universe.add(path);
+    const deps = node != null && typeof node === "object" && Array.isArray(node.deps) ? node.deps : [];
+    const cleanDeps = deps.filter((d) => typeof d === "string" && d.length > 0);
+    depsByPath.set(path, cleanDeps);
+    for (const dep of cleanDeps) {
+      universe.add(dep);
+      if (!reverseDeps.has(dep)) reverseDeps.set(dep, /* @__PURE__ */ new Set());
+      reverseDeps.get(dep).add(path);
+    }
+  }
+  for (const edge of edgesRaw) {
+    if (edge == null || typeof edge !== "object") continue;
+    const edgeFrom = "from" in edge && typeof edge.from === "string" ? edge.from : "";
+    const edgeTo = "to" in edge && typeof edge.to === "string" ? edge.to : "";
+    if (!edgeFrom || !edgeTo) continue;
+    universe.add(edgeFrom);
+    universe.add(edgeTo);
+    if (!outgoingEdges.has(edgeFrom)) outgoingEdges.set(edgeFrom, /* @__PURE__ */ new Set());
+    outgoingEdges.get(edgeFrom).add(edgeTo);
+    if (!incomingEdges.has(edgeTo)) incomingEdges.set(edgeTo, /* @__PURE__ */ new Set());
+    incomingEdges.get(edgeTo).add(edgeFrom);
+  }
+  if (!universe.has(from)) return [];
+  const neighbors = (path) => {
+    if (direction === "upstream") {
+      const depNeighbors2 = depsByPath.get(path) ?? [];
+      const edgeNeighbors2 = [...incomingEdges.get(path) ?? []];
+      return [...depNeighbors2, ...edgeNeighbors2];
+    }
+    const depNeighbors = [...reverseDeps.get(path) ?? []];
+    const edgeNeighbors = [...outgoingEdges.get(path) ?? []];
+    return [...depNeighbors, ...edgeNeighbors];
+  };
+  const visited = /* @__PURE__ */ new Set([from]);
+  const out = /* @__PURE__ */ new Set();
+  const queue = [{ path: from, depth: 0 }];
+  while (queue.length > 0) {
+    const next = queue.shift();
+    if (maxDepth != null && next.depth >= maxDepth) continue;
+    for (const nb of neighbors(next.path)) {
+      if (!nb || visited.has(nb)) continue;
+      visited.add(nb);
+      out.add(nb);
+      queue.push({ path: nb, depth: next.depth + 1 });
+    }
+  }
+  return [...out].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+}
+
+export {
+  GRAPH_META_SEGMENT,
+  Graph,
+  reachable
+};
+//# sourceMappingURL=chunk-6W5SGIGB.js.map