@graphrefly/graphrefly 0.1.0

package/dist/graph/index.cjs

@@ -0,0 +1,3225 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/graph/index.ts
+var graph_exports = {};
+__export(graph_exports, {
+  GRAPH_META_SEGMENT: () => GRAPH_META_SEGMENT,
+  Graph: () => Graph,
+  JsonCodec: () => JsonCodec,
+  createDagCborCodec: () => createDagCborCodec,
+  createDagCborZstdCodec: () => createDagCborZstdCodec,
+  negotiateCodec: () => negotiateCodec,
+  reachable: () => reachable,
+  replayWAL: () => replayWAL
+});
+module.exports = __toCommonJS(graph_exports);
+
+// src/graph/codec.ts
+var JsonCodec = {
+  contentType: "application/json",
+  name: "json",
+  encode(snapshot) {
+    const json = JSON.stringify(snapshot);
+    return new TextEncoder().encode(json);
+  },
+  decode(buffer) {
+    const json = new TextDecoder().decode(buffer);
+    return JSON.parse(json);
+  }
+};
+function createDagCborCodec(dagCbor) {
+  return {
+    contentType: "application/dag-cbor",
+    name: "dag-cbor",
+    encode: (snapshot) => dagCbor.encode(snapshot),
+    decode: (buffer) => dagCbor.decode(buffer)
+  };
+}
+function createDagCborZstdCodec(dagCbor, zstd) {
+  return {
+    contentType: "application/dag-cbor+zstd",
+    name: "dag-cbor-zstd",
+    encode: (snapshot) => zstd.compressSync(dagCbor.encode(snapshot)),
+    decode: (buffer) => dagCbor.decode(zstd.decompressSync(buffer))
+  };
+}
+function negotiateCodec(localPreference, remoteContentTypes) {
+  const remoteSet = new Set(remoteContentTypes);
+  for (const codec of localPreference) {
+    if (remoteSet.has(codec.contentType)) return codec;
+  }
+  return null;
+}
+function replayWAL(entries) {
+  if (entries.length === 0) {
+    throw new Error("WAL is empty \u2014 need at least one full snapshot");
+  }
+  const first = entries[0];
+  if (first.type !== "full") {
+    throw new Error("WAL must start with a full snapshot");
+  }
+  const result = JSON.parse(JSON.stringify(first.snapshot));
+  for (let i = 1; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.type === "full") {
+      Object.assign(result, JSON.parse(JSON.stringify(entry.snapshot)));
+      continue;
+    }
+    const delta = entry.delta;
+    for (const [name, patch] of Object.entries(delta.nodes)) {
+      if (result.nodes[name]) {
+        result.nodes[name].value = patch.value;
+        if (patch.meta) {
+          result.nodes[name].meta = patch.meta;
+        }
+      }
+    }
+    for (const name of delta.removed) {
+      delete result.nodes[name];
+    }
+    const edges = [...result.edges];
+    for (const edge of delta.edgesRemoved) {
+      const idx = edges.findIndex((e) => e.from === edge.from && e.to === edge.to);
+      if (idx !== -1) edges.splice(idx, 1);
+    }
+    for (const edge of delta.edgesAdded) {
+      edges.push(edge);
+    }
+    result.edges = edges;
+  }
+  return result;
+}
+
+// src/core/messages.ts
+var DATA = /* @__PURE__ */ Symbol.for("graphrefly/DATA");
+var DIRTY = /* @__PURE__ */ Symbol.for("graphrefly/DIRTY");
+var RESOLVED = /* @__PURE__ */ Symbol.for("graphrefly/RESOLVED");
+var INVALIDATE = /* @__PURE__ */ Symbol.for("graphrefly/INVALIDATE");
+var PAUSE = /* @__PURE__ */ Symbol.for("graphrefly/PAUSE");
+var RESUME = /* @__PURE__ */ Symbol.for("graphrefly/RESUME");
+var TEARDOWN = /* @__PURE__ */ Symbol.for("graphrefly/TEARDOWN");
+var COMPLETE = /* @__PURE__ */ Symbol.for("graphrefly/COMPLETE");
+var ERROR = /* @__PURE__ */ Symbol.for("graphrefly/ERROR");
+function messageTier(t) {
+  if (t === DIRTY || t === INVALIDATE) return 0;
+  if (t === PAUSE || t === RESUME) return 1;
+  if (t === DATA || t === RESOLVED) return 2;
+  if (t === COMPLETE || t === ERROR) return 3;
+  if (t === TEARDOWN) return 4;
+  return 0;
+}
+function isPhase2Message(msg) {
+  const t = msg[0];
+  return t === DATA || t === RESOLVED;
+}
+function isTerminalMessage(t) {
+  return t === COMPLETE || t === ERROR;
+}
+function propagatesToMeta(t) {
+  return t === TEARDOWN;
+}
+
+// src/core/batch.ts
+var batchDepth = 0;
+var flushInProgress = false;
+var pendingPhase2 = [];
+var pendingPhase3 = [];
+function isBatching() {
+  return batchDepth > 0 || flushInProgress;
+}
+function partitionForBatch(messages) {
+  const immediate = [];
+  const deferred = [];
+  const terminal = [];
+  for (const m of messages) {
+    if (isPhase2Message(m)) {
+      deferred.push(m);
+    } else if (isTerminalMessage(m[0])) {
+      terminal.push(m);
+    } else {
+      immediate.push(m);
+    }
+  }
+  return { immediate, deferred, terminal };
+}
+function emitWithBatch(emit, messages, phase = 2) {
+  if (messages.length === 0) {
+    return;
+  }
+  const queue = phase === 3 ? pendingPhase3 : pendingPhase2;
+  if (messages.length === 1) {
+    const t = messages[0][0];
+    if (t === DATA || t === RESOLVED) {
+      if (isBatching()) {
+        queue.push(() => emit(messages));
+      } else {
+        emit(messages);
+      }
+    } else if (isTerminalMessage(t)) {
+      if (isBatching()) {
+        queue.push(() => emit(messages));
+      } else {
+        emit(messages);
+      }
+    } else {
+      emit(messages);
+    }
+    return;
+  }
+  const { immediate, deferred, terminal } = partitionForBatch(messages);
+  if (immediate.length > 0) {
+    emit(immediate);
+  }
+  if (isBatching()) {
+    if (deferred.length > 0) {
+      queue.push(() => emit(deferred));
+    }
+    if (terminal.length > 0) {
+      queue.push(() => emit(terminal));
+    }
+  } else {
+    if (deferred.length > 0) {
+      emit(deferred);
+    }
+    if (terminal.length > 0) {
+      emit(terminal);
+    }
+  }
+}
+
+// src/core/clock.ts
+function monotonicNs() {
+  return Math.trunc(performance.now() * 1e6);
+}
+function wallClockNs() {
+  return Date.now() * 1e6;
+}
+
+// src/core/guard.ts
+var GuardDenied = class extends Error {
+  actor;
+  action;
+  nodeName;
+  /**
+   * @param details - Actor, action, and optional node name for the denial.
+   * @param message - Optional override for the default error message.
+   */
+  constructor(details, message) {
+    super(
+      message ?? `GuardDenied: action "${String(details.action)}" denied for actor type "${String(details.actor.type)}"`
+    );
+    this.name = "GuardDenied";
+    this.actor = details.actor;
+    this.action = details.action;
+    this.nodeName = details.nodeName;
+  }
+  /** Qualified registry path when known (roadmap diagnostics: same as {@link nodeName}). */
+  get node() {
+    return this.nodeName;
+  }
+};
+var STANDARD_WRITE_TYPES = ["human", "llm", "wallet", "system"];
+function accessHintForGuard(guard) {
+  const allowed = STANDARD_WRITE_TYPES.filter((t) => guard({ type: t, id: "" }, "write"));
+  if (allowed.length === 0) return "restricted";
+  if (allowed.includes("human") && allowed.includes("llm") && allowed.every((t) => t === "human" || t === "llm" || t === "system")) {
+    return "both";
+  }
+  if (allowed.length === 1) return allowed[0];
+  return allowed.join("+");
+}
+
+// src/core/actor.ts
+var DEFAULT_ACTOR = { type: "system", id: "" };
+function normalizeActor(actor) {
+  if (actor == null) return DEFAULT_ACTOR;
+  const { type, id, ...rest } = actor;
+  return {
+    type: type ?? "system",
+    id: id ?? "",
+    ...rest
+  };
+}
+
+// src/core/versioning.ts
+var import_node_crypto = require("crypto");
+function canonicalizeForHash(value) {
+  if (value === void 0) return null;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Cannot hash non-finite number: ${value}`);
+    }
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw new TypeError(
+        `Cannot hash integer outside safe range (|n| > 2^53-1): ${value}. Cross-language cid parity is not guaranteed for unsafe integers.`
+      );
+    }
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(canonicalizeForHash);
+  }
+  if (typeof value === "object" && value !== null) {
+    const sorted = {};
+    for (const k of Object.keys(value).sort()) {
+      sorted[k] = canonicalizeForHash(value[k]);
+    }
+    return sorted;
+  }
+  return null;
+}
+function defaultHash(value) {
+  const canonical = canonicalizeForHash(value ?? null);
+  const json = JSON.stringify(canonical);
+  return (0, import_node_crypto.createHash)("sha256").update(json).digest("hex").slice(0, 16);
+}
+function createVersioning(level, initialValue, opts) {
+  const id = opts?.id ?? (0, import_node_crypto.randomUUID)();
+  if (level === 0) {
+    return { id, version: 0 };
+  }
+  const hash = opts?.hash ?? defaultHash;
+  const cid = hash(initialValue);
+  return { id, version: 0, cid, prev: null };
+}
+function advanceVersion(info, newValue, hashFn) {
+  info.version += 1;
+  if ("cid" in info) {
+    info.prev = info.cid;
+    info.cid = hashFn(newValue);
+  }
+}
+
+// src/core/node.ts
+function createIntBitSet() {
+  let bits = 0;
+  return {
+    set(i) {
+      bits |= 1 << i;
+    },
+    clear(i) {
+      bits &= ~(1 << i);
+    },
+    has(i) {
+      return (bits & 1 << i) !== 0;
+    },
+    covers(other) {
+      return (bits & other._bits()) === other._bits();
+    },
+    any() {
+      return bits !== 0;
+    },
+    reset() {
+      bits = 0;
+    },
+    _bits() {
+      return bits;
+    }
+  };
+}
+function createArrayBitSet(size) {
+  const words = new Uint32Array(Math.ceil(size / 32));
+  return {
+    set(i) {
+      words[i >>> 5] |= 1 << (i & 31);
+    },
+    clear(i) {
+      words[i >>> 5] &= ~(1 << (i & 31));
+    },
+    has(i) {
+      return (words[i >>> 5] & 1 << (i & 31)) !== 0;
+    },
+    covers(other) {
+      const ow = other._words;
+      for (let w = 0; w < words.length; w++) {
+        if ((words[w] & ow[w]) >>> 0 !== ow[w]) return false;
+      }
+      return true;
+    },
+    any() {
+      for (let w = 0; w < words.length; w++) {
+        if (words[w] !== 0) return true;
+      }
+      return false;
+    },
+    reset() {
+      words.fill(0);
+    },
+    _words: words
+  };
+}
+function createBitSet(size) {
+  return size <= 31 ? createIntBitSet() : createArrayBitSet(size);
+}
+var isNodeArray = (value) => Array.isArray(value);
+var isNodeOptions = (value) => typeof value === "object" && value != null && !Array.isArray(value);
+var isCleanupFn = (value) => typeof value === "function";
+var statusAfterMessage = (status, msg) => {
+  const t = msg[0];
+  if (t === DIRTY) return "dirty";
+  if (t === DATA) return "settled";
+  if (t === RESOLVED) return "resolved";
+  if (t === COMPLETE) return "completed";
+  if (t === ERROR) return "errored";
+  if (t === INVALIDATE) return "dirty";
+  if (t === TEARDOWN) return "disconnected";
+  return status;
+};
+var NodeImpl = class {
+  // --- Configuration (set once, never reassigned) ---
+  _optsName;
+  _registryName;
+  /** @internal — read by {@link describeNode} before inference. */
+  _describeKind;
+  meta;
+  _deps;
+  _fn;
+  _opts;
+  _equals;
+  _onMessage;
+  /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
+  _guard;
+  _lastMutation;
+  _hasDeps;
+  _autoComplete;
+  _isSingleDep;
+  // --- Mutable state ---
+  _cached;
+  _status;
+  _terminal = false;
+  _connected = false;
+  _producerStarted = false;
+  _connecting = false;
+  _manualEmitUsed = false;
+  _sinkCount = 0;
+  _singleDepSinkCount = 0;
+  // --- Object/collection state ---
+  _depDirtyMask;
+  _depSettledMask;
+  _depCompleteMask;
+  _allDepsCompleteMask;
+  _lastDepValues;
+  _cleanup;
+  _sinks = null;
+  _singleDepSinks = /* @__PURE__ */ new WeakSet();
+  _upstreamUnsubs = [];
+  _actions;
+  _boundEmitToSinks;
+  _inspectorHook;
+  _versioning;
+  _hashFn;
+  constructor(deps, fn, opts) {
+    this._deps = deps;
+    this._fn = fn;
+    this._opts = opts;
+    this._optsName = opts.name;
+    this._describeKind = opts.describeKind;
+    this._equals = opts.equals ?? Object.is;
+    this._onMessage = opts.onMessage;
+    this._guard = opts.guard;
+    this._hasDeps = deps.length > 0;
+    this._autoComplete = opts.completeWhenDepsComplete ?? true;
+    this._isSingleDep = deps.length === 1 && fn != null;
+    this._cached = opts.initial;
+    this._status = this._hasDeps ? "disconnected" : "settled";
+    this._hashFn = opts.versioningHash ?? defaultHash;
+    this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached, {
+      id: opts.versioningId,
+      hash: this._hashFn
+    }) : void 0;
+    this._depDirtyMask = createBitSet(deps.length);
+    this._depSettledMask = createBitSet(deps.length);
+    this._depCompleteMask = createBitSet(deps.length);
+    this._allDepsCompleteMask = createBitSet(deps.length);
+    for (let i = 0; i < deps.length; i++) this._allDepsCompleteMask.set(i);
+    const meta = {};
+    for (const [k, v] of Object.entries(opts.meta ?? {})) {
+      meta[k] = node({
+        initial: v,
+        name: `${opts.name ?? "node"}:meta:${k}`,
+        describeKind: "state",
+        ...opts.guard != null ? { guard: opts.guard } : {}
+      });
+    }
+    Object.freeze(meta);
+    this.meta = meta;
+    const self = this;
+    this._actions = {
+      down(messages) {
+        self._manualEmitUsed = true;
+        self._downInternal(messages);
+      },
+      emit(value) {
+        self._manualEmitUsed = true;
+        self._emitAutoValue(value);
+      },
+      up(messages) {
+        self._upInternal(messages);
+      }
+    };
+    this.down = this.down.bind(this);
+    this.up = this.up.bind(this);
+    this._boundEmitToSinks = this._emitToSinks.bind(this);
+  }
+  get name() {
+    return this._registryName ?? this._optsName;
+  }
+  /**
+   * When a node is registered with {@link Graph.add} without an options `name`,
+   * the graph assigns the registry local name for introspection (parity with graphrefly-py).
+   */
+  _assignRegistryName(localName) {
+    if (this._optsName !== void 0 || this._registryName !== void 0) return;
+    this._registryName = localName;
+  }
+  /**
+   * @internal Attach/remove inspector hook for graph-level observability.
+   * Returns a disposer that restores the previous hook.
+   */
+  _setInspectorHook(hook) {
+    const prev = this._inspectorHook;
+    this._inspectorHook = hook;
+    return () => {
+      if (this._inspectorHook === hook) {
+        this._inspectorHook = prev;
+      }
+    };
+  }
+  // --- Public interface (Node<T>) ---
+  get status() {
+    return this._status;
+  }
+  get lastMutation() {
+    return this._lastMutation;
+  }
+  get v() {
+    return this._versioning;
+  }
+  /**
+   * Retroactively apply versioning to a node that was created without it.
+   * No-op if versioning is already enabled.
+   *
+   * Version starts at 0 regardless of prior DATA emissions — it tracks
+   * changes from the moment versioning is enabled, not historical ones.
+   *
+   * @internal — used by {@link Graph.setVersioning}.
+   */
+  _applyVersioning(level, opts) {
+    if (this._versioning != null) return;
+    this._hashFn = opts?.hash ?? this._hashFn;
+    this._versioning = createVersioning(level, this._cached, {
+      id: opts?.id,
+      hash: this._hashFn
+    });
+  }
+  hasGuard() {
+    return this._guard != null;
+  }
+  allowsObserve(actor) {
+    if (this._guard == null) return true;
+    return this._guard(normalizeActor(actor), "observe");
+  }
+  get() {
+    return this._cached;
+  }
+  down(messages, options) {
+    if (messages.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      const delivery = options?.delivery ?? "write";
+      const action = delivery === "signal" ? "signal" : "write";
+      if (!this._guard(actor, action)) {
+        throw new GuardDenied({ actor, action, nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    this._downInternal(messages);
+  }
+  _downInternal(messages) {
+    if (messages.length === 0) return;
+    let lifecycleMessages = messages;
+    let sinkMessages = messages;
+    if (this._terminal && !this._opts.resubscribable) {
+      const terminalPassthrough = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
+      if (terminalPassthrough.length === 0) return;
+      lifecycleMessages = terminalPassthrough;
+      sinkMessages = terminalPassthrough;
+    }
+    this._handleLocalLifecycle(lifecycleMessages);
+    if (this._canSkipDirty()) {
+      let hasPhase2 = false;
+      for (let i = 0; i < sinkMessages.length; i++) {
+        const t = sinkMessages[i][0];
+        if (t === DATA || t === RESOLVED) {
+          hasPhase2 = true;
+          break;
+        }
+      }
+      if (hasPhase2) {
+        const filtered = [];
+        for (let i = 0; i < sinkMessages.length; i++) {
+          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
+        }
+        if (filtered.length > 0) {
+          emitWithBatch(this._boundEmitToSinks, filtered);
+        }
+        return;
+      }
+    }
+    emitWithBatch(this._boundEmitToSinks, sinkMessages);
+  }
+  subscribe(sink, hints) {
+    if (hints?.actor != null && this._guard != null) {
+      const actor = normalizeActor(hints.actor);
+      if (!this._guard(actor, "observe")) {
+        throw new GuardDenied({ actor, action: "observe", nodeName: this.name });
+      }
+    }
+    if (this._terminal && this._opts.resubscribable) {
+      this._terminal = false;
+      this._status = this._hasDeps ? "disconnected" : "settled";
+      this._opts.onResubscribe?.();
+    }
+    this._sinkCount += 1;
+    if (hints?.singleDep) {
+      this._singleDepSinkCount += 1;
+      this._singleDepSinks.add(sink);
+    }
+    if (this._sinks == null) {
+      this._sinks = sink;
+    } else if (typeof this._sinks === "function") {
+      this._sinks = /* @__PURE__ */ new Set([this._sinks, sink]);
+    } else {
+      this._sinks.add(sink);
+    }
+    if (this._hasDeps) {
+      this._connectUpstream();
+    } else if (this._fn) {
+      this._startProducer();
+    }
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this._sinkCount -= 1;
+      if (this._singleDepSinks.has(sink)) {
+        this._singleDepSinkCount -= 1;
+        this._singleDepSinks.delete(sink);
+      }
+      if (this._sinks == null) return;
+      if (typeof this._sinks === "function") {
+        if (this._sinks === sink) this._sinks = null;
+      } else {
+        this._sinks.delete(sink);
+        if (this._sinks.size === 1) {
+          const [only] = this._sinks;
+          this._sinks = only;
+        } else if (this._sinks.size === 0) {
+          this._sinks = null;
+        }
+      }
+      if (this._sinks == null) {
+        this._disconnectUpstream();
+        this._stopProducer();
+      }
+    };
+  }
+  up(messages, options) {
+    if (!this._hasDeps) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      if (!this._guard(actor, "write")) {
+        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    for (const dep of this._deps) {
+      if (options === void 0) {
+        dep.up?.(messages);
+      } else {
+        dep.up?.(messages, options);
+      }
+    }
+  }
+  _upInternal(messages) {
+    if (!this._hasDeps) return;
+    for (const dep of this._deps) {
+      dep.up?.(messages, { internal: true });
+    }
+  }
+  unsubscribe() {
+    if (!this._hasDeps) return;
+    this._disconnectUpstream();
+  }
+  // --- Private methods (prototype, _ prefix) ---
+  _emitToSinks(messages) {
+    if (this._sinks == null) return;
+    if (typeof this._sinks === "function") {
+      this._sinks(messages);
+      return;
+    }
+    const snapshot = [...this._sinks];
+    for (const sink of snapshot) {
+      sink(messages);
+    }
+  }
+  _handleLocalLifecycle(messages) {
+    for (const m of messages) {
+      const t = m[0];
+      if (t === DATA) {
+        this._cached = m[1];
+        if (this._versioning != null) {
+          advanceVersion(this._versioning, m[1], this._hashFn);
+        }
+      }
+      if (t === INVALIDATE) {
+        const cleanupFn = this._cleanup;
+        this._cleanup = void 0;
+        cleanupFn?.();
+        this._cached = void 0;
+        this._lastDepValues = void 0;
+      }
+      this._status = statusAfterMessage(this._status, m);
+      if (t === COMPLETE || t === ERROR) {
+        this._terminal = true;
+      }
+      if (t === TEARDOWN) {
+        if (this._opts.resetOnTeardown) {
+          this._cached = void 0;
+        }
+        const teardownCleanup = this._cleanup;
+        this._cleanup = void 0;
+        teardownCleanup?.();
+        try {
+          this._propagateToMeta(t);
+        } finally {
+          this._disconnectUpstream();
+          this._stopProducer();
+        }
+      }
+      if (t !== TEARDOWN && propagatesToMeta(t)) {
+        this._propagateToMeta(t);
+      }
+    }
+  }
+  /** Propagate a signal to all companion meta nodes (best-effort). */
+  _propagateToMeta(t) {
+    for (const metaNode of Object.values(this.meta)) {
+      try {
+        metaNode._downInternal([[t]]);
+      } catch {
+      }
+    }
+  }
+  _canSkipDirty() {
+    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
+  }
+  _emitAutoValue(value) {
+    const wasDirty = this._status === "dirty";
+    const unchanged = this._equals(this._cached, value);
+    if (unchanged) {
+      this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
+      return;
+    }
+    this._cached = value;
+    this._downInternal(wasDirty ? [[DATA, value]] : [[DIRTY], [DATA, value]]);
+  }
+  _runFn() {
+    if (!this._fn) return;
+    if (this._terminal && !this._opts.resubscribable) return;
+    if (this._connecting) return;
+    try {
+      const n = this._deps.length;
+      const depValues = new Array(n);
+      for (let i = 0; i < n; i++) depValues[i] = this._deps[i].get();
+      const prev = this._lastDepValues;
+      if (n > 0 && prev != null && prev.length === n) {
+        let allSame = true;
+        for (let i = 0; i < n; i++) {
+          if (!Object.is(depValues[i], prev[i])) {
+            allSame = false;
+            break;
+          }
+        }
+        if (allSame) {
+          if (this._status === "dirty") {
+            this._downInternal([[RESOLVED]]);
+          }
+          return;
+        }
+      }
+      const prevCleanup = this._cleanup;
+      this._cleanup = void 0;
+      prevCleanup?.();
+      this._manualEmitUsed = false;
+      this._lastDepValues = depValues;
+      this._inspectorHook?.({ kind: "run", depValues });
+      const out = this._fn(depValues, this._actions);
+      if (isCleanupFn(out)) {
+        this._cleanup = out;
+        return;
+      }
+      if (this._manualEmitUsed) return;
+      if (out === void 0) return;
+      this._emitAutoValue(out);
+    } catch (err) {
+      this._downInternal([[ERROR, err]]);
+    }
+  }
+  _onDepDirty(index) {
+    const wasDirty = this._depDirtyMask.has(index);
+    this._depDirtyMask.set(index);
+    this._depSettledMask.clear(index);
+    if (!wasDirty) {
+      this._downInternal([[DIRTY]]);
+    }
+  }
+  _onDepSettled(index) {
+    if (!this._depDirtyMask.has(index)) {
+      this._onDepDirty(index);
+    }
+    this._depSettledMask.set(index);
+    if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
+      this._depDirtyMask.reset();
+      this._depSettledMask.reset();
+      this._runFn();
+    }
+  }
+  _maybeCompleteFromDeps() {
+    if (this._autoComplete && this._deps.length > 0 && this._depCompleteMask.covers(this._allDepsCompleteMask)) {
+      this._downInternal([[COMPLETE]]);
+    }
+  }
+  _handleDepMessages(index, messages) {
+    for (const msg of messages) {
+      this._inspectorHook?.({ kind: "dep_message", depIndex: index, message: msg });
+      const t = msg[0];
+      if (this._onMessage) {
+        try {
+          if (this._onMessage(msg, index, this._actions)) continue;
+        } catch (err) {
+          this._downInternal([[ERROR, err]]);
+          return;
+        }
+      }
+      if (!this._fn) {
+        if (t === COMPLETE && this._deps.length > 1) {
+          this._depCompleteMask.set(index);
+          this._maybeCompleteFromDeps();
+          continue;
+        }
+        this._downInternal([msg]);
+        continue;
+      }
+      if (t === DIRTY) {
+        this._onDepDirty(index);
+        continue;
+      }
+      if (t === DATA || t === RESOLVED) {
+        this._onDepSettled(index);
+        continue;
+      }
+      if (t === COMPLETE) {
+        this._depCompleteMask.set(index);
+        this._depDirtyMask.clear(index);
+        this._depSettledMask.clear(index);
+        if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
+          this._depDirtyMask.reset();
+          this._depSettledMask.reset();
+          this._runFn();
+        } else if (!this._depDirtyMask.any() && this._status === "dirty") {
+          this._depSettledMask.reset();
+          this._runFn();
+        }
+        this._maybeCompleteFromDeps();
+        continue;
+      }
+      if (t === ERROR) {
+        this._downInternal([msg]);
+        continue;
+      }
+      if (t === INVALIDATE || t === TEARDOWN || t === PAUSE || t === RESUME) {
+        this._downInternal([msg]);
+        continue;
+      }
+      this._downInternal([msg]);
+    }
+  }
+  _connectUpstream() {
+    if (!this._hasDeps || this._connected) return;
+    this._connected = true;
+    this._depDirtyMask.reset();
+    this._depSettledMask.reset();
+    this._depCompleteMask.reset();
+    this._status = "settled";
+    const subHints = this._isSingleDep ? { singleDep: true } : void 0;
+    this._connecting = true;
+    try {
+      for (let i = 0; i < this._deps.length; i += 1) {
+        const dep = this._deps[i];
+        this._upstreamUnsubs.push(
+          dep.subscribe((msgs) => this._handleDepMessages(i, msgs), subHints)
+        );
+      }
+    } finally {
+      this._connecting = false;
+    }
+    if (this._fn) {
+      this._runFn();
+    }
+  }
+  _stopProducer() {
+    if (!this._producerStarted) return;
+    this._producerStarted = false;
+    const producerCleanup = this._cleanup;
+    this._cleanup = void 0;
+    producerCleanup?.();
+  }
+  _startProducer() {
+    if (this._deps.length !== 0 || !this._fn || this._producerStarted) return;
+    this._producerStarted = true;
+    this._runFn();
+  }
+  _disconnectUpstream() {
+    if (!this._connected) return;
+    for (const unsub of this._upstreamUnsubs.splice(0)) {
+      unsub();
+    }
+    this._connected = false;
+    this._depDirtyMask.reset();
+    this._depSettledMask.reset();
+    this._depCompleteMask.reset();
+    this._status = "disconnected";
+  }
+};
+function node(depsOrFn, fnOrOpts, optsArg) {
+  const deps = isNodeArray(depsOrFn) ? depsOrFn : [];
+  const fn = typeof depsOrFn === "function" ? depsOrFn : typeof fnOrOpts === "function" ? fnOrOpts : void 0;
+  let opts = {};
+  if (isNodeArray(depsOrFn)) {
+    opts = (isNodeOptions(fnOrOpts) ? fnOrOpts : optsArg) ?? {};
+  } else if (isNodeOptions(depsOrFn)) {
+    opts = depsOrFn;
+  } else {
+    opts = (isNodeOptions(fnOrOpts) ? fnOrOpts : optsArg) ?? {};
+  }
+  return new NodeImpl(deps, fn, opts);
+}
+
+// src/core/dynamic-node.ts
+var DynamicNodeImpl = class {
+  _optsName;
+  _registryName;
+  _describeKind;
+  meta;
+  _fn;
+  _equals;
+  _resubscribable;
+  _resetOnTeardown;
+  _autoComplete;
+  _onMessage;
+  _onResubscribe;
+  /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
+  _guard;
+  _lastMutation;
+  _inspectorHook;
+  // Sink tracking
+  _sinkCount = 0;
+  _singleDepSinkCount = 0;
+  _singleDepSinks = /* @__PURE__ */ new WeakSet();
+  // Actions object (for onMessage handler)
+  _actions;
+  _boundEmitToSinks;
+  // Mutable state
+  _cached;
+  _status = "disconnected";
+  _terminal = false;
+  _connected = false;
+  _rewiring = false;
+  // re-entrancy guard
+  // Dynamic deps tracking
+  _deps = [];
+  _depUnsubs = [];
+  _depIndexMap = /* @__PURE__ */ new Map();
+  // node → index in _deps
+  _dirtyBits = /* @__PURE__ */ new Set();
+  _settledBits = /* @__PURE__ */ new Set();
+  _completeBits = /* @__PURE__ */ new Set();
+  // Sinks
+  _sinks = null;
+  constructor(fn, opts) {
+    this._fn = fn;
+    this._optsName = opts.name;
+    this._describeKind = opts.describeKind;
+    this._equals = opts.equals ?? Object.is;
+    this._resubscribable = opts.resubscribable ?? false;
+    this._resetOnTeardown = opts.resetOnTeardown ?? false;
+    this._autoComplete = opts.completeWhenDepsComplete ?? true;
+    this._onMessage = opts.onMessage;
+    this._onResubscribe = opts.onResubscribe;
+    this._guard = opts.guard;
+    this._inspectorHook = void 0;
+    const meta = {};
+    for (const [k, v] of Object.entries(opts.meta ?? {})) {
+      meta[k] = node({
+        initial: v,
+        name: `${opts.name ?? "dynamicNode"}:meta:${k}`,
+        describeKind: "state",
+        ...opts.guard != null ? { guard: opts.guard } : {}
+      });
+    }
+    Object.freeze(meta);
+    this.meta = meta;
+    const self = this;
+    this._actions = {
+      down(messages) {
+        self._downInternal(messages);
+      },
+      emit(value) {
+        self._emitAutoValue(value);
+      },
+      up(messages) {
+        for (const dep of self._deps) {
+          dep.up?.(messages, { internal: true });
+        }
+      }
+    };
+    this._boundEmitToSinks = this._emitToSinks.bind(this);
+  }
+  get name() {
+    return this._registryName ?? this._optsName;
+  }
+  /** @internal */
+  _assignRegistryName(localName) {
+    if (this._optsName !== void 0 || this._registryName !== void 0) return;
+    this._registryName = localName;
+  }
+  /**
+   * @internal Attach/remove inspector hook for graph-level observability.
+   * Returns a disposer that restores the previous hook.
+   */
+  _setInspectorHook(hook) {
+    const prev = this._inspectorHook;
+    this._inspectorHook = hook;
+    return () => {
+      if (this._inspectorHook === hook) {
+        this._inspectorHook = prev;
+      }
+    };
+  }
+  get status() {
+    return this._status;
+  }
+  get lastMutation() {
+    return this._lastMutation;
+  }
+  /** Versioning not yet supported on DynamicNodeImpl. */
+  get v() {
+    return void 0;
+  }
+  hasGuard() {
+    return this._guard != null;
+  }
+  allowsObserve(actor) {
+    if (this._guard == null) return true;
+    return this._guard(normalizeActor(actor), "observe");
+  }
+  get() {
+    return this._cached;
+  }
+  down(messages, options) {
+    if (messages.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      const delivery = options?.delivery ?? "write";
+      const action = delivery === "signal" ? "signal" : "write";
+      if (!this._guard(actor, action)) {
+        throw new GuardDenied({ actor, action, nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    this._downInternal(messages);
+  }
+  _downInternal(messages) {
+    if (messages.length === 0) return;
+    let sinkMessages = messages;
+    if (this._terminal && !this._resubscribable) {
+      const pass = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
+      if (pass.length === 0) return;
+      sinkMessages = pass;
+    }
+    this._handleLocalLifecycle(sinkMessages);
+    if (this._canSkipDirty()) {
+      let hasPhase2 = false;
+      for (let i = 0; i < sinkMessages.length; i++) {
+        const t = sinkMessages[i][0];
+        if (t === DATA || t === RESOLVED) {
+          hasPhase2 = true;
+          break;
+        }
+      }
+      if (hasPhase2) {
+        const filtered = [];
+        for (let i = 0; i < sinkMessages.length; i++) {
+          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
+        }
+        if (filtered.length > 0) {
+          emitWithBatch(this._boundEmitToSinks, filtered);
+        }
+        return;
+      }
+    }
+    emitWithBatch(this._boundEmitToSinks, sinkMessages);
+  }
+  _canSkipDirty() {
+    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
+  }
+  subscribe(sink, hints) {
+    if (hints?.actor != null && this._guard != null) {
+      const actor = normalizeActor(hints.actor);
+      if (!this._guard(actor, "observe")) {
+        throw new GuardDenied({ actor, action: "observe", nodeName: this.name });
+      }
+    }
+    if (this._terminal && this._resubscribable) {
+      this._terminal = false;
+      this._status = "disconnected";
+      this._onResubscribe?.();
+    }
+    this._sinkCount += 1;
+    if (hints?.singleDep) {
+      this._singleDepSinkCount += 1;
+      this._singleDepSinks.add(sink);
+    }
+    if (this._sinks == null) {
+      this._sinks = sink;
+    } else if (typeof this._sinks === "function") {
+      this._sinks = /* @__PURE__ */ new Set([this._sinks, sink]);
+    } else {
+      this._sinks.add(sink);
+    }
+    if (!this._connected) {
+      this._connect();
+    }
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this._sinkCount -= 1;
+      if (this._singleDepSinks.has(sink)) {
+        this._singleDepSinkCount -= 1;
+        this._singleDepSinks.delete(sink);
+      }
+      if (this._sinks == null) return;
+      if (typeof this._sinks === "function") {
+        if (this._sinks === sink) this._sinks = null;
+      } else {
+        this._sinks.delete(sink);
+        if (this._sinks.size === 1) {
+          const [only] = this._sinks;
+          this._sinks = only;
+        } else if (this._sinks.size === 0) {
+          this._sinks = null;
+        }
+      }
+      if (this._sinks == null) {
+        this._disconnect();
+      }
+    };
+  }
+  up(messages, options) {
+    if (this._deps.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      if (!this._guard(actor, "write")) {
+        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    for (const dep of this._deps) {
+      dep.up?.(messages, options);
+    }
+  }
+  unsubscribe() {
+    this._disconnect();
+  }
+  // --- Private methods ---
+  _emitToSinks(messages) {
+    if (this._sinks == null) return;
+    if (typeof this._sinks === "function") {
+      this._sinks(messages);
+      return;
+    }
+    const snapshot = [...this._sinks];
+    for (const sink of snapshot) {
+      sink(messages);
+    }
+  }
+  _handleLocalLifecycle(messages) {
+    for (const m of messages) {
+      const t = m[0];
+      if (t === DATA) this._cached = m[1];
+      if (t === INVALIDATE) {
+        this._cached = void 0;
+      }
+      if (t === DATA || t === RESOLVED) {
+        this._status = "settled";
+      } else if (t === DIRTY) {
+        this._status = "dirty";
+      } else if (t === COMPLETE) {
+        this._status = "completed";
+        this._terminal = true;
+      } else if (t === ERROR) {
+        this._status = "errored";
+        this._terminal = true;
+      }
+      if (t === TEARDOWN) {
+        if (this._resetOnTeardown) this._cached = void 0;
+        try {
+          this._propagateToMeta(t);
+        } finally {
+          this._disconnect();
+        }
+      }
+      if (t !== TEARDOWN && propagatesToMeta(t)) {
+        this._propagateToMeta(t);
+      }
+    }
+  }
+  /** Propagate a signal to all companion meta nodes (best-effort). */
+  _propagateToMeta(t) {
+    for (const metaNode of Object.values(this.meta)) {
+      try {
+        metaNode.down([[t]], { internal: true });
+      } catch {
+      }
+    }
+  }
+  _emitAutoValue(value) {
+    const wasDirty = this._status === "dirty";
+    const unchanged = this._equals(this._cached, value);
+    if (unchanged) {
+      this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
+      return;
+    }
+    this._cached = value;
+    this._downInternal(wasDirty ? [[DATA, value]] : [[DIRTY], [DATA, value]]);
+  }
+  _connect() {
+    if (this._connected) return;
+    this._connected = true;
+    this._status = "settled";
+    this._dirtyBits.clear();
+    this._settledBits.clear();
+    this._completeBits.clear();
+    this._runFn();
+  }
+  _disconnect() {
+    if (!this._connected) return;
+    for (const unsub of this._depUnsubs) unsub();
+    this._depUnsubs = [];
+    this._deps = [];
+    this._depIndexMap.clear();
+    this._dirtyBits.clear();
+    this._settledBits.clear();
+    this._completeBits.clear();
+    this._connected = false;
+    this._status = "disconnected";
+  }
+  _runFn() {
+    if (this._terminal && !this._resubscribable) return;
+    if (this._rewiring) return;
+    const trackedDeps = [];
+    const trackedSet = /* @__PURE__ */ new Set();
+    const get = (dep) => {
+      if (!trackedSet.has(dep)) {
+        trackedSet.add(dep);
+        trackedDeps.push(dep);
+      }
+      return dep.get();
+    };
+    try {
+      const depValues = [];
+      for (const dep of this._deps) {
+        depValues.push(dep.get());
+      }
+      this._inspectorHook?.({ kind: "run", depValues });
+      const result = this._fn(get);
+      this._rewire(trackedDeps);
+      if (result === void 0) return;
+      this._emitAutoValue(result);
+    } catch (err) {
+      this._downInternal([[ERROR, err]]);
+    }
+  }
+  _rewire(newDeps) {
+    this._rewiring = true;
+    try {
+      const oldMap = this._depIndexMap;
+      const newMap = /* @__PURE__ */ new Map();
+      const newUnsubs = [];
+      for (let i = 0; i < newDeps.length; i++) {
+        const dep = newDeps[i];
+        newMap.set(dep, i);
+        const oldIdx = oldMap.get(dep);
+        if (oldIdx !== void 0) {
+          newUnsubs.push(this._depUnsubs[oldIdx]);
+          this._depUnsubs[oldIdx] = () => {
+          };
+        } else {
+          const idx = i;
+          const unsub = dep.subscribe((msgs) => this._handleDepMessages(idx, msgs));
+          newUnsubs.push(unsub);
+        }
+      }
+      for (const [dep, oldIdx] of oldMap) {
+        if (!newMap.has(dep)) {
+          this._depUnsubs[oldIdx]();
+        }
+      }
+      this._deps = newDeps;
+      this._depUnsubs = newUnsubs;
+      this._depIndexMap = newMap;
+      this._dirtyBits.clear();
+      this._settledBits.clear();
+      const newCompleteBits = /* @__PURE__ */ new Set();
+      for (const oldIdx of this._completeBits) {
+        const dep = [...oldMap.entries()].find(([, idx]) => idx === oldIdx)?.[0];
+        if (dep && newMap.has(dep)) {
+          newCompleteBits.add(newMap.get(dep));
+        }
+      }
+      this._completeBits = newCompleteBits;
+    } finally {
+      this._rewiring = false;
+    }
+  }
+  _handleDepMessages(index, messages) {
+    if (this._rewiring) return;
+    for (const msg of messages) {
+      this._inspectorHook?.({ kind: "dep_message", depIndex: index, message: msg });
+      const t = msg[0];
+      if (this._onMessage) {
+        try {
+          if (this._onMessage(msg, index, this._actions)) continue;
+        } catch (err) {
+          this._downInternal([[ERROR, err]]);
+          return;
+        }
+      }
+      if (t === DIRTY) {
+        this._dirtyBits.add(index);
+        this._settledBits.delete(index);
+        if (this._dirtyBits.size === 1) {
+          emitWithBatch(this._boundEmitToSinks, [[DIRTY]]);
+        }
+        continue;
+      }
+      if (t === DATA || t === RESOLVED) {
+        if (!this._dirtyBits.has(index)) {
+          this._dirtyBits.add(index);
+          emitWithBatch(this._boundEmitToSinks, [[DIRTY]]);
+        }
+        this._settledBits.add(index);
+        if (this._allDirtySettled()) {
+          this._dirtyBits.clear();
+          this._settledBits.clear();
+          this._runFn();
+        }
+        continue;
+      }
+      if (t === COMPLETE) {
+        this._completeBits.add(index);
+        this._dirtyBits.delete(index);
+        this._settledBits.delete(index);
+        if (this._allDirtySettled()) {
+          this._dirtyBits.clear();
+          this._settledBits.clear();
+          this._runFn();
+        }
+        if (this._autoComplete && this._completeBits.size >= this._deps.length && this._deps.length > 0) {
+          this._downInternal([[COMPLETE]]);
+        }
+        continue;
+      }
+      if (t === ERROR) {
+        this._downInternal([msg]);
+        continue;
+      }
+      if (t === INVALIDATE || t === TEARDOWN || t === PAUSE || t === RESUME) {
+        this._downInternal([msg]);
+        continue;
+      }
+      this._downInternal([msg]);
+    }
+  }
+  _allDirtySettled() {
+    if (this._dirtyBits.size === 0) return false;
+    for (const idx of this._dirtyBits) {
+      if (!this._settledBits.has(idx)) return false;
+    }
+    return true;
+  }
+};
+
+// src/core/meta.ts
+function inferDescribeType(n) {
+  if (n._describeKind != null) return n._describeKind;
+  if (!n._hasDeps) return n._fn != null ? "producer" : "state";
+  if (n._fn == null) return "derived";
+  if (n._manualEmitUsed) return "operator";
+  return "derived";
+}
+function metaSnapshot(node2) {
+  const out = {};
+  for (const [key, child] of Object.entries(node2.meta)) {
+    try {
+      out[key] = child.get();
+    } catch {
+    }
+  }
+  return out;
+}
+function describeNode(node2) {
+  const meta = { ...metaSnapshot(node2) };
+  const guard = node2 instanceof NodeImpl && node2._guard || node2 instanceof DynamicNodeImpl && node2._guard || void 0;
+  if (guard != null && meta.access === void 0) {
+    meta.access = accessHintForGuard(guard);
+  }
+  let type = "state";
+  let deps = [];
+  if (node2 instanceof NodeImpl) {
+    type = inferDescribeType(node2);
+    deps = node2._deps.map((d) => d.name ?? "");
+  } else if (node2 instanceof DynamicNodeImpl) {
+    type = node2._describeKind ?? "derived";
+    deps = [];
+  }
+  const out = {
+    type,
+    status: node2.status,
+    deps,
+    meta
+  };
+  if (node2.name != null) {
+    out.name = node2.name;
+  }
+  try {
+    out.value = node2.get();
+  } catch {
+  }
+  if (node2.v != null) {
+    const vInfo = { id: node2.v.id, version: node2.v.version };
+    if ("cid" in node2.v) {
+      vInfo.cid = node2.v.cid;
+      vInfo.prev = node2.v.prev;
+    }
+    out.v = vInfo;
+  }
+  return out;
+}
+
+// src/core/sugar.ts
+function state(initial, opts) {
+  return node([], { ...opts, initial });
+}
+
+// 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, node2) {
+    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 === node2) {
+        throw new Error(
+          `Graph "${this.name}": node instance already registered as "${existingName}"`
+        );
+      }
+    }
+    this._nodes.set(name, node2);
+    if (node2 instanceof NodeImpl) {
+      node2._assignRegistryName(name);
+      if (this._defaultVersioningLevel != null) {
+        node2._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 node2 = this._nodes.get(name);
+    if (!node2) {
+      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);
+    }
+    node2.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 node2;
+        if (slice?.type === "state") {
+          node2 = state(slice.value, { meta });
+        } else {
+          if (factory == null) continue;
+          node2 = factory(localName, {
+            path,
+            type: slice.type,
+            value: slice.value,
+            meta,
+            deps,
+            resolvedDeps: deps.map((dep) => created.get(dep))
+          });
+        }
+        owner.add(localName, node2);
+        created.set(path, node2);
+        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, node2] of Object.entries(nodesRaw)) {
+    if (!path) continue;
+    universe.add(path);
+    const deps = node2 != null && typeof node2 === "object" && Array.isArray(node2.deps) ? node2.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);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GRAPH_META_SEGMENT,
+  Graph,
+  JsonCodec,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  negotiateCodec,
+  reachable,
+  replayWAL
+});
+//# sourceMappingURL=index.cjs.map