@graphrefly/graphrefly 0.25.0 → 0.27.0

package/dist/compat/zustand/index.cjs

@@ -0,0 +1,4931 @@
+"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/compat/zustand/index.ts
+var zustand_exports = {};
+__export(zustand_exports, {
+  create: () => create
+});
+module.exports = __toCommonJS(zustand_exports);
+
+// src/core/messages.ts
+var START = /* @__PURE__ */ Symbol.for("graphrefly/START");
+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");
+var DIRTY_MSG = Object.freeze([DIRTY]);
+var RESOLVED_MSG = Object.freeze([RESOLVED]);
+var INVALIDATE_MSG = Object.freeze([INVALIDATE]);
+var START_MSG = Object.freeze([START]);
+var COMPLETE_MSG = Object.freeze([COMPLETE]);
+var TEARDOWN_MSG = Object.freeze([TEARDOWN]);
+var DIRTY_ONLY_BATCH = Object.freeze([DIRTY_MSG]);
+var RESOLVED_ONLY_BATCH = Object.freeze([RESOLVED_MSG]);
+var INVALIDATE_ONLY_BATCH = Object.freeze([INVALIDATE_MSG]);
+var COMPLETE_ONLY_BATCH = Object.freeze([COMPLETE_MSG]);
+var TEARDOWN_ONLY_BATCH = Object.freeze([TEARDOWN_MSG]);
+
+// src/graph/codec.ts
+var JsonCodec = {
+  name: "json",
+  version: 1,
+  contentType: "application/json",
+  encode(snapshot) {
+    const json = JSON.stringify(snapshot);
+    return new TextEncoder().encode(json);
+  },
+  decode(buffer, _codecVersion) {
+    const json = new TextDecoder().decode(buffer);
+    return JSON.parse(json);
+  }
+};
+var ENVELOPE_VERSION = 1;
+var ENVELOPE_MIN_LEN = 4;
+function encodeEnvelope(codec, payload) {
+  const nameBytes = new TextEncoder().encode(codec.name);
+  if (nameBytes.length === 0 || nameBytes.length > 255) {
+    throw new Error(
+      `encodeEnvelope: codec name "${codec.name}" encodes to ${nameBytes.length} bytes (must be 1\u2013255)`
+    );
+  }
+  const cv = codec.version;
+  if (!Number.isInteger(cv) || cv < 0 || cv > 65535) {
+    throw new Error(
+      `encodeEnvelope: codec.version ${cv} out of u16 range (expected integer 0\u201365535)`
+    );
+  }
+  const totalLen = 1 + 1 + nameBytes.length + 2 + payload.length;
+  if (totalLen > 4294967295) {
+    throw new Error(
+      `encodeEnvelope: total envelope size ${totalLen} exceeds 2^32-1 bytes (payload ${payload.length} bytes)`
+    );
+  }
+  const out = new Uint8Array(totalLen);
+  let i = 0;
+  out[i++] = ENVELOPE_VERSION;
+  out[i++] = nameBytes.length;
+  out.set(nameBytes, i);
+  i += nameBytes.length;
+  out[i++] = cv >>> 8 & 255;
+  out[i++] = cv & 255;
+  out.set(payload, i);
+  return out;
+}
+function decodeEnvelope(bytes, config) {
+  if (bytes.length < ENVELOPE_MIN_LEN) {
+    throw new Error(`decodeEnvelope: bytes too short (${bytes.length} < ${ENVELOPE_MIN_LEN})`);
+  }
+  let i = 0;
+  const envVersion = bytes[i++];
+  if (envVersion !== ENVELOPE_VERSION) {
+    throw new Error(
+      `decodeEnvelope: unsupported envelope version ${envVersion} (expected ${ENVELOPE_VERSION})`
+    );
+  }
+  const nameLen = bytes[i++];
+  if (nameLen === 0) {
+    throw new Error("decodeEnvelope: name_len must be >= 1");
+  }
+  if (i + nameLen + 2 > bytes.length) {
+    throw new Error(
+      `decodeEnvelope: envelope truncated (need ${i + nameLen + 2} bytes, have ${bytes.length})`
+    );
+  }
+  const name = new TextDecoder().decode(bytes.subarray(i, i + nameLen));
+  i += nameLen;
+  const codecVersion = (bytes[i] << 8 | bytes[i + 1]) >>> 0;
+  i += 2;
+  const payload = bytes.subarray(i);
+  const codec = config.lookupCodec(name);
+  if (codec == null) {
+    throw new Error(
+      `decodeEnvelope: codec "${name}" not registered (envelope codec_v=${codecVersion})`
+    );
+  }
+  return { codec, codecVersion, payload };
+}
+function registerBuiltinCodecs(config) {
+  config.registerCodec(JsonCodec);
+}
+
+// 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/batch.ts
+var MAX_DRAIN_ITERATIONS = 1e3;
+var batchDepth = 0;
+var flushInProgress = false;
+var drainPhase2 = [];
+var drainPhase3 = [];
+var drainPhase4 = [];
+var flushHooks = [];
+function isBatching() {
+  return batchDepth > 0 || flushInProgress;
+}
+function isExplicitlyBatching() {
+  return batchDepth > 0;
+}
+function registerBatchFlushHook(hook) {
+  if (batchDepth > 0) {
+    flushHooks.push(hook);
+  } else {
+    hook();
+  }
+}
+function batch(fn) {
+  batchDepth += 1;
+  let threw = false;
+  try {
+    fn();
+  } catch (e) {
+    threw = true;
+    throw e;
+  } finally {
+    batchDepth -= 1;
+    if (batchDepth === 0) {
+      if (threw) {
+        if (!flushInProgress) {
+          const hooks = flushHooks.splice(0);
+          for (const h of hooks) {
+            try {
+              h();
+            } catch {
+            }
+          }
+          drainPhase2.length = 0;
+          drainPhase3.length = 0;
+          drainPhase4.length = 0;
+        }
+      } else {
+        drainPending();
+      }
+    }
+  }
+}
+function drainPending() {
+  const ownsFlush = !flushInProgress;
+  if (ownsFlush) flushInProgress = true;
+  const errors = [];
+  let iterations = 0;
+  try {
+    while (drainPhase2.length > 0 || drainPhase3.length > 0 || drainPhase4.length > 0 || ownsFlush && flushHooks.length > 0) {
+      if (ownsFlush && flushHooks.length > 0) {
+        const hooks = flushHooks.splice(0);
+        for (const h of hooks) {
+          try {
+            h();
+          } catch (e) {
+            errors.push(e);
+          }
+        }
+        continue;
+      }
+      iterations += 1;
+      if (iterations > MAX_DRAIN_ITERATIONS) {
+        drainPhase2.length = 0;
+        drainPhase3.length = 0;
+        drainPhase4.length = 0;
+        throw new Error(
+          `batch drain exceeded ${MAX_DRAIN_ITERATIONS} iterations \u2014 likely a reactive cycle`
+        );
+      }
+      const queue = drainPhase2.length > 0 ? drainPhase2 : drainPhase3.length > 0 ? drainPhase3 : drainPhase4;
+      const ops = queue.splice(0);
+      for (const run of ops) {
+        try {
+          run();
+        } catch (e) {
+          errors.push(e);
+        }
+      }
+    }
+  } finally {
+    if (ownsFlush) flushInProgress = false;
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "batch drain: multiple callbacks threw");
+  }
+}
+function downWithBatch(sink, messages, tierOf) {
+  if (messages.length === 0) return;
+  if (messages.length === 1) {
+    const tier = tierOf(messages[0][0]);
+    if (tier < 3 || !isBatching()) {
+      sink(messages);
+      return;
+    }
+    const queue = tier >= 5 ? drainPhase4 : tier === 4 ? drainPhase3 : drainPhase2;
+    queue.push(() => sink(messages));
+    return;
+  }
+  const n = messages.length;
+  let phase2Start = n;
+  let phase3Start = n;
+  let phase4Start = n;
+  let i = 0;
+  while (i < n && tierOf(messages[i][0]) < 3) i++;
+  phase2Start = i;
+  while (i < n && tierOf(messages[i][0]) === 3) i++;
+  phase3Start = i;
+  while (i < n && tierOf(messages[i][0]) === 4) i++;
+  phase4Start = i;
+  const batching = isBatching();
+  if (phase2Start > 0) {
+    const immediate = messages.slice(0, phase2Start);
+    sink(immediate);
+  }
+  if (phase3Start > phase2Start) {
+    const phase2 = messages.slice(phase2Start, phase3Start);
+    if (batching) drainPhase2.push(() => sink(phase2));
+    else sink(phase2);
+  }
+  if (phase4Start > phase3Start) {
+    const phase3 = messages.slice(phase3Start, phase4Start);
+    if (batching) drainPhase3.push(() => sink(phase3));
+    else sink(phase3);
+  }
+  if (n > phase4Start) {
+    const phase4 = messages.slice(phase4Start, n);
+    if (batching) drainPhase4.push(() => sink(phase4));
+    else sink(phase4);
+  }
+}
+
+// src/core/clock.ts
+function monotonicNs() {
+  return Math.trunc(performance.now() * 1e6);
+}
+function wallClockNs() {
+  return Date.now() * 1e6;
+}
+
+// src/core/config.ts
+var GraphReFlyConfig = class {
+  _messageTypes = /* @__PURE__ */ new Map();
+  _codecs = /* @__PURE__ */ new Map();
+  _onMessage;
+  _onSubscribe;
+  _defaultVersioning;
+  _defaultHashFn;
+  _inspectorEnabled = !(typeof process !== "undefined" && process.env?.NODE_ENV === "production");
+  _globalInspector;
+  _frozen = false;
+  /**
+   * Pre-bound tier lookup — shared by every node bound to this config. Since
+   * the registry is frozen on first hook access, this closure can be built
+   * once in the constructor and handed directly to `downWithBatch` /
+   * `_frameBatch` paths without per-node or per-emission `.bind(config)`
+   * allocation.
+   */
+  tierOf;
+  constructor(init) {
+    this._onMessage = init.onMessage;
+    this._onSubscribe = init.onSubscribe;
+    this._defaultVersioning = init.defaultVersioning;
+    this._defaultHashFn = init.defaultHashFn;
+    this.tierOf = (t) => {
+      const reg = this._messageTypes.get(t);
+      return reg != null ? reg.tier : 1;
+    };
+  }
+  // --- Hook getters (freeze on read) ---
+  get onMessage() {
+    this._frozen = true;
+    return this._onMessage;
+  }
+  get onSubscribe() {
+    this._frozen = true;
+    return this._onSubscribe;
+  }
+  // --- Hook setters (throw when frozen) ---
+  set onMessage(v) {
+    this._assertUnfrozen();
+    this._onMessage = v;
+  }
+  set onSubscribe(v) {
+    this._assertUnfrozen();
+    this._onSubscribe = v;
+  }
+  /**
+   * Default versioning level applied to every node bound to this config,
+   * unless the node's own `opts.versioning` provides an explicit override.
+   * Setting this is only allowed before the config freezes (i.e., before
+   * the first node is created) so every node in the graph sees a
+   * consistent starting level. Individual nodes can still opt into a
+   * higher level via `opts.versioning`, or post-hoc via
+   * `NodeImpl._applyVersioning(level)` when the node is quiescent.
+   *
+   * v0 is the minimum opt-in — unversioned nodes (`undefined`) skip
+   * the version counter entirely. v1 adds content-addressed cid.
+   * Future levels (v2, v3) are reserved for linked-history and
+   * cryptographic attestation extensions.
+   */
+  get defaultVersioning() {
+    return this._defaultVersioning;
+  }
+  set defaultVersioning(v) {
+    this._assertUnfrozen();
+    this._defaultVersioning = v;
+  }
+  /**
+   * Default content-hash function applied to every versioned node bound
+   * to this config, unless the node's own `opts.versioningHash` provides
+   * an explicit override. Use this when a graph needs a non-default hash
+   * — e.g., swap the vendored sync SHA-256 for a faster non-crypto hash
+   * (xxHash, FNV-1a) in hot-path workloads, or a stronger hash when
+   * versioning v1 cids are used as audit anchors.
+   *
+   * Only settable before the config freezes. Individual nodes can still
+   * override via `opts.versioningHash`.
+   */
+  get defaultHashFn() {
+    return this._defaultHashFn;
+  }
+  set defaultHashFn(v) {
+    this._assertUnfrozen();
+    this._defaultHashFn = v;
+  }
+  /**
+   * When `false`, structured observation options (`causal`, `timeline`)
+   * and `Graph.trace()` writes are no-ops. Raw `Graph.observe()` always
+   * works. Default: `true` outside production (`NODE_ENV !== "production"`).
+   *
+   * Settable at any time — inspector gating is an operational concern, not
+   * a protocol invariant, so it does NOT require freeze before node creation.
+   */
+  get inspectorEnabled() {
+    return this._inspectorEnabled;
+  }
+  set inspectorEnabled(v) {
+    this._inspectorEnabled = v;
+  }
+  /**
+   * Process-global observability hook (Redux-DevTools-style full-graph
+   * tracer). Fires once per outgoing batch from every node bound to this
+   * config, gated by {@link inspectorEnabled}. See {@link GlobalInspectorHook}.
+   *
+   * Settable at any time — like {@link inspectorEnabled} this is operational,
+   * not protocol-shaping, so it does NOT trigger config freeze.
+   */
+  get globalInspector() {
+    return this._globalInspector;
+  }
+  set globalInspector(v) {
+    this._globalInspector = v;
+  }
+  // --- Registry (writes require unfrozen; reads are free lookups) ---
+  /**
+   * Register a custom message type. Must be called before any node that
+   * uses this config has been created — otherwise throws. Default
+   * `wireCrossing` is `tier >= 3`.
+   */
+  registerMessageType(t, input) {
+    this._assertUnfrozen();
+    this._messageTypes.set(t, {
+      tier: input.tier,
+      wireCrossing: input.wireCrossing ?? input.tier >= 3,
+      metaPassthrough: input.metaPassthrough ?? true
+    });
+    return this;
+  }
+  /** Tier for `t`. Unknown types default to tier 1 (immediate, after START). */
+  messageTier(t) {
+    const reg = this._messageTypes.get(t);
+    return reg != null ? reg.tier : 1;
+  }
+  /**
+   * Whether `t` is registered as wire-crossing. Unknown types default to
+   * `true` (spec §1.3.6 forward-compat — unknowns cross the wire).
+   */
+  isWireCrossing(t) {
+    const reg = this._messageTypes.get(t);
+    return reg != null ? reg.wireCrossing : true;
+  }
+  /** Convenience inverse of {@link isWireCrossing}. */
+  isLocalOnly(t) {
+    return !this.isWireCrossing(t);
+  }
+  /**
+   * Whether `t` is forwarded to meta companions by `Graph.signal`. Defaults
+   * to `true` for unknowns (forward-compat — new types pass through meta by
+   * default; opt-in filter via `registerMessageType({metaPassthrough: false})`).
+   */
+  isMetaPassthrough(t) {
+    const reg = this._messageTypes.get(t);
+    return reg != null ? reg.metaPassthrough : true;
+  }
+  /** Whether `t` is a registered (built-in or custom) type. */
+  isKnownMessageType(t) {
+    return this._messageTypes.has(t);
+  }
+  // --- Codec registry (writes require unfrozen; reads are free lookups) ---
+  /**
+   * Register a graph codec by `codec.name`. Used by the envelope-based
+   * `graph.snapshot({format: "bytes", codec: name})` path and
+   * `Graph.decode(bytes)` auto-dispatch. Must be called before any node
+   * bound to this config is created — otherwise throws.
+   *
+   * Re-registering the same name overwrites, so user codecs can shadow
+   * built-in ones before freeze (e.g., to swap a zstd-wrapped dag-cbor in
+   * for `"dag-cbor"`).
+   */
+  registerCodec(codec) {
+    this._assertUnfrozen();
+    this._codecs.set(codec.name, codec);
+    return this;
+  }
+  /**
+   * Resolve a registered codec by name. Returns `undefined` for unknown
+   * names. Typed callers cast to their concrete codec interface (e.g.,
+   * `config.lookupCodec<GraphCodec>("json")`) — this method stays
+   * layer-pure (no import of graph-layer types into `core/`).
+   */
+  lookupCodec(name) {
+    return this._codecs.get(name);
+  }
+  /** @internal Used by tests and dev tooling — check freeze state without triggering it. */
+  _isFrozen() {
+    return this._frozen;
+  }
+  _assertUnfrozen() {
+    if (this._frozen) {
+      throw new Error(
+        "GraphReFlyConfig is frozen: a node has already captured this config. Register custom types and set hooks before creating any node."
+      );
+    }
+  }
+};
+function registerBuiltins(cfg) {
+  cfg.registerMessageType(START, { tier: 0, wireCrossing: false });
+  cfg.registerMessageType(DIRTY, { tier: 1, wireCrossing: false });
+  cfg.registerMessageType(INVALIDATE, {
+    tier: 1,
+    wireCrossing: false,
+    metaPassthrough: false
+  });
+  cfg.registerMessageType(PAUSE, { tier: 2, wireCrossing: false });
+  cfg.registerMessageType(RESUME, { tier: 2, wireCrossing: false });
+  cfg.registerMessageType(DATA, { tier: 3, wireCrossing: true });
+  cfg.registerMessageType(RESOLVED, { tier: 3, wireCrossing: true });
+  cfg.registerMessageType(COMPLETE, {
+    tier: 4,
+    wireCrossing: true,
+    metaPassthrough: false
+  });
+  cfg.registerMessageType(ERROR, {
+    tier: 4,
+    wireCrossing: true,
+    metaPassthrough: false
+  });
+  cfg.registerMessageType(TEARDOWN, {
+    tier: 5,
+    wireCrossing: true,
+    metaPassthrough: false
+  });
+}
+
+// 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/versioning.ts
+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;
+}
+var SHA256_K = /* @__PURE__ */ new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+var UTF8_ENCODER = /* @__PURE__ */ new TextEncoder();
+function sha256Hex(msg) {
+  const bytes = UTF8_ENCODER.encode(msg);
+  const msgLen = bytes.length;
+  const bitLen = msgLen * 8;
+  const totalLen = msgLen + 9 + 63 & ~63;
+  const padded = new Uint8Array(totalLen);
+  padded.set(bytes);
+  padded[msgLen] = 128;
+  const dv = new DataView(padded.buffer);
+  dv.setUint32(totalLen - 4, bitLen >>> 0, false);
+  dv.setUint32(totalLen - 8, Math.floor(bitLen / 4294967296) >>> 0, false);
+  let h0 = 1779033703;
+  let h1 = 3144134277;
+  let h2 = 1013904242;
+  let h3 = 2773480762;
+  let h4 = 1359893119;
+  let h5 = 2600822924;
+  let h6 = 528734635;
+  let h7 = 1541459225;
+  const W = new Uint32Array(64);
+  const rotr = (x, n) => x >>> n | x << 32 - n;
+  for (let off = 0; off < totalLen; off += 64) {
+    for (let i = 0; i < 16; i++) W[i] = dv.getUint32(off + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const w15 = W[i - 15];
+      const w2 = W[i - 2];
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ w15 >>> 3;
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ w2 >>> 10;
+      W[i] = W[i - 16] + s0 + W[i - 7] + s1 >>> 0;
+    }
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const t1 = h + S1 + ch + SHA256_K[i] + W[i] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const mj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + mj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + t1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 >>> 0;
+    }
+    h0 = h0 + a >>> 0;
+    h1 = h1 + b >>> 0;
+    h2 = h2 + c >>> 0;
+    h3 = h3 + d >>> 0;
+    h4 = h4 + e >>> 0;
+    h5 = h5 + f >>> 0;
+    h6 = h6 + g >>> 0;
+    h7 = h7 + h >>> 0;
+  }
+  const toHex = (x) => x.toString(16).padStart(8, "0");
+  return toHex(h0) + toHex(h1) + toHex(h2) + toHex(h3) + toHex(h4) + toHex(h5) + toHex(h6) + toHex(h7);
+}
+function defaultHash(value) {
+  const canonical = canonicalizeForHash(value ?? null);
+  const json = JSON.stringify(canonical);
+  return sha256Hex(json).slice(0, 16);
+}
+function randomUuid() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  const r = () => Math.floor(Math.random() * 4294967296).toString(16).padStart(8, "0");
+  const hex = r() + r() + r() + r();
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-${(parseInt(hex.slice(16, 17), 16) & 3 | 8).toString(16)}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+function createVersioning(level, initialValue, opts) {
+  const id = opts?.id ?? 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
+var noopUnsub = () => {
+};
+var MAX_RERUN_DEPTH = 100;
+function createDepRecord(n) {
+  return {
+    node: n,
+    unsub: null,
+    prevData: void 0,
+    dirty: false,
+    involvedThisWave: false,
+    dataBatch: [],
+    terminal: void 0
+  };
+}
+function resetDepRecord(d) {
+  d.prevData = void 0;
+  d.dirty = false;
+  d.involvedThisWave = false;
+  d.dataBatch.length = 0;
+  d.terminal = void 0;
+}
+function normalizeMessages(input) {
+  if (input.length === 0) return input;
+  return typeof input[0] === "symbol" ? [input] : input;
+}
+var defaultOnMessage = (node2, msg, ctx, _actions) => {
+  if (ctx.direction === "down-in") {
+    node2._onDepMessage(ctx.depIndex, msg);
+  }
+  return void 0;
+};
+var defaultOnSubscribe = (node2, sink, _ctx, _actions) => {
+  const impl = node2;
+  if (impl._status === "completed" || impl._status === "errored") return;
+  const cached = impl._cached;
+  const initial = cached === void 0 ? [START_MSG] : [START_MSG, [DATA, cached]];
+  if (impl._status === "dirty") initial.push(DIRTY_MSG);
+  downWithBatch(sink, initial, impl._config.tierOf);
+};
+var defaultConfig = new GraphReFlyConfig({
+  onMessage: defaultOnMessage,
+  onSubscribe: defaultOnSubscribe
+});
+registerBuiltins(defaultConfig);
+registerBuiltinCodecs(defaultConfig);
+var NodeImpl = class _NodeImpl {
+  // --- Identity ---
+  _optsName;
+  _describeKind;
+  meta;
+  /**
+   * Cached `Object.keys(meta).length > 0` check. `meta` is frozen at
+   * construction so this boolean never flips. Used by `_emit` to skip
+   * the meta TEARDOWN fan-out block allocation on the common "no meta"
+   * hot path.
+   */
+  _hasMeta;
+  // --- Config ---
+  _config;
+  // --- Topology ---
+  /** Mutable for autoTrackNode / Graph.connect() post-construction dep addition. */
+  _deps;
+  _sinks = null;
+  _sinkCount = 0;
+  // --- State ---
+  _cached;
+  _status;
+  _cleanup;
+  _store = {};
+  _waveHasNewData = false;
+  _hasNewTerminal = false;
+  _hasCalledFnOnce = false;
+  _paused = false;
+  _pendingWave = false;
+  _isExecutingFn = false;
+  _pendingRerun = false;
+  _rerunDepth = 0;
+  // --- Settlement counter (A3) ---
+  /**
+   * Count of deps currently in `dirty === true`. `_maybeRunFnOnSettlement`
+   * treats `0` as "wave settled" — O(1) check for full dep settlement.
+   */
+  _dirtyDepCount = 0;
+  // --- Per-batch emit accumulator (Bug 2: K+1 fan-in fix) ---
+  /**
+   * Inside an explicit `batch(() => ...)` scope, every `_emit` accumulates
+   * its already-framed messages here instead of dispatching synchronously.
+   * At batch end, `_flushBatchPending` runs (registered via
+   * `registerBatchFlushHook`) and delivers the whole accumulated batch as
+   * one `downWithBatch` call — collapsing what would otherwise be K
+   * separate sink invocations into one. This is the fix for the diamond
+   * fan-in K+1 over-fire.
+   *
+   * `null` outside batch (or after flush). Only ever appended to within
+   * a single explicit batch lifetime; reset to `null` on flush. State
+   * updates (cache, version, status) still happen per-emit via
+   * `_updateState` — only the downstream delivery is coalesced.
+   */
+  _batchPendingMessages = null;
+  // --- PAUSE/RESUME lock tracking (C0) ---
+  /**
+   * Set of active pause locks held against this node. Every `[PAUSE, lockId]`
+   * adds its `lockId` to the set; every `[RESUME, lockId]` removes it.
+   * `_paused` is a derived quantity: `_pauseLocks.size > 0`. Multi-pauser
+   * correctness — one controller releasing its lock does NOT resume the
+   * node while another controller still holds its lock.
+   */
+  _pauseLocks = null;
+  /**
+   * Buffered DATA messages held while paused. Only populated when
+   * `_pausable === "resumeAll"` (bufferAll mode). On final lock release
+   * the buffer is replayed through the node's outgoing pipeline in the
+   * order received. Non-bufferAll pause mode drops DATA on the floor
+   * (upstream is expected to honor PAUSE by suppressing production).
+   */
+  _pauseBuffer = null;
+  // --- Options (frozen at construction) ---
+  _fn;
+  _equals;
+  _resubscribable;
+  _resetOnTeardown;
+  _autoComplete;
+  _autoError;
+  _pausable;
+  _guard;
+  /**
+   * @internal Additional guards stacked at runtime via {@link NodeImpl._pushGuard}
+   * (e.g. by `policyEnforcer({ mode: "enforce" })`, roadmap §9.2). Effective
+   * write/signal/observe checks AND the original `_guard` with every entry here.
+   */
+  _extraGuards;
+  _hashFn;
+  _versioning;
+  /**
+   * Explicit versioning level, tracked separately from `_versioning` so
+   * monotonicity checks and future v2/v3 extensions don't rely on the
+   * fragile `"cid" in _versioning` shape discriminator. `undefined` means
+   * the node has no versioning attached; `0` / `1` / future levels name
+   * the tier. Mutated in lockstep with `_versioning` by the constructor
+   * and by `_applyVersioning`.
+   */
+  _versioningLevel;
+  // --- ABAC ---
+  _lastMutation;
+  /**
+   * @internal Per-node inspector hooks for `Graph.observe(path,
+   * { causal, derived })`. Fires in `_onDepMessage` and `_execFn`.
+   * Attached via `_setInspectorHook` (returns a disposer). Multiple
+   * observers can attach simultaneously — all registered hooks fire for
+   * every event.
+   */
+  _inspectorHooks;
+  // --- Actions (built once in the constructor) ---
+  _actions;
+  constructor(deps, fn, opts) {
+    this._config = opts.config ?? defaultConfig;
+    void this._config.onMessage;
+    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._autoError = opts.errorWhenDepsError ?? true;
+    this._pausable = opts.pausable ?? true;
+    this._guard = opts.guard;
+    this._fn = fn;
+    this._cached = opts.initial !== void 0 ? opts.initial : void 0;
+    this._status = deps.length === 0 && fn == null && this._cached !== void 0 ? "settled" : "sentinel";
+    this._hashFn = opts.versioningHash ?? this._config.defaultHashFn ?? defaultHash;
+    const versioningLevel = opts.versioning ?? this._config.defaultVersioning;
+    this._versioningLevel = versioningLevel;
+    this._versioning = versioningLevel != null ? createVersioning(versioningLevel, this._cached === void 0 ? void 0 : this._cached, {
+      id: opts.versioningId,
+      hash: this._hashFn
+    }) : void 0;
+    this._deps = deps.map(createDepRecord);
+    const meta = {};
+    for (const [k, v] of Object.entries(opts.meta ?? {})) {
+      const metaOpts = {
+        initial: v,
+        name: `${opts.name ?? "node"}:meta:${k}`,
+        describeKind: "state",
+        config: this._config
+      };
+      if (opts.guard != null) metaOpts.guard = opts.guard;
+      meta[k] = new _NodeImpl([], void 0, metaOpts);
+    }
+    Object.freeze(meta);
+    this.meta = meta;
+    this._hasMeta = Object.keys(meta).length > 0;
+    const self = this;
+    this._actions = {
+      emit(value) {
+        self._emit([[DATA, value]]);
+      },
+      down(messageOrMessages) {
+        self._emit(normalizeMessages(messageOrMessages));
+      },
+      up(messageOrMessages) {
+        self._emitUp(normalizeMessages(messageOrMessages));
+      }
+    };
+    this.down = this.down.bind(this);
+    this.up = this.up.bind(this);
+  }
+  // --- Derived state ---
+  get _isTerminal() {
+    return this._status === "completed" || this._status === "errored";
+  }
+  // --- Public getters ---
+  get name() {
+    return this._optsName;
+  }
+  get status() {
+    return this._status;
+  }
+  get cache() {
+    return this._cached === void 0 ? void 0 : this._cached;
+  }
+  get lastMutation() {
+    return this._lastMutation;
+  }
+  get v() {
+    return this._versioning;
+  }
+  hasGuard() {
+    return this._guard != null;
+  }
+  /**
+   * @internal Retroactively attach (or upgrade) versioning state on this
+   * node. Intended for `Graph.setVersioning(level)` bulk application and
+   * for rare cases where a specific node needs to be bumped to a higher
+   * level (e.g., `v0 → v1`) after construction.
+   *
+   * **Safety:** the mutation is rejected mid-wave. Specifically,
+   * throws if the node is currently executing its fn (`_isExecutingFn`).
+   * Callers at quiescent points — before the first sink subscribes, or
+   * after all sinks unsubscribe, or between external `down()` / `emit()`
+   * invocations — are safe. The re-entrance window that motivated §10.6.4
+   * removal was the "transition `_versioning` from `undefined` to a fresh
+   * object mid-`_updateState`" case; that path is now guarded.
+   *
+   * **Monotonicity:** levels can only go up. Downgrade (e.g., `v1 → v0`)
+   * is a no-op — once a node carries higher-level metadata, dropping it
+   * mid-graph would tear the linked-history invariant for v1 and above.
+   *
+   * **Linked-history boundary (D1, 2026-04-13):** upgrading v0 → v1
+   * produces a **fresh history root**. The new v1 state has `cid =
+   * hash(currentCachedValue)` and `prev = null`, not a synthetic `prev`
+   * anchored to any previous v0 value. The v0 monotonic `version` counter
+   * is preserved across the upgrade, but the linked-cid chain (spec §7)
+   * starts fresh at the upgrade point. Downstream audit tools that walk
+   * `v.cid.prev` backwards through time will see a `null` boundary at
+   * the upgrade — **this is intentional**: v0 had no cid to link to, and
+   * fabricating one would lie about the hash. Callers that require an
+   * unbroken cid chain from birth must attach versioning at construction
+   * via `opts.versioning` or `config.defaultVersioning`, not retroactively.
+   *
+   * @param level - New minimum versioning level.
+   * @param opts - Optional id / hash overrides; applied only if the
+   *   node currently has no versioning state.
+   */
+  _applyVersioning(level, opts) {
+    if (this._isExecutingFn) {
+      throw new Error(
+        `Node "${this.name}": _applyVersioning cannot run mid-fn \u2014 call it outside of \`_execFn\` (typically at graph setup time before the first subscribe).`
+      );
+    }
+    const currentLevel = this._versioningLevel;
+    if (currentLevel != null && level <= currentLevel) {
+      return;
+    }
+    const hash = opts?.hash ?? this._hashFn;
+    if (hash !== this._hashFn) this._hashFn = hash;
+    const initialValue = this._cached === void 0 ? void 0 : this._cached;
+    const current = this._versioning;
+    const preservedId = current?.id ?? opts?.id;
+    const preservedVersion = current?.version ?? 0;
+    const fresh = createVersioning(level, initialValue, {
+      id: preservedId,
+      hash
+    });
+    fresh.version = preservedVersion;
+    this._versioning = fresh;
+    this._versioningLevel = level;
+  }
+  /**
+   * @internal Attach an inspector hook. Returns a disposer that removes
+   * the hook. Used by `Graph.observe(path, { causal, derived })` to build
+   * causal traces. Multiple hooks may be attached concurrently — all fire
+   * for every event in registration order. Passing `undefined` is a no-op
+   * and returns a no-op disposer.
+   */
+  _setInspectorHook(hook) {
+    if (hook == null) return () => {
+    };
+    if (this._inspectorHooks == null) this._inspectorHooks = /* @__PURE__ */ new Set();
+    this._inspectorHooks.add(hook);
+    return () => {
+      this._inspectorHooks?.delete(hook);
+      if (this._inspectorHooks?.size === 0) this._inspectorHooks = void 0;
+    };
+  }
+  /**
+   * @internal Push an additional guard onto this node. Effective enforcement
+   * is the AND of `_guard` and every guard pushed via this hook — any one
+   * rejecting throws {@link GuardDenied}. Returns a disposer that removes
+   * the pushed guard. Multiple guards may be stacked simultaneously.
+   *
+   * Used by `policyEnforcer({ mode: "enforce" })` (roadmap §9.2) to overlay
+   * runtime constraint enforcement onto an existing graph without rebuilding
+   * its nodes. Pre-1.0 internal API; not part of the public surface.
+   *
+   * **Identity semantics:** guards are tracked in a `Set`, so pushing the
+   * same `NodeGuard` reference twice is a single registration. Wrap each
+   * push in a unique closure if independent stacking is needed.
+   *
+   * **Iteration order:** insertion-ordered (`Set` semantics). Determinism
+   * follows from single-threaded JS execution; nested re-entry from inside
+   * a guard body (push/pop while iterating) is undefined-but-survivable.
+   */
+  _pushGuard(guard) {
+    if (this._extraGuards == null) this._extraGuards = /* @__PURE__ */ new Set();
+    this._extraGuards.add(guard);
+    return () => {
+      this._extraGuards?.delete(guard);
+      if (this._extraGuards?.size === 0) this._extraGuards = void 0;
+    };
+  }
+  allowsObserve(actor) {
+    if (this._guard == null && this._extraGuards == null) return true;
+    const a = normalizeActor(actor);
+    if (this._guard != null && !this._guard(a, "observe")) return false;
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(a, "observe")) return false;
+      }
+    }
+    return true;
+  }
+  // --- Guard helper ---
+  _checkGuard(options) {
+    if (options?.internal) return;
+    const hasGuard = this._guard != null || this._extraGuards != null;
+    const hasActor = options?.actor != null;
+    if (!hasGuard && !hasActor) return;
+    const actor = normalizeActor(options?.actor);
+    const action = options?.delivery === "signal" ? "signal" : "write";
+    if (this._guard != null && !this._guard(actor, action)) {
+      throw new GuardDenied({ actor, action, nodeName: this.name });
+    }
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(actor, action)) {
+          throw new GuardDenied({ actor, action, nodeName: this.name });
+        }
+      }
+    }
+    this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+  }
+  // --- Public transport ---
+  down(messageOrMessages, options) {
+    const messages = normalizeMessages(messageOrMessages);
+    if (messages.length === 0) return;
+    this._checkGuard(options);
+    this._emit(messages);
+  }
+  emit(value, options) {
+    this._checkGuard(options);
+    this._emit([[DATA, value]]);
+  }
+  up(messageOrMessages, options) {
+    if (this._deps.length === 0) return;
+    const messages = normalizeMessages(messageOrMessages);
+    if (messages.length === 0) return;
+    this._checkGuard(options);
+    const forwardOpts = options ?? { internal: true };
+    this._validateUpTiers(messages);
+    for (const d of this._deps) {
+      d.node.up?.(messages, forwardOpts);
+    }
+  }
+  /**
+   * @internal Internal up-path used by `actions.up(...)` from inside fn.
+   * Same tier validation as public `up`, but bypasses the guard check
+   * since the fn context is already inside an authorized operation.
+   */
+  _emitUp(messages) {
+    if (this._deps.length === 0) return;
+    if (messages.length === 0) return;
+    this._validateUpTiers(messages);
+    for (const d of this._deps) {
+      d.node.up?.(messages, { internal: true });
+    }
+  }
+  /**
+   * @internal Enforce spec §1.2 — up-direction messages are restricted to
+   * tier 0–2 and tier 5 (START, DIRTY, INVALIDATE, PAUSE, RESUME,
+   * TEARDOWN). Tier 3 (DATA/RESOLVED) and tier 4 (COMPLETE/ERROR) are
+   * downstream-only. Emitting tier-3/4 via `up` would bypass equals
+   * substitution and cache advance entirely and is a protocol bug.
+   */
+  _validateUpTiers(messages) {
+    const tierOf = this._config.tierOf;
+    for (const m of messages) {
+      const tier = tierOf(m[0]);
+      if (tier === 3 || tier === 4) {
+        throw new Error(
+          `Node "${this.name}": tier-${tier} messages cannot flow up \u2014 DATA/RESOLVED/COMPLETE/ERROR are downstream-only. Use \`down(...)\` for value delivery; \`up(...)\` is for control signals (DIRTY, INVALIDATE, PAUSE, RESUME, TEARDOWN).`
+        );
+      }
+    }
+  }
+  subscribe(sink, actor) {
+    if (actor != null && this._guard != null) {
+      const a = normalizeActor(actor);
+      if (!this._guard(a, "observe")) {
+        throw new GuardDenied({ actor: a, action: "observe", nodeName: this.name });
+      }
+    }
+    const wasTerminal = this._isTerminal;
+    const afterTerminalReset = wasTerminal && this._resubscribable;
+    if (afterTerminalReset) {
+      this._cached = void 0;
+      this._status = "sentinel";
+      this._store = {};
+      this._hasCalledFnOnce = false;
+      this._waveHasNewData = false;
+      this._hasNewTerminal = false;
+      this._paused = false;
+      this._pendingWave = false;
+      this._pendingRerun = false;
+      this._isExecutingFn = false;
+      this._rerunDepth = 0;
+      this._dirtyDepCount = 0;
+      this._pauseLocks = null;
+      this._pauseBuffer = null;
+      for (const d of this._deps) resetDepRecord(d);
+    }
+    this._sinkCount += 1;
+    let subCleanup;
+    try {
+      subCleanup = this._config.onSubscribe(
+        this,
+        sink,
+        { sinkCount: this._sinkCount, afterTerminalReset },
+        this._actions
+      );
+    } catch (err) {
+      this._sinkCount -= 1;
+      throw err;
+    }
+    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);
+    }
+    const isTerminalNow = this._isTerminal;
+    if (this._sinkCount === 1 && !isTerminalNow) {
+      try {
+        this._activate();
+      } catch (err) {
+        this._sinkCount -= 1;
+        this._removeSink(sink);
+        if (this._sinkCount === 0) this._status = "sentinel";
+        if (typeof subCleanup === "function") {
+          try {
+            subCleanup();
+          } catch {
+          }
+        }
+        throw err;
+      }
+    }
+    if (this._status === "sentinel" && this._cached === void 0) {
+      this._status = "pending";
+    }
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this._sinkCount -= 1;
+      this._removeSink(sink);
+      if (typeof subCleanup === "function") subCleanup();
+      if (this._sinks == null) this._deactivate();
+    };
+  }
+  _removeSink(sink) {
+    if (this._sinks === sink) {
+      this._sinks = null;
+    } else if (this._sinks != null && typeof this._sinks !== "function") {
+      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;
+      }
+    }
+  }
+  // --- Lifecycle ---
+  /**
+   * @internal First-sink activation. For a producer (no deps + fn),
+   * invokes fn once. For a compute node (has deps), subscribes to every
+   * dep with the pre-set-dirty trick so the first-run gate waits for
+   * every dep to settle at least once.
+   */
+  _activate() {
+    if (this._deps.length === 0) {
+      if (this._fn) this._execFn();
+      return;
+    }
+    this._dirtyDepCount = 0;
+    const initialLen = this._deps.length;
+    let subscribedCount = 0;
+    try {
+      for (let i = 0; i < initialLen; i++) {
+        const depIdx = i;
+        const dep = this._deps[i];
+        dep.unsub = noopUnsub;
+        dep.unsub = dep.node.subscribe((msgs) => {
+          if (dep.unsub === null) return;
+          const tierOf = this._config.tierOf;
+          let sawSettlement = false;
+          for (const m of msgs) {
+            if (tierOf(m[0]) >= 3) sawSettlement = true;
+            this._config.onMessage(
+              this,
+              m,
+              { direction: "down-in", depIndex: depIdx },
+              this._actions
+            );
+          }
+          if (sawSettlement) this._maybeRunFnOnSettlement();
+        });
+        subscribedCount++;
+      }
+    } catch (err) {
+      this._deps[subscribedCount].unsub = null;
+      for (let j = 0; j < subscribedCount; j++) {
+        const d = this._deps[j];
+        if (d.unsub != null) {
+          const u = d.unsub;
+          d.unsub = null;
+          try {
+            u();
+          } catch {
+          }
+          resetDepRecord(d);
+        }
+      }
+      this._dirtyDepCount = 0;
+      throw err;
+    }
+  }
+  /**
+   * @internal Append a dep post-construction. Used by `autoTrackNode`
+   * (runtime dep discovery) and `Graph.connect()` (post-construction
+   * wiring). Subscribes immediately — if DATA arrives synchronously
+   * during subscribe and fn is currently executing, the re-run is
+   * deferred via `_pendingRerun` flag (see `_execFn` guard).
+   *
+   * **Dedup:** idempotent on duplicate `depNode` — if `depNode` is
+   * already in `_deps`, returns the existing index without mutating
+   * state. Callers can safely invoke `_addDep` without their own
+   * "already added" check. `autoTrackNode` still keeps a `depIndexMap`
+   * as a fast-path lookup for known deps (returning cached `data[idx]`
+   * without calling `_addDep` at all); this internal dedup is the
+   * backstop for any caller that doesn't track its own dep set.
+   *
+   * @returns The index of the new dep in `_deps`, or the existing index
+   *   if the dep was already present.
+   */
+  _addDep(depNode) {
+    for (let i = 0; i < this._deps.length; i++) {
+      if (this._deps[i].node === depNode) return i;
+    }
+    const depIdx = this._deps.length;
+    const record = createDepRecord(depNode);
+    this._deps.push(record);
+    if (this._sinks == null) return depIdx;
+    record.dirty = true;
+    this._dirtyDepCount++;
+    if (this._status !== "dirty") this._emit(DIRTY_ONLY_BATCH);
+    record.unsub = noopUnsub;
+    try {
+      record.unsub = depNode.subscribe((msgs) => {
+        if (record.unsub === null) return;
+        const tierOf = this._config.tierOf;
+        let sawSettlement = false;
+        for (const m of msgs) {
+          if (tierOf(m[0]) >= 3) sawSettlement = true;
+          this._config.onMessage(
+            this,
+            m,
+            { direction: "down-in", depIndex: depIdx },
+            this._actions
+          );
+        }
+        if (sawSettlement) this._maybeRunFnOnSettlement();
+      });
+    } catch (err) {
+      record.unsub = null;
+      this._deps.pop();
+      this._dirtyDepCount--;
+      throw err;
+    }
+    return depIdx;
+  }
+  /**
+   * @internal Unsubscribes from deps, fires fn cleanup (both shapes),
+   * clears wave/store state, and (for compute nodes) drops `_cached` per
+   * the ROM/RAM rule. Idempotent: second call is a no-op.
+   *
+   * @param skipStatusUpdate — When `true`, the caller takes responsibility
+   *   for setting `_status` after deactivation (e.g. TEARDOWN always sets
+   *   `"sentinel"` unconditionally). When `false` (default), deactivation
+   *   applies the ROM rule: compute nodes → `"sentinel"`, state nodes
+   *   preserve their current status.
+   */
+  _deactivate(skipStatusUpdate = false) {
+    const cleanup = this._cleanup;
+    this._cleanup = void 0;
+    if (typeof cleanup === "function") {
+      try {
+        cleanup();
+      } catch (err) {
+        this._emit([[ERROR, this._wrapFnError("cleanup threw", err)]]);
+      }
+    } else if (cleanup != null && typeof cleanup.deactivation === "function") {
+      try {
+        cleanup.deactivation();
+      } catch (err) {
+        this._emit([[ERROR, this._wrapFnError("cleanup.deactivation threw", err)]]);
+      }
+    }
+    for (const d of this._deps) {
+      if (d.unsub != null) {
+        const u = d.unsub;
+        d.unsub = null;
+        try {
+          u();
+        } catch {
+        }
+      }
+      resetDepRecord(d);
+    }
+    this._waveHasNewData = false;
+    this._hasNewTerminal = false;
+    this._hasCalledFnOnce = false;
+    this._paused = false;
+    this._pendingWave = false;
+    this._pendingRerun = false;
+    this._rerunDepth = 0;
+    this._store = {};
+    this._dirtyDepCount = 0;
+    this._pauseLocks = null;
+    this._pauseBuffer = null;
+    if (this._fn != null) {
+      this._cached = void 0;
+    }
+    if (!skipStatusUpdate) {
+      if (this._fn != null || this._deps.length > 0) {
+        if (!this._isTerminal || this._resubscribable) {
+          this._status = "sentinel";
+        }
+      }
+    }
+  }
+  // --- Dep message dispatch (§3.5 singleton default) ---
+  /**
+   * @internal Default per-tier dispatch for incoming dep messages. Called
+   * by `defaultOnMessage`. Updates the DepRecord, triggers wave
+   * completion, and forwards passthrough traffic.
+   */
+  _onDepMessage(depIndex, msg) {
+    const dep = this._deps[depIndex];
+    const t = msg[0];
+    if (this._inspectorHooks != null) {
+      const ev = { kind: "dep_message", depIndex, message: msg };
+      for (const hook of this._inspectorHooks) hook(ev);
+    }
+    if (t === START) return;
+    if (t === DIRTY) {
+      this._depDirtied(dep);
+      return;
+    }
+    if (t === INVALIDATE) {
+      this._depInvalidated(dep);
+      this._emit(INVALIDATE_ONLY_BATCH);
+      return;
+    }
+    if (t === PAUSE || t === RESUME) {
+      this._emit([msg]);
+      return;
+    }
+    if (t === TEARDOWN) {
+      this._emit(TEARDOWN_ONLY_BATCH);
+      return;
+    }
+    if (t === DATA) {
+      this._depSettledAsData(dep, msg[1]);
+    } else if (t === RESOLVED) {
+      this._depSettledAsResolved(dep);
+    } else if (t === COMPLETE) {
+      this._depSettledAsTerminal(dep, true);
+    } else if (t === ERROR) {
+      this._depSettledAsTerminal(dep, msg[1]);
+    } else {
+      this._emit([msg]);
+      return;
+    }
+    if (!this._fn) {
+      if (t === DATA || t === RESOLVED) {
+        this._emit([msg]);
+      }
+      if (t === COMPLETE || t === ERROR) {
+        this._maybeAutoTerminalAfterWave();
+      }
+      return;
+    }
+  }
+  // --- Centralized dep-state transitions (A3 settlement counters) ---
+  //
+  // Every mutation to `DepRecord.dirty` / `DepRecord.prevData` /
+  // `DepRecord.terminal` must go through one of these helpers so the
+  // `_dirtyDepCount` and `_sentinelDepCount` counters stay in sync with
+  // the per-record flags. `_maybeRunFnOnSettlement` reads the counters
+  // and never re-scans the `_deps` array.
+  /**
+   * Called when a dep transitions `dirty: false → true` (either from an
+   * incoming DIRTY, or pre-set during `_activate` / `_addDep` /
+   * `_depInvalidated`). No-op if the dep is already dirty. Fires the
+   * downstream DIRTY emit if we're the first to dirty this wave.
+   */
+  _depDirtied(dep) {
+    if (dep.dirty) return;
+    dep.dirty = true;
+    dep.involvedThisWave = true;
+    this._dirtyDepCount++;
+    if (this._status !== "dirty") {
+      this._emit(DIRTY_ONLY_BATCH);
+    }
+  }
+  /**
+   * Called when a dep delivers new DATA: clears dirty, stores the payload,
+   * marks wave-has-data, and — if this is the dep's first DATA — clears
+   * its sentinel slot so the first-run gate can open.
+   */
+  _depSettledAsData(dep, value) {
+    if (dep.dirty) {
+      dep.dirty = false;
+      this._dirtyDepCount--;
+    }
+    dep.involvedThisWave = true;
+    dep.dataBatch.push(value);
+    this._waveHasNewData = true;
+  }
+  /**
+   * Called when a dep emits RESOLVED (wave settled, value unchanged).
+   * Clears dirty; does NOT touch `prevData` / `terminal` / sentinel
+   * count — sentinel only exits on first DATA or terminal, not RESOLVED.
+   */
+  _depSettledAsResolved(dep) {
+    if (dep.dirty) {
+      dep.dirty = false;
+      this._dirtyDepCount--;
+    }
+  }
+  /**
+   * Called when a dep delivers COMPLETE (`terminal = true`) or ERROR
+   * (`terminal = errorPayload`). Clears dirty, stores the terminal, and
+   * — if the dep had never contributed a DATA yet — leaves sentinel
+   * since the gate treats "terminated without data" as gate-open too.
+   */
+  _depSettledAsTerminal(dep, terminal) {
+    if (dep.dirty) {
+      dep.dirty = false;
+      this._dirtyDepCount--;
+    }
+    dep.terminal = terminal;
+    dep.involvedThisWave = true;
+    this._hasNewTerminal = true;
+  }
+  /**
+   * Called when a dep emits INVALIDATE: clears prevData, terminal, and
+   * dataBatch. The dep is now back in the "never delivered a real value"
+   * state — `prevData === undefined` so the sentinel check in fn will fire.
+   */
+  _depInvalidated(dep) {
+    dep.prevData = void 0;
+    dep.terminal = void 0;
+    dep.dataBatch.length = 0;
+    if (!dep.dirty) {
+      dep.dirty = true;
+      dep.involvedThisWave = true;
+      this._dirtyDepCount++;
+    } else {
+      dep.involvedThisWave = false;
+    }
+  }
+  _maybeRunFnOnSettlement() {
+    if (this._isTerminal && !this._resubscribable) return;
+    if (this._dirtyDepCount > 0) return;
+    if (this._paused) {
+      this._pendingWave = true;
+      return;
+    }
+    if (!this._waveHasNewData && !this._hasNewTerminal && this._hasCalledFnOnce) {
+      this._clearWaveFlags();
+      this._emit(RESOLVED_ONLY_BATCH);
+      this._maybeAutoTerminalAfterWave();
+      return;
+    }
+    if (this._fn) this._execFn();
+    this._maybeAutoTerminalAfterWave();
+  }
+  _maybeAutoTerminalAfterWave() {
+    if (this._deps.length === 0) return;
+    if (this._isTerminal) return;
+    const erroredDep = this._deps.find((d) => d.terminal !== void 0 && d.terminal !== true);
+    if (erroredDep != null) {
+      if (this._autoError) {
+        this._emit([[ERROR, erroredDep.terminal]]);
+      }
+      return;
+    }
+    if (this._autoComplete && this._deps.every((d) => d.terminal !== void 0)) {
+      this._emit(COMPLETE_ONLY_BATCH);
+    }
+  }
+  // --- Fn execution ---
+  /**
+   * @internal Runs the node fn once. Default cleanup (function form) fires
+   * before the new run; `{ deactivation }` cleanup survives.
+   */
+  _execFn() {
+    if (!this._fn) return;
+    if (this._isTerminal && !this._resubscribable) return;
+    if (this._isExecutingFn) {
+      this._pendingRerun = true;
+      return;
+    }
+    const prevCleanup = this._cleanup;
+    if (typeof prevCleanup === "function") {
+      this._cleanup = void 0;
+      try {
+        prevCleanup();
+      } catch (err) {
+        this._emit([[ERROR, this._wrapFnError("cleanup threw", err)]]);
+        return;
+      }
+    }
+    const batchData = this._deps.map(
+      (d) => !d.involvedThisWave ? void 0 : d.dataBatch.length > 0 ? [...d.dataBatch] : []
+    );
+    const prevData = this._deps.map((d) => d.prevData);
+    for (let i = 0; i < this._deps.length; i++) {
+      const batch2 = batchData[i];
+      if (batch2 != null && batch2.length > 0) {
+        this._deps[i].prevData = batch2[batch2.length - 1];
+      }
+    }
+    const terminalDeps = this._deps.map((d) => d.terminal);
+    const ctx = { prevData, terminalDeps, store: this._store };
+    this._hasCalledFnOnce = true;
+    this._clearWaveFlags();
+    if (this._inspectorHooks != null) {
+      const ev = { kind: "run", batchData, prevData };
+      for (const hook of this._inspectorHooks) hook(ev);
+    }
+    this._isExecutingFn = true;
+    try {
+      const result = this._fn(batchData, this._actions, ctx);
+      if (typeof result === "function") {
+        this._cleanup = result;
+      } else if (result != null && typeof result === "object" && typeof result.deactivation === "function") {
+        this._cleanup = result;
+      }
+    } catch (err) {
+      this._emit([[ERROR, this._wrapFnError("fn threw", err)]]);
+    } finally {
+      this._isExecutingFn = false;
+      if (this._pendingRerun) {
+        this._pendingRerun = false;
+        this._rerunDepth += 1;
+        if (this._rerunDepth > MAX_RERUN_DEPTH) {
+          this._rerunDepth = 0;
+          this._emit([
+            [
+              ERROR,
+              new Error(
+                `Node "${this.name}": _pendingRerun depth exceeded ${MAX_RERUN_DEPTH} \u2014 likely a reactive cycle`
+              )
+            ]
+          ]);
+        } else {
+          this._maybeRunFnOnSettlement();
+        }
+      } else {
+        this._rerunDepth = 0;
+      }
+      this._clearWaveFlags();
+    }
+  }
+  _clearWaveFlags() {
+    this._waveHasNewData = false;
+    this._hasNewTerminal = false;
+    for (const d of this._deps) {
+      d.involvedThisWave = false;
+      d.dataBatch.length = 0;
+    }
+  }
+  _wrapFnError(label, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Error(`Node "${this.name}": ${label}: ${msg}`, { cause: err });
+  }
+  // --- Framing (tier sort + synthetic DIRTY prefix) ---
+  /**
+   * @internal Stable tier sort + synthetic DIRTY prefix for an outgoing
+   * batch. Fast path: already-monotone single-tier batches (the common
+   * case from interned singletons like `DIRTY_ONLY_BATCH`) return the
+   * input unchanged. General path: decorate-sort-undecorate into a new
+   * array, then prepend `[DIRTY]` after any tier-0 START entries when
+   * a tier-3 payload is present and the node isn't already dirty.
+   *
+   * Single source of truth for the spec §1.3.1 framing invariant. Every
+   * outgoing path hits `_frameBatch` exactly once via `_emit`.
+   */
+  _frameBatch(messages) {
+    const tierOf = this._config.tierOf;
+    if (messages.length === 1) {
+      const t = tierOf(messages[0][0]);
+      if (t === 3 && this._status !== "dirty") {
+        return [DIRTY_MSG, messages[0]];
+      }
+      return messages;
+    }
+    let monotone = true;
+    let hasTier3 = false;
+    let hasDirty = false;
+    let prevTier = -1;
+    for (const m of messages) {
+      const tier = tierOf(m[0]);
+      if (tier < prevTier) monotone = false;
+      if (tier === 3) hasTier3 = true;
+      if (m[0] === DIRTY) hasDirty = true;
+      prevTier = tier;
+    }
+    let sorted = messages;
+    if (!monotone) {
+      const indexed = messages.map((m, i) => ({ m, i, tier: tierOf(m[0]) }));
+      indexed.sort((a, b) => a.tier - b.tier || a.i - b.i);
+      sorted = indexed.map((x) => x.m);
+    }
+    if (hasTier3 && !hasDirty && this._status !== "dirty") {
+      let insertAt = 0;
+      while (insertAt < sorted.length && tierOf(sorted[insertAt][0]) === 0) insertAt++;
+      if (insertAt === 0) return [DIRTY_MSG, ...sorted];
+      return [...sorted.slice(0, insertAt), DIRTY_MSG, ...sorted.slice(insertAt)];
+    }
+    return sorted;
+  }
+  // --- Emit pipeline ---
+  /**
+   * @internal The unified dispatch waist — one call = one wave.
+   * See `GRAPHREFLY-SPEC.md` §1.3.1 for protocol context — the stages
+   * below are the implementation order.
+   *
+   * Pipeline stages, in order:
+   *
+   *   1. Terminal filter — post-COMPLETE/ERROR only TEARDOWN/INVALIDATE
+   *      still propagate so graph teardown and cache-clear still work.
+   *   2. Tier sort (stable) — the batch can be in any order when it
+   *      arrives; the walker downstream (`downWithBatch`) assumes
+   *      ascending tier monotone, and so does `_updateState`'s tier-3
+   *      slice walk. This is the single source of truth for ordering.
+   *   3. Synthetic DIRTY prefix — if a tier-3 payload is present, no
+   *      DIRTY is already in the batch, and the node isn't already in
+   *      `"dirty"` status, prepend `[DIRTY]` after any tier-0 START
+   *      entries. Guarantees spec §1.3.1 (DIRTY precedes DATA within
+   *      the same batch) uniformly across every entry point.
+   *   4. PAUSE/RESUME lock bookkeeping (C0) — update `_pauseLocks`,
+   *      derive `_paused`, filter unknown-lockId RESUME, replay
+   *      bufferAll buffer on final lock release.
+   *   5. Meta TEARDOWN fan-out — notify meta children before
+   *      `_updateState`'s TEARDOWN branch calls `_deactivate`. Hoisted
+   *      out of the walk to keep `_updateState` re-entrance-free.
+   *   6. `_updateState` — walk the batch in tier order, advancing
+   *      `_cached` / `_status` / `_versioning` and running equals
+   *      substitution on tier-3 DATA (§3.5.1). Returns
+   *      `{finalMessages, equalsError?}`.
+   *   7. `downWithBatch` dispatch (or bufferAll capture if paused with
+   *      `pausable: "resumeAll"`).
+   *   8. Recursive ERROR emission if equals threw mid-walk.
+   */
+  _emit(messages) {
+    if (messages.length === 0) return;
+    let deliverable = messages;
+    const terminal = this._isTerminal;
+    if (terminal && !this._resubscribable) {
+      const pass = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
+      if (pass.length === 0) return;
+      deliverable = pass;
+    }
+    deliverable = this._frameBatch(deliverable);
+    let filtered = null;
+    for (let i = 0; i < deliverable.length; i++) {
+      const m = deliverable[i];
+      const t = m[0];
+      if (t !== PAUSE && t !== RESUME) {
+        if (filtered != null) filtered.push(m);
+        continue;
+      }
+      if (m.length < 2) {
+        throw new Error(
+          `Node "${this.name}": [[${t === PAUSE ? "PAUSE" : "RESUME"}]] must carry a lockId payload \u2014 bare PAUSE/RESUME is a protocol violation (C0 rule). Use \`[[PAUSE, lockId]]\` / \`[[RESUME, lockId]]\`.`
+        );
+      }
+      let forward = true;
+      if (this._pausable !== false) {
+        const lockId = m[1];
+        if (t === PAUSE) {
+          if (this._pauseLocks == null) this._pauseLocks = /* @__PURE__ */ new Set();
+          this._pauseLocks.add(lockId);
+          this._paused = true;
+          if (this._pausable === "resumeAll" && this._pauseBuffer == null) {
+            this._pauseBuffer = [];
+          }
+        } else {
+          if (this._pauseLocks == null || !this._pauseLocks.has(lockId)) {
+            forward = false;
+          } else {
+            this._pauseLocks.delete(lockId);
+            if (this._pauseLocks.size === 0) {
+              this._paused = false;
+              if (this._pauseBuffer != null && this._pauseBuffer.length > 0) {
+                const drain = this._pauseBuffer;
+                this._pauseBuffer = [];
+                this._emit(drain);
+              }
+              if (this._pendingWave) {
+                this._pendingWave = false;
+                this._maybeRunFnOnSettlement();
+              }
+            }
+          }
+        }
+      }
+      if (!forward) {
+        if (filtered == null) filtered = deliverable.slice(0, i);
+      } else if (filtered != null) {
+        filtered.push(m);
+      }
+    }
+    if (filtered != null) {
+      if (filtered.length === 0) return;
+      deliverable = filtered;
+    }
+    if (this._hasMeta && deliverable.some((m) => m[0] === TEARDOWN)) {
+      for (const k of Object.keys(this.meta)) {
+        try {
+          this.meta[k]._emit(TEARDOWN_ONLY_BATCH);
+        } catch {
+        }
+      }
+    }
+    const { finalMessages, equalsError } = this._updateState(deliverable);
+    if (finalMessages.length > 0 && this._config.inspectorEnabled) {
+      const inspector = this._config.globalInspector;
+      if (inspector != null) {
+        try {
+          inspector({ kind: "emit", node: this, messages: finalMessages });
+        } catch {
+        }
+      }
+    }
+    if (finalMessages.length > 0) {
+      if (this._paused && this._pausable === "resumeAll" && this._pauseBuffer != null) {
+        const tierOf = this._config.tierOf;
+        const immediate = [];
+        for (const m of finalMessages) {
+          const tier = tierOf(m[0]);
+          if (tier < 3 || tier === 5) {
+            immediate.push(m);
+          } else {
+            this._pauseBuffer.push(m);
+          }
+        }
+        if (immediate.length > 0) {
+          this._dispatchOrAccumulate(immediate);
+        }
+      } else {
+        this._dispatchOrAccumulate(finalMessages);
+      }
+    }
+    if (equalsError != null) {
+      this._emit([[ERROR, equalsError]]);
+    }
+  }
+  /**
+   * @internal Walk an outgoing (already-framed) batch, updating own
+   * cache / status / versioning and running equals substitution on
+   * every tier-3 DATA (§3.5.1). Framing — tier sort and synthetic
+   * DIRTY prefix — has already happened upstream in `_frameBatch`.
+   * This walk trusts the input is in monotone tier order and that the
+   * spec §1.3.1 DIRTY/RESOLVED precedence invariant is already
+   * satisfied by the frame.
+   *
+   * Equals substitution: every DATA payload is compared against the
+   * live `_cached`; when equal, the tuple is rewritten to `[RESOLVED]`
+   * in a per-call copy and cache is not re-advanced. `.cache` remains
+   * coherent with "the last DATA payload this node actually sent
+   * downstream".
+   *
+   * Returns `{ finalMessages, equalsError? }`:
+   * - `finalMessages` — the array to deliver to sinks (may be
+   *   `messages` unchanged, a rewritten copy with DATA→RESOLVED
+   *   substitutions, or a truncated prefix when equals throws mid-walk).
+   * - `equalsError` — present only when the configured `equals` function
+   *   threw on some DATA message. `_emit` delivers the prefix first,
+   *   then emits a fresh ERROR batch via a recursive `_emit` call so
+   *   subscribers observe `[...walked_prefix, ERROR]` in order.
+   */
+  _updateState(messages) {
+    const tierOf = this._config.tierOf;
+    let rewritten;
+    let equalsError;
+    let abortedAt = -1;
+    let dataCount = 0;
+    for (const m of messages) {
+      if (tierOf(m[0]) === 3) dataCount++;
+    }
+    const checkEquals = dataCount <= 1;
+    let lastDataIdx = -1;
+    if (this._versioning != null && dataCount > 1) {
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i][0] === DATA) {
+          lastDataIdx = i;
+          break;
+        }
+      }
+    }
+    for (let i = 0; i < messages.length; i++) {
+      const m = messages[i];
+      const t = m[0];
+      if (t === DATA) {
+        if (m.length >= 2) {
+          let unchanged = false;
+          if (checkEquals && this._cached !== void 0) {
+            try {
+              unchanged = this._equals(this._cached, m[1]);
+            } catch (err) {
+              equalsError = this._wrapFnError("equals threw", err);
+              abortedAt = i;
+              break;
+            }
+          }
+          if (unchanged) {
+            if (rewritten == null) rewritten = messages.slice(0, i);
+            rewritten.push(RESOLVED_MSG);
+            this._status = "resolved";
+            continue;
+          }
+          this._cached = m[1];
+          if (this._versioning != null) {
+            if (lastDataIdx < 0 || i === lastDataIdx) {
+              advanceVersion(this._versioning, m[1], this._hashFn);
+            }
+          }
+        }
+        this._status = "settled";
+        if (rewritten != null) rewritten.push(m);
+      } else {
+        if (rewritten != null) rewritten.push(m);
+        if (t === DIRTY) {
+          this._status = "dirty";
+        } else if (t === RESOLVED) {
+          this._status = "resolved";
+        } else if (t === COMPLETE) {
+          this._status = "completed";
+        } else if (t === ERROR) {
+          this._status = "errored";
+        } else if (t === INVALIDATE) {
+          this._cached = void 0;
+          this._status = "dirty";
+          const c = this._cleanup;
+          if (typeof c === "function") {
+            this._cleanup = void 0;
+            try {
+              c();
+            } catch {
+            }
+          }
+        } else if (t === TEARDOWN) {
+          if (this._resetOnTeardown) this._cached = void 0;
+          this._deactivate(
+            /* skipStatusUpdate */
+            true
+          );
+          this._status = "sentinel";
+        }
+      }
+    }
+    const base = abortedAt >= 0 ? rewritten ?? messages.slice(0, abortedAt) : rewritten ?? messages;
+    return equalsError != null ? { finalMessages: base, equalsError } : { finalMessages: base };
+  }
+  _deliverToSinks = (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);
+  };
+  /**
+   * @internal Dispatch entry point that respects the per-batch emit
+   * accumulator (Bug 2). Inside an explicit `batch()` scope, append to
+   * `_batchPendingMessages` and register a flush hook on first append.
+   * Outside batch — or during a drain (where `flushInProgress` is true
+   * but `batchDepth` is 0) — dispatch synchronously through `downWithBatch`.
+   *
+   * Per-emit state updates (`_frameBatch`, `_updateState`) have already
+   * happened by the time we reach here; only the **downstream delivery**
+   * is coalesced. Cache, version, and status are visible mid-batch on
+   * the emitting node itself.
+   */
+  _dispatchOrAccumulate(messages) {
+    if (isExplicitlyBatching()) {
+      if (this._batchPendingMessages === null) {
+        this._batchPendingMessages = [];
+        registerBatchFlushHook(() => this._flushBatchPending());
+      }
+      for (const m of messages) this._batchPendingMessages.push(m);
+      return;
+    }
+    downWithBatch(this._deliverToSinks, messages, this._config.tierOf);
+  }
+  /**
+   * @internal Flushes the accumulated batch through `downWithBatch` and
+   * clears the pending state. Idempotent — safe to call when pending is
+   * already null or empty (e.g. on a `batch()` throw, where the hook
+   * fires for cleanup but the drainPhase queues are wiped after).
+   *
+   * Critical: the accumulated batch is interleaved per-emit framings like
+   * `[DIRTY, DATA(1), DIRTY, DATA(2)]` — non-monotone tier order. We must
+   * re-frame to sort by tier before handing to `downWithBatch`, which
+   * assumes pre-sorted input. `_frameBatch` also handles the synthetic
+   * DIRTY prepend rule (no-op here — `hasDirty` is true since each
+   * accumulated emit already carries its own DIRTY prefix).
+   */
+  _flushBatchPending() {
+    const pending = this._batchPendingMessages;
+    if (pending === null) return;
+    this._batchPendingMessages = null;
+    if (pending.length === 0) return;
+    const framed = this._frameBatch(pending);
+    downWithBatch(this._deliverToSinks, framed, this._config.tierOf);
+  }
+};
+var isNodeArray = (value) => Array.isArray(value);
+var isNodeOptionsObject = (value) => typeof value === "object" && value != null && !Array.isArray(value);
+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 = (isNodeOptionsObject(fnOrOpts) ? fnOrOpts : optsArg) ?? {};
+  } else if (isNodeOptionsObject(depsOrFn)) {
+    opts = depsOrFn;
+  } else {
+    opts = (isNodeOptionsObject(fnOrOpts) ? fnOrOpts : optsArg) ?? {};
+  }
+  return new NodeImpl(deps, fn, opts);
+}
+
+// src/core/sugar.ts
+function state(initial, opts) {
+  return node([], { ...opts, initial });
+}
+function producer(fn, opts) {
+  const wrapped = (_data, actions, ctx) => fn(actions, ctx) ?? void 0;
+  return node(wrapped, { describeKind: "producer", ...opts });
+}
+
+// src/core/meta.ts
+function resolveDescribeFields(detail, fields) {
+  if (fields != null && fields.length > 0) return new Set(fields);
+  switch (detail) {
+    case "standard":
+      return /* @__PURE__ */ new Set(["type", "status", "value", "deps", "meta", "v"]);
+    case "full":
+      return null;
+    default:
+      return /* @__PURE__ */ new Set(["type", "deps"]);
+  }
+}
+function inferDescribeType(n) {
+  if (n._describeKind != null) return n._describeKind;
+  const hasDeps = n._deps.length > 0;
+  if (!hasDeps) return n._fn != null ? "producer" : "state";
+  return "derived";
+}
+function metaSnapshot(node2) {
+  const out = {};
+  for (const [key, child] of Object.entries(node2.meta)) {
+    try {
+      out[key] = child.cache;
+    } catch {
+    }
+  }
+  return out;
+}
+function describeNode(node2, includeFields) {
+  const all = includeFields == null;
+  const metaKeys = !all && includeFields != null ? [...includeFields].filter((f) => f.startsWith("meta.")).map((f) => f.slice(5)) : null;
+  const wantsMeta = all || includeFields.has("meta") || metaKeys != null && metaKeys.length > 0;
+  let type = "state";
+  let deps = [];
+  if (node2 instanceof NodeImpl) {
+    type = inferDescribeType(node2);
+    deps = node2._deps.map((d) => d.node.name ?? "");
+  }
+  const out = { type, deps };
+  if (all || includeFields.has("status")) {
+    out.status = node2.status;
+  }
+  const guard = node2 instanceof NodeImpl ? node2._guard : void 0;
+  if (wantsMeta) {
+    const rawMeta = { ...metaSnapshot(node2) };
+    if (guard != null && rawMeta.access === void 0) {
+      rawMeta.access = accessHintForGuard(guard);
+    }
+    if (metaKeys != null && metaKeys.length > 0 && !includeFields.has("meta")) {
+      const filtered = {};
+      for (const k of metaKeys) {
+        if (k in rawMeta) filtered[k] = rawMeta[k];
+      }
+      out.meta = filtered;
+    } else {
+      out.meta = rawMeta;
+    }
+  }
+  if (node2.name != null) {
+    out.name = node2.name;
+  }
+  if (all || includeFields.has("value")) {
+    if (node2.status === "sentinel") out.sentinel = true;
+    try {
+      out.value = node2.cache;
+    } catch {
+    }
+  }
+  if ((all || includeFields.has("v")) && 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;
+  }
+  if (all || includeFields.has("guard")) {
+    if (guard != null) out.guard = accessHintForGuard(guard);
+  }
+  if (all || includeFields.has("lastMutation")) {
+    if (node2.lastMutation != null) out.lastMutation = node2.lastMutation;
+  }
+  return out;
+}
+
+// src/extra/timer.ts
+var ResettableTimer = class {
+  _timer;
+  _gen = 0;
+  /** Schedule callback after delayMs. Cancels any pending timer. */
+  start(delayMs, callback) {
+    this.cancel();
+    this._gen += 1;
+    const gen = this._gen;
+    this._timer = setTimeout(() => {
+      this._timer = void 0;
+      if (gen !== this._gen) return;
+      callback();
+    }, delayMs);
+  }
+  /** Cancel the pending timer (if any). */
+  cancel() {
+    if (this._timer !== void 0) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+  }
+  /** Whether a timer is currently pending. */
+  get pending() {
+    return this._timer !== void 0;
+  }
+};
+
+// src/extra/utils/ring-buffer.ts
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`RingBuffer capacity must be a positive integer (got ${capacity})`);
+    }
+    this.buf = new Array(capacity);
+  }
+  buf;
+  head = 0;
+  _size = 0;
+  /** Current number of stored entries. */
+  get size() {
+    return this._size;
+  }
+  /** Configured maximum before drop-oldest eviction fires. */
+  get maxSize() {
+    return this.capacity;
+  }
+  /**
+   * Append an item. If size equals capacity, drops the oldest entry and
+   * advances the head pointer.
+   */
+  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;
+  }
+  /** Remove and return the oldest entry; `undefined` when empty. */
+  shift() {
+    if (this._size === 0) return void 0;
+    const item = this.buf[this.head];
+    this.buf[this.head] = void 0;
+    this.head = (this.head + 1) % this.capacity;
+    this._size--;
+    return item;
+  }
+  /**
+   * O(1) index lookup. Negative indices count from the tail (Python-style).
+   * Returns `undefined` for out-of-range.
+   */
+  at(i) {
+    if (this._size === 0) return void 0;
+    const n = i < 0 ? this._size + i : i;
+    if (n < 0 || n >= this._size) return void 0;
+    return this.buf[(this.head + n) % this.capacity];
+  }
+  /**
+   * Materialize the contents in insertion order (oldest → newest).
+   * Returns a new array each call.
+   */
+  toArray() {
+    const result = new Array(this._size);
+    for (let i = 0; i < this._size; i++) {
+      result[i] = this.buf[(this.head + i) % this.capacity];
+    }
+    return result;
+  }
+  /** Reset to empty. Storage slots are released so held refs can GC. */
+  clear() {
+    for (let i = 0; i < this._size; i++) {
+      this.buf[(this.head + i) % this.capacity] = void 0;
+    }
+    this.head = 0;
+    this._size = 0;
+  }
+};
+
+// src/graph/explain.ts
+function explainPath(described, from, to, opts = {}) {
+  const fromExists = from in described.nodes;
+  const toExists = to in described.nodes;
+  if (!fromExists) return makeFailure(from, to, "no-such-from");
+  if (!toExists) return makeFailure(from, to, "no-such-to");
+  const maxDepth = opts.maxDepth;
+  if (maxDepth != null && (!Number.isInteger(maxDepth) || maxDepth < 0)) {
+    throw new Error(`explainPath: maxDepth must be an integer >= 0`);
+  }
+  if (from === to) {
+    if (opts.findCycle === true) {
+      const cycle = findShortestCycle(described, from, opts);
+      if (cycle != null) return cycle;
+    }
+    const step = buildStep(from, described.nodes[from], 0, opts);
+    return makeSuccess(from, to, [step]);
+  }
+  if (maxDepth === 0) return makeFailure(from, to, "no-path");
+  const result = bfsShortestPath(described, from, to, maxDepth);
+  if (!result.found) {
+    return makeFailure(from, to, result.truncated ? "max-depth-exceeded" : "no-path");
+  }
+  return makeSuccess(from, to, materializeSteps(described, result.pathOrder, opts));
+}
+function bfsShortestPath(described, from, to, maxDepth) {
+  const pred = /* @__PURE__ */ new Map();
+  const queue = [{ path: to, depth: 0 }];
+  const visited = /* @__PURE__ */ new Set([to]);
+  let head = 0;
+  let truncated = false;
+  while (head < queue.length) {
+    const cur = queue[head++];
+    if (cur.path === from) break;
+    if (maxDepth != null && cur.depth >= maxDepth) {
+      const node3 = described.nodes[cur.path];
+      if (node3?.deps && node3.deps.length > 0) truncated = true;
+      continue;
+    }
+    const node2 = described.nodes[cur.path];
+    if (node2 == null) continue;
+    const deps = node2.deps ?? [];
+    const slots = /* @__PURE__ */ new Map();
+    for (let i = 0; i < deps.length; i++) {
+      const dep = deps[i];
+      if (!dep) continue;
+      let arr = slots.get(dep);
+      if (arr == null) {
+        arr = [];
+        slots.set(dep, arr);
+      }
+      arr.push(i);
+    }
+    for (const [dep, indices] of slots) {
+      if (visited.has(dep)) continue;
+      visited.add(dep);
+      pred.set(dep, { from: cur.path, depIndices: indices });
+      queue.push({ path: dep, depth: cur.depth + 1 });
+    }
+  }
+  if (!pred.has(from)) {
+    return { found: false, pathOrder: [], truncated };
+  }
+  const pathOrder = [{ path: from }];
+  let cursor = from;
+  while (cursor !== to) {
+    const p = pred.get(cursor);
+    if (p == null) return { found: false, pathOrder: [], truncated: false };
+    pathOrder[pathOrder.length - 1].depIndices = p.depIndices;
+    pathOrder.push({ path: p.from });
+    cursor = p.from;
+  }
+  return { found: true, pathOrder, truncated: false };
+}
+function findShortestCycle(described, start, opts) {
+  const startNode = described.nodes[start];
+  if (startNode == null) return null;
+  const startDeps = startNode.deps ?? [];
+  const selfSlots = [];
+  for (let i = 0; i < startDeps.length; i++) if (startDeps[i] === start) selfSlots.push(i);
+  if (selfSlots.length > 0) {
+    const step0 = buildStep(start, startNode, 0, opts);
+    step0.dep_index = selfSlots[0];
+    const step1 = buildStep(start, startNode, 1, opts);
+    return makeSuccess(start, start, [step0, step1]);
+  }
+  let best = null;
+  for (let i = 0; i < startDeps.length; i++) {
+    const dep = startDeps[i];
+    if (!dep || dep === start) continue;
+    const sub = bfsShortestPath(described, dep, start, opts.maxDepth);
+    if (!sub.found) continue;
+    if (best == null || sub.pathOrder.length < best.pathOrder.length) {
+      best = sub;
+      best = {
+        found: true,
+        pathOrder: [{ path: start, depIndices: [i] }, ...sub.pathOrder],
+        truncated: false
+      };
+    }
+  }
+  if (best == null) return null;
+  return makeSuccess(start, start, materializeSteps(described, best.pathOrder, opts));
+}
+function materializeSteps(described, pathOrder, opts) {
+  return pathOrder.map((entry, i) => {
+    const node2 = described.nodes[entry.path];
+    const step = buildStep(entry.path, node2, i, opts);
+    if (entry.depIndices != null && entry.depIndices.length > 0) {
+      step.dep_index = entry.depIndices[0];
+      if (entry.depIndices.length > 1) step.dep_indices = [...entry.depIndices];
+    }
+    return step;
+  });
+}
+function buildStep(path, node2, hop, opts) {
+  const step = {
+    path,
+    type: node2.type,
+    hop
+  };
+  if (node2.status !== void 0) step.status = node2.status;
+  if ("value" in node2) step.value = node2.value;
+  if (node2.v != null) step.v = node2.v;
+  const annotation = opts.annotations?.get(path) ?? node2.reason;
+  if (annotation != null) step.reason = annotation;
+  const lastMutation = opts.lastMutations?.get(path) ?? node2.lastMutation;
+  if (lastMutation != null) step.lastMutation = lastMutation;
+  return step;
+}
+function makeSuccess(from, to, steps) {
+  return finalize(from, to, true, "ok", steps);
+}
+function makeFailure(from, to, reason) {
+  return finalize(from, to, false, reason, []);
+}
+function finalize(from, to, found, reason, steps) {
+  const text = renderChain(from, to, found, reason, steps);
+  return {
+    from,
+    to,
+    found,
+    reason,
+    steps,
+    text,
+    toJSON() {
+      return { from, to, found, reason, steps };
+    }
+  };
+}
+function renderChain(from, to, found, reason, steps) {
+  if (!found) {
+    switch (reason) {
+      case "no-such-from":
+        return `explainPath: no node named "${from}"`;
+      case "no-such-to":
+        return `explainPath: no node named "${to}"`;
+      case "max-depth-exceeded":
+        return `explainPath: no path from "${from}" to "${to}" within maxDepth`;
+      default:
+        return `explainPath: no path from "${from}" to "${to}"`;
+    }
+  }
+  const lines = [`Causal path: ${from} \u2192 ${to} (${steps.length} step(s))`];
+  for (const step of steps) {
+    const arrow = step.hop === 0 ? "\xB7" : "\u2193";
+    const head = `  ${arrow} ${step.path} (${step.type}${step.status ? `/${step.status}` : ""})`;
+    lines.push(head);
+    if ("value" in step) {
+      lines.push(`      value: ${formatValue(step.value)}`);
+    }
+    if (step.reason != null) {
+      lines.push(`      reason: ${step.reason}`);
+    }
+    if (step.lastMutation != null) {
+      const a = step.lastMutation.actor;
+      lines.push(`      actor: ${a.type}${a.id ? `:${a.id}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatValue(v) {
+  if (v === void 0) return "<sentinel>";
+  if (v === null) return "null";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+  try {
+    const s = JSON.stringify(v);
+    return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+  } catch {
+    return String(v);
+  }
+}
+
+// src/extra/utils/sizeof.ts
+var OVERHEAD = {
+  object: 56,
+  array: 64,
+  string: 40,
+  // header; content added separately
+  number: 8,
+  boolean: 4,
+  null: 0,
+  undefined: 0,
+  symbol: 40,
+  bigint: 16,
+  // base; scales with digit count (see `_bigintSize`)
+  function: 120,
+  map: 72,
+  set: 72,
+  mapEntry: 40,
+  setEntry: 24,
+  date: 24,
+  regexp: 48,
+  error: 64,
+  url: 80,
+  promise: 48,
+  weakmap: 40,
+  weakset: 40
+};
+var SIZEOF_SYMBOL = /* @__PURE__ */ Symbol.for("sizeof");
+function sizeof(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const seenBuffers = /* @__PURE__ */ new WeakSet();
+  const stack = [value];
+  let total = 0;
+  while (stack.length > 0) {
+    const v = stack.pop();
+    total += _shallowSize(v, seen, seenBuffers, stack);
+  }
+  return total;
+}
+function _shallowSize(value, seen, seenBuffers, stack) {
+  if (value === null || value === void 0) return 0;
+  const t = typeof value;
+  switch (t) {
+    case "number":
+      return OVERHEAD.number;
+    case "boolean":
+      return OVERHEAD.boolean;
+    case "string":
+      return OVERHEAD.string + value.length * 2;
+    case "bigint":
+      return OVERHEAD.bigint + _bigintSize(value);
+    case "symbol":
+      return OVERHEAD.symbol;
+    case "function":
+      if (seen.has(value)) return 0;
+      seen.add(value);
+      return OVERHEAD.function;
+    case "undefined":
+      return 0;
+  }
+  const obj = value;
+  if (seen.has(obj)) return 0;
+  seen.add(obj);
+  const hook = obj[SIZEOF_SYMBOL];
+  if (typeof hook === "function") {
+    try {
+      const reported = hook.call(obj);
+      if (typeof reported === "number" && Number.isFinite(reported)) return reported;
+    } catch {
+    }
+  }
+  if (obj instanceof Date) return OVERHEAD.date;
+  if (obj instanceof RegExp) return OVERHEAD.regexp + obj.source.length * 2;
+  if (obj instanceof Error) {
+    const m = obj.message ? obj.message.length * 2 : 0;
+    const s = obj.stack ? obj.stack.length * 2 : 0;
+    return OVERHEAD.error + m + s;
+  }
+  if (typeof URL !== "undefined" && obj instanceof URL) {
+    return OVERHEAD.url + obj.href.length * 2;
+  }
+  if (typeof Promise !== "undefined" && obj instanceof Promise) {
+    return OVERHEAD.promise;
+  }
+  if (obj instanceof WeakMap) return OVERHEAD.weakmap;
+  if (obj instanceof WeakSet) return OVERHEAD.weakset;
+  if (obj instanceof Map) {
+    let size2 = OVERHEAD.map;
+    for (const [k, v] of obj) {
+      size2 += OVERHEAD.mapEntry;
+      stack.push(k);
+      stack.push(v);
+    }
+    return size2;
+  }
+  if (obj instanceof Set) {
+    let size2 = OVERHEAD.set;
+    for (const v of obj) {
+      size2 += OVERHEAD.setEntry;
+      stack.push(v);
+    }
+    return size2;
+  }
+  if (Array.isArray(obj)) {
+    const size2 = OVERHEAD.array + obj.length * 8;
+    for (const item of obj) stack.push(item);
+    return size2;
+  }
+  if (obj instanceof ArrayBuffer) {
+    if (seenBuffers.has(obj)) return 0;
+    seenBuffers.add(obj);
+    return obj.byteLength;
+  }
+  if (ArrayBuffer.isView(obj)) {
+    const view = obj;
+    if (seenBuffers.has(view.buffer)) return 48;
+    seenBuffers.add(view.buffer);
+    return view.buffer.byteLength + 48;
+  }
+  let size = OVERHEAD.object;
+  const keys = Object.keys(obj);
+  for (const key of keys) {
+    size += OVERHEAD.string + key.length * 2;
+    try {
+      stack.push(obj[key]);
+    } catch {
+    }
+  }
+  return size;
+}
+function _bigintSize(n) {
+  const abs = n < 0n ? -n : n;
+  if (abs === 0n) return 0;
+  const bits = abs.toString(2).length;
+  return Math.ceil(bits / 32) * 8;
+}
+
+// src/graph/profile.ts
+function graphProfile(graph, opts) {
+  const topN = opts?.topN ?? 10;
+  const desc = graph.describe({ detail: "standard" });
+  const targets = [];
+  const collector = graph._collectObserveTargets;
+  if (typeof collector === "function") {
+    collector.call(graph, "", targets);
+  }
+  const pathToNode = /* @__PURE__ */ new Map();
+  for (const [p, n] of targets) pathToNode.set(p, n);
+  const profiles = [];
+  for (const [path, nodeDesc] of Object.entries(desc.nodes)) {
+    const nd = pathToNode.get(path);
+    const impl = nd instanceof NodeImpl ? nd : null;
+    const valueSizeBytes = impl ? sizeof(impl.cache) : 0;
+    const subscriberCount = impl ? impl._sinkCount : 0;
+    const depCount = nodeDesc.deps?.length ?? 0;
+    const isOrphanEffect = nodeDesc.type === "effect" && subscriberCount === 0;
+    const orphanKind = subscriberCount === 0 ? nodeDesc.type === "effect" ? "orphan-effect" : nodeDesc.type === "derived" ? "idle-derived" : nodeDesc.type === "producer" ? "idle-producer" : null : null;
+    profiles.push({
+      path,
+      type: nodeDesc.type,
+      status: nodeDesc.status ?? "unknown",
+      valueSizeBytes,
+      subscriberCount,
+      depCount,
+      isOrphanEffect,
+      orphanKind
+    });
+  }
+  const totalValueSizeBytes = profiles.reduce((sum, p) => sum + p.valueSizeBytes, 0);
+  const topBy = (key, cmp) => [...profiles].sort(cmp ?? ((a, b) => b[key] - a[key])).slice(0, topN);
+  const orphans = profiles.filter((p) => p.orphanKind != null);
+  const orphanEffects = profiles.filter((p) => p.isOrphanEffect);
+  return {
+    nodeCount: profiles.length,
+    edgeCount: desc.edges.length,
+    subgraphCount: desc.subgraphs.length,
+    nodes: profiles,
+    totalValueSizeBytes,
+    hotspots: {
+      byValueSize: topBy("valueSizeBytes"),
+      bySubscriberCount: topBy("subscriberCount"),
+      byDepCount: topBy("depCount")
+    },
+    orphans,
+    orphanEffects
+  };
+}
+
+// src/graph/graph.ts
+var PATH_SEP = "::";
+var GRAPH_META_SEGMENT = "__meta__";
+var SNAPSHOT_VERSION = 1;
+function drainDisposers(set, graphName) {
+  const cap = Math.max(16, set.size * 4);
+  let iterations = 0;
+  while (set.size > 0) {
+    if (iterations++ >= cap) {
+      console.error(
+        `[Graph "${graphName}".destroy] disposer drain exceeded cap (${cap}); ${set.size} disposer(s) discarded`
+      );
+      set.clear();
+      return;
+    }
+    const it = set.values().next();
+    if (it.done) return;
+    const dispose = it.value;
+    set.delete(dispose);
+    try {
+      dispose();
+    } catch (err) {
+      console.error(`[Graph "${graphName}".destroy] disposer threw:`, err);
+    }
+  }
+}
+function computeVersionFingerprint(nodes) {
+  const parts = [];
+  for (const path of Object.keys(nodes).sort()) {
+    const v = nodes[path].v;
+    if (v != null) parts.push(`${path}	${v.id}	${v.version}`);
+  }
+  return parts.join("\n");
+}
+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 deepEqual(a, b) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  const walk = (x, y) => {
+    if (Object.is(x, y)) return true;
+    if (x == null || y == null || typeof x !== "object" || typeof y !== "object") return false;
+    let seenRhs = seen.get(x);
+    if (seenRhs == null) {
+      seenRhs = /* @__PURE__ */ new WeakSet();
+      seen.set(x, seenRhs);
+    }
+    if (seenRhs.has(y)) return true;
+    seenRhs.add(y);
+    const ctorA = x.constructor;
+    const ctorB = y.constructor;
+    if (ctorA !== ctorB) return false;
+    if (x instanceof Date) return x.getTime() === y.getTime();
+    if (x instanceof RegExp)
+      return x.source === y.source && x.flags === y.flags;
+    if (Array.isArray(x)) {
+      const arrB = y;
+      if (x.length !== arrB.length) return false;
+      for (let i = 0; i < x.length; i++) {
+        if (!walk(x[i], arrB[i])) return false;
+      }
+      return true;
+    }
+    if (x instanceof Map) {
+      const mB = y;
+      if (x.size !== mB.size) return false;
+      for (const [k, v] of x) {
+        if (!mB.has(k) || !walk(v, mB.get(k))) return false;
+      }
+      return true;
+    }
+    if (x instanceof Set) {
+      const sB = y;
+      if (x.size !== sB.size) return false;
+      for (const v of x) {
+        let found = false;
+        for (const w of sB) {
+          if (walk(v, w)) {
+            found = true;
+            break;
+          }
+        }
+        if (!found) return false;
+      }
+      return true;
+    }
+    if (ArrayBuffer.isView(x)) {
+      const taA = x;
+      const taB = y;
+      if (taA.length !== taB.length) return false;
+      for (let i = 0; i < taA.length; i++) if (taA[i] !== taB[i]) return false;
+      return true;
+    }
+    const keysA = Object.keys(x);
+    const keysB = Object.keys(y);
+    if (keysA.length !== keysB.length) return false;
+    const setB = new Set(keysB);
+    for (const k of keysA) {
+      if (!setB.has(k)) return false;
+      if (!walk(x[k], y[k])) return false;
+    }
+    return true;
+  };
+  return walk(a, b);
+}
+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 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 renderDescribeAsJson(d, options) {
+  const includeEdges = options.includeEdges ?? true;
+  const includeSubgraphs = options.includeSubgraphs ?? true;
+  const { expand: _expand, ...rest } = d;
+  const payload = {
+    ...rest,
+    edges: includeEdges ? d.edges : [],
+    subgraphs: includeSubgraphs ? d.subgraphs : []
+  };
+  const text = JSON.stringify(sortJsonValue(payload), null, options.indent ?? 2);
+  options.logger?.(text);
+  return text;
+}
+function renderDescribeAsPretty(d, options) {
+  const includeEdges = options.includeEdges ?? true;
+  const includeSubgraphs = options.includeSubgraphs ?? true;
+  const lines = [];
+  lines.push(`Graph ${d.name}`);
+  lines.push("Nodes:");
+  for (const path of Object.keys(d.nodes).sort()) {
+    const n = d.nodes[path];
+    lines.push(`- ${path} (${n.type}/${n.status}): ${describeData(n.value)}`);
+  }
+  if (includeEdges) {
+    lines.push("Edges:");
+    for (const edge of d.edges) {
+      lines.push(`- ${edge.from} -> ${edge.to}`);
+    }
+  }
+  if (includeSubgraphs) {
+    lines.push("Subgraphs:");
+    for (const sg of d.subgraphs) {
+      lines.push(`- ${sg}`);
+    }
+  }
+  const text = lines.join("\n");
+  options.logger?.(text);
+  return text;
+}
+function renderDescribeAsMermaid(d, options) {
+  const direction = normalizeDiagramDirection(options.direction);
+  const paths = Object.keys(d.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(d)) {
+    const fromId = ids.get(from);
+    const toId = ids.get(to);
+    if (!fromId || !toId) continue;
+    lines.push(`  ${fromId} --> ${toId}`);
+  }
+  return lines.join("\n");
+}
+function renderDescribeAsD2(d, options) {
+  const direction = normalizeDiagramDirection(options.direction);
+  const paths = Object.keys(d.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(d)) {
+    const fromId = ids.get(from);
+    const toId = ids.get(to);
+    if (!fromId || !toId) continue;
+    lines.push(`${fromId} -> ${toId}`);
+  }
+  return lines.join("\n");
+}
+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 OBSERVE_ANSI_THEME = {
+  data: "\x1B[32m",
+  dirty: "\x1B[33m",
+  resolved: "\x1B[36m",
+  invalidate: "\x1B[93m",
+  pause: "\x1B[90m",
+  resume: "\x1B[96m",
+  complete: "\x1B[34m",
+  error: "\x1B[31m",
+  teardown: "\x1B[91m",
+  derived: "\x1B[35m",
+  path: "\x1B[90m",
+  reset: "\x1B[0m"
+};
+var OBSERVE_NO_COLOR_THEME = {
+  data: "",
+  dirty: "",
+  resolved: "",
+  invalidate: "",
+  pause: "",
+  resume: "",
+  complete: "",
+  error: "",
+  teardown: "",
+  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 resolveObserveTheme(theme) {
+  if (theme === "none") return OBSERVE_NO_COLOR_THEME;
+  if (theme === "ansi" || theme == null) return OBSERVE_ANSI_THEME;
+  return {
+    data: theme.data ?? "",
+    dirty: theme.dirty ?? "",
+    resolved: theme.resolved ?? "",
+    invalidate: theme.invalidate ?? "",
+    pause: theme.pause ?? "",
+    resume: theme.resume ?? "",
+    complete: theme.complete ?? "",
+    error: theme.error ?? "",
+    teardown: theme.teardown ?? "",
+    derived: theme.derived ?? "",
+    path: theme.path ?? "",
+    reset: theme.reset ?? ""
+  };
+}
+function resolveObserveDetail(opts) {
+  if (opts == null) return {};
+  const detail = opts.detail;
+  if (detail === "full") {
+    return {
+      ...opts,
+      structured: opts.structured ?? true,
+      timeline: opts.timeline ?? true,
+      causal: opts.causal ?? true,
+      derived: opts.derived ?? true
+    };
+  }
+  if (detail === "minimal") {
+    return { ...opts, structured: opts.structured ?? true };
+  }
+  return opts;
+}
+function assertNoControlChars(name, graphName, label) {
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c < 32 || c === 127) {
+      throw new Error(
+        `Graph "${graphName}": ${label} "${name}" must not contain control character (U+${c.toString(16).padStart(4, "0").toUpperCase()} at index ${i})`
+      );
+    }
+  }
+}
+function assertRegisterableName(name, graphName, label) {
+  if (name === "") {
+    throw new Error(`Graph "${graphName}": ${label} name must be non-empty`);
+  }
+  if (name.includes(PATH_SEP)) {
+    throw new Error(
+      `Graph "${graphName}": ${label} "${name}" must not contain '${PATH_SEP}' (path separator)`
+    );
+  }
+  if (name === GRAPH_META_SEGMENT) {
+    throw new Error(
+      `Graph "${graphName}": ${label} name "${GRAPH_META_SEGMENT}" is reserved for meta companion paths`
+    );
+  }
+  assertNoControlChars(name, graphName, label);
+}
+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 filterMetaMessages(messages, config) {
+  let anyFiltered = false;
+  for (const m of messages) {
+    if (!config.isMetaPassthrough(m[0])) {
+      anyFiltered = true;
+      break;
+    }
+  }
+  if (!anyFiltered) return messages;
+  const kept = messages.filter((m) => config.isMetaPassthrough(m[0]));
+  return kept;
+}
+function teardownMountedGraph(root) {
+  for (const child of root._mounts.values()) {
+    teardownMountedGraph(child);
+  }
+  for (const n of root._nodes.values()) {
+    try {
+      n.down([[TEARDOWN]], { internal: true });
+    } catch {
+    }
+  }
+}
+var Graph = class _Graph {
+  name;
+  opts;
+  /** Protocol config bound to this graph (defaults to `defaultConfig`). */
+  config;
+  /** @internal — exposed for {@link teardownMountedGraph} and cross-graph helpers. */
+  _nodes = /* @__PURE__ */ new Map();
+  /**
+   * @internal Reverse lookup for duplicate-instance detection in
+   * {@link Graph.add} — O(1) replacement for an O(n) scan of `_nodes`.
+   * Weak so nodes can be GC'd after `remove()` even if a caller keeps the
+   * map alive via some unusual pattern.
+   */
+  _nodeToName = /* @__PURE__ */ new WeakMap();
+  /** @internal — exposed for {@link teardownMountedGraph}. */
+  _mounts = /* @__PURE__ */ new Map();
+  /**
+   * @internal Parent graph if this instance is mounted. `undefined` when
+   * this is the root or when the graph has been unmounted. Used for
+   * reparenting rejection + O(depth) ancestor walks.
+   */
+  _parent = void 0;
+  _storageDisposers = /* @__PURE__ */ new Set();
+  _disposers = /* @__PURE__ */ new Set();
+  /**
+   * @internal Lazy `TopologyEvent` producer. Created on first `.topology`
+   * access. Zero cost until something subscribes — producer fn only runs when
+   * the first sink attaches, registering one handler into
+   * {@link Graph._topologyEmitters}.
+   */
+  _topology;
+  /**
+   * @internal Active emit handlers for the topology producer. Each entry is
+   * the closure registered by the producer fn on activation; cleared on
+   * deactivation. `_emitTopology` broadcasts through every entry (there is at
+   * most one per activation cycle of the producer).
+   */
+  _topologyEmitters = /* @__PURE__ */ new Set();
+  /**
+   * @param name - Non-empty graph id (must not contain `::` and must not
+   *   equal the reserved meta segment `__meta__`).
+   * @param opts - See {@link GraphOptions}. Stored frozen on the instance.
+   */
+  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}")`);
+    }
+    if (name === GRAPH_META_SEGMENT) {
+      throw new Error(`Graph name "${GRAPH_META_SEGMENT}" is reserved for meta companion paths`);
+    }
+    this.name = name;
+    this.opts = Object.freeze({ ...opts ?? {} });
+    this.config = opts?.config ?? defaultConfig;
+    this._traceRing = new RingBuffer(opts?.traceCapacity ?? 1e3);
+    if (opts?.versioning != null) {
+      this.setVersioning(opts.versioning);
+    }
+  }
+  /**
+   * Walk ancestors up through `_parent`. Returns the chain starting at this
+   * instance, ending at the root (a graph with no parent). O(depth).
+   *
+   * @param includeSelf - Include `this` in the chain (default `true`).
+   */
+  ancestors(includeSelf = true) {
+    const out = [];
+    let p = includeSelf ? this : this._parent;
+    while (p != null) {
+      out.push(p);
+      p = p._parent;
+    }
+    return out;
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Topology companion (structural-change event stream)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Reactive stream of structural changes to this graph's own registry
+   * (add / mount / remove). Value mutations live on `observe()`; this
+   * companion only fires when the topology shape changes.
+   *
+   * Lazy: the underlying node is created on first access and activates when
+   * something subscribes. No emission replay — late subscribers do not
+   * receive historical events and should snapshot via {@link Graph.describe}
+   * before listening for incremental changes. Events that fire while the
+   * producer has zero subscribers are dropped (no retention).
+   *
+   * Own-graph only: a parent's `topology` does NOT emit for structural
+   * changes inside a mounted child. Transitive consumers subscribe to each
+   * child's topology separately (recurse through `topology`'s own "added"
+   * events with `nodeKind: "mount"` to discover new children).
+   *
+   * See {@link TopologyEvent} for payload shape.
+   *
+   * @category observability
+   */
+  get topology() {
+    if (this._topology == null) {
+      this._topology = producer(
+        (actions) => {
+          const handler = (event) => {
+            actions.emit(event);
+          };
+          this._topologyEmitters.add(handler);
+          return () => {
+            this._topologyEmitters.delete(handler);
+          };
+        },
+        { name: `${this.name}_topology` }
+      );
+    }
+    return this._topology;
+  }
+  /**
+   * @internal Fire a {@link TopologyEvent} to every active subscriber of
+   * `this.topology`. No-op when the topology node has never been accessed or
+   * currently has no sinks — zero cost for graphs nobody observes.
+   */
+  _emitTopology(event) {
+    if (this._topology == null || this._topologyEmitters.size === 0) return;
+    for (const h of this._topologyEmitters) h(event);
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Node registry
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Registers a node under a local name. Fails if the name is already used,
+   * reserved by a mount, the same node instance is already registered, or
+   * the node is torn down.
+   *
+   * Returns the registered node so callers can chain:
+   * `const counter = g.add("counter", state(0))`.
+   *
+   * @param name - Local key (no `::`).
+   * @param node - Node instance to own.
+   */
+  add(name, node2) {
+    assertRegisterableName(name, this.name, "add");
+    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`);
+    }
+    const existingName = this._nodeToName.get(node2);
+    if (existingName !== void 0) {
+      throw new Error(
+        `Graph "${this.name}": node instance already registered as "${existingName}"`
+      );
+    }
+    this._nodes.set(name, node2);
+    this._nodeToName.set(node2, name);
+    this._emitTopology({ kind: "added", name, nodeKind: "node" });
+    return node2;
+  }
+  /**
+   * Bulk-apply a minimum versioning level to every currently-registered node
+   * in this graph (roadmap §6.0). `_applyVersioning` is monotonic — nodes
+   * already at a higher level are untouched. The method refuses to run
+   * mid-wave; invoke at setup time before any external subscribers attach.
+   *
+   * **Not** a default-for-future-adds mechanism — that's what
+   * `config.defaultVersioning` is for. Nodes added after this call do NOT
+   * automatically inherit `level`; register new nodes with their own
+   * `opts.versioning` or set `config.defaultVersioning` before construction.
+   *
+   * **Scope:** local only. Does not propagate to mounted subgraphs.
+   *
+   * @param level - `0` for V0, `1` for V1, or `undefined` to no-op.
+   */
+  setVersioning(level) {
+    if (level == null) return;
+    for (const node2 of this._nodes.values()) {
+      if (node2 instanceof NodeImpl) {
+        node2._applyVersioning(level);
+      }
+    }
+  }
+  /**
+   * Unregisters a node or unmounts a subgraph and sends `[[TEARDOWN]]` to the
+   * removed node or recursively through the mounted subtree (§3.2).
+   *
+   * @param name - Local mount or node name.
+   * @returns Audit record of what was removed: `{kind, nodes, mounts}`.
+   *   `kind: "node"` → `nodes: [name]`, `mounts: []`. `kind: "mount"` →
+   *   `nodes` lists every primary node torn down across the subtree (sorted
+   *   qualified paths relative to the unmounted subgraph) and `mounts` lists
+   *   the mounted subgraphs in depth-first order including `name` itself.
+   */
+  remove(name) {
+    assertRegisterableName(name, this.name, "remove");
+    const child = this._mounts.get(name);
+    if (child) {
+      const audit2 = { kind: "mount", nodes: [], mounts: [] };
+      const targets = [];
+      child._collectObserveTargets("", targets);
+      for (const [p, n] of targets) {
+        if (!p.includes(`${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}`)) {
+          audit2.nodes.push(p);
+        }
+        void n;
+      }
+      audit2.nodes.sort();
+      audit2.mounts.push(name);
+      audit2.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
+      this._mounts.delete(name);
+      child._parent = void 0;
+      teardownMountedGraph(child);
+      this._emitTopology({ kind: "removed", name, nodeKind: "mount", audit: audit2 });
+      return audit2;
+    }
+    const node2 = this._nodes.get(name);
+    if (!node2) {
+      throw new Error(`Graph "${this.name}": unknown node or mount "${name}"`);
+    }
+    this._nodes.delete(name);
+    this._nodeToName.delete(node2);
+    node2.down([[TEARDOWN]], { internal: true });
+    const audit = { kind: "node", nodes: [name], mounts: [] };
+    this._emitTopology({ kind: "removed", name, nodeKind: "node", audit });
+    return audit;
+  }
+  /**
+   * Bulk remove — invokes {@link Graph.remove} for every local name matching
+   * `filter`. Audit records merge into a single result. Mounted subgraphs
+   * are included via `filter` receiving the mount name; internal subtree
+   * entries are not walked directly (use describe + scan for tree-level
+   * queries).
+   *
+   * @param filter - Predicate or glob. Glob strings support `*` within a
+   *   segment and `**` across segments (same grammar as `restore({only})`).
+   * @returns Combined audit of all nodes + mounts removed.
+   */
+  removeAll(filter) {
+    const match = typeof filter === "function" ? filter : (() => {
+      const re = globToRegex(filter);
+      return (n) => re.test(n);
+    })();
+    const audit = { kind: "mount", nodes: [], mounts: [] };
+    const localNames = [...this._nodes.keys(), ...this._mounts.keys()].filter((n) => match(n));
+    for (const name of localNames) {
+      const sub = this.remove(name);
+      audit.nodes.push(...sub.nodes);
+      audit.mounts.push(...sub.mounts);
+    }
+    audit.nodes.sort();
+    audit.mounts.sort();
+    return audit;
+  }
+  /**
+   * Iterable over locally-registered `[localName, Node]` pairs (sorted).
+   * Does not recurse into mounts.
+   */
+  [Symbol.iterator]() {
+    const sorted = [...this._nodes.keys()].sort();
+    const nodes = this._nodes;
+    let i = 0;
+    return {
+      [Symbol.iterator]() {
+        return this;
+      },
+      next() {
+        if (i >= sorted.length) return { value: void 0, done: true };
+        const name = sorted[i++];
+        return { value: [name, nodes.get(name)], done: false };
+      }
+    };
+  }
+  /**
+   * 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).cache;
+  }
+  /**
+   * 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"
+    });
+  }
+  /**
+   * Atomic multi-node DATA write. Wraps every {@link Graph.set} call in a
+   * single `batch(...)` so downstream dependents see one coalesced wave
+   * instead of N cascading ones.
+   *
+   * @param entries - `{name → value}` map or `[name, value]` pairs.
+   * @param options - Passed to each underlying `set` call (same `actor` + `internal` semantics).
+   */
+  setAll(entries, options) {
+    const iter = Symbol.iterator in entries ? entries : Object.entries(entries);
+    batch(() => {
+      for (const [name, value] of iter) this.set(name, value, options);
+    });
+  }
+  /**
+   * Emit a single `[[INVALIDATE]]` (tier 1) on a node. Thin wrapper over
+   * `node.down([[INVALIDATE]], …)` matching the {@link Graph.set} ergonomics.
+   */
+  invalidate(name, options) {
+    const internal = options?.internal === true;
+    this.node(name).down([[INVALIDATE]], {
+      actor: options?.actor,
+      internal,
+      delivery: "write"
+    });
+  }
+  /**
+   * Emit a single `[[ERROR, err]]` (tier 4) on a node.
+   */
+  error(name, err, options) {
+    const internal = options?.internal === true;
+    this.node(name).down([[ERROR, err]], {
+      actor: options?.actor,
+      internal,
+      delivery: "write"
+    });
+  }
+  /**
+   * Emit a single `[[COMPLETE]]` (tier 4) on a node, declaring the stream
+   * cleanly finished. Distinct from {@link Graph.remove} (which emits
+   * TEARDOWN and unregisters the node).
+   */
+  complete(name, options) {
+    const internal = options?.internal === true;
+    this.node(name).down([[COMPLETE]], {
+      actor: options?.actor,
+      internal,
+      delivery: "write"
+    });
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Edges (derived on-demand from node `_deps`)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Returns the full edge list for this graph tree, derived on demand from
+   * each registered node's `_deps` (no stored registry). Local-only
+   * (non-recursive) by default to match the historical `edges()` surface;
+   * pass `{recursive: true}` to include mounted subgraphs with qualified
+   * paths relative to this graph.
+   *
+   * Use {@link Graph.describe} for full-tree snapshots with edges already
+   * qualified and paired with node metadata.
+   */
+  edges(opts) {
+    const recursive = opts?.recursive === true;
+    const nodeToLocal = /* @__PURE__ */ new Map();
+    if (!recursive) {
+      for (const [localName, n] of this._nodes) nodeToLocal.set(n, localName);
+      const result2 = [];
+      for (const [localName, n] of this._nodes) {
+        if (!(n instanceof NodeImpl)) continue;
+        for (const dep of n._deps) {
+          const from = nodeToLocal.get(dep.node);
+          if (from != null) result2.push([from, localName]);
+        }
+      }
+      result2.sort(
+        (a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0
+      );
+      return result2;
+    }
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    const nodeToPath = /* @__PURE__ */ new Map();
+    for (const [p, n] of targets) nodeToPath.set(n, p);
+    const result = [];
+    for (const [path, n] of targets) {
+      if (!(n instanceof NodeImpl)) continue;
+      for (const dep of n._deps) {
+        const from = nodeToPath.get(dep.node);
+        if (from != null) result.push([from, path]);
+      }
+    }
+    result.sort(
+      (a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0
+    );
+    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.
+   * @returns The mounted `child`, for chaining.
+   */
+  mount(name, child) {
+    assertRegisterableName(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`);
+    }
+    if (child._parent != null) {
+      throw new Error(
+        `Graph "${this.name}": this child graph is already mounted on "${child._parent.name}"`
+      );
+    }
+    for (let p = this; p != null; p = p._parent) {
+      if (p === child) {
+        throw new Error(`Graph "${this.name}": mount("${name}", \u2026) would create a mount cycle`);
+      }
+    }
+    this._mounts.set(name, child);
+    child._parent = this;
+    this._emitTopology({ kind: "added", name, nodeKind: "mount" });
+    return 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"`). The strip
+   * is applied **recursively** when descending into mounted children, so
+   * `child.resolve("child::x")` also works when `child.name === "child"`.
+   *
+   * @param path - Qualified `::` path or local name.
+   * @returns The resolved `Node`.
+   */
+  resolve(path) {
+    const segments = splitPath(path, this.name);
+    return this._resolveFromSegments(segments);
+  }
+  /**
+   * Non-throwing {@link Graph.resolve}. Returns `undefined` instead of
+   * throwing when the path does not resolve to a node.
+   */
+  tryResolve(path) {
+    try {
+      return this.resolve(path);
+    } catch {
+      return void 0;
+    }
+  }
+  _resolveFromSegments(segments) {
+    let seg = segments;
+    if (seg[0] === this.name) {
+      seg = seg.slice(1);
+      if (seg.length === 0) {
+        throw new Error(`Graph "${this.name}": resolve path ends at graph name only`);
+      }
+    }
+    const head = seg[0];
+    const rest = seg.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, seg.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;
+  }
+  /**
+   * 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).
+   *
+   * **Primary-vs-meta filter asymmetry (intentional):** primary nodes receive the
+   * unfiltered `messages` batch — that's the canonical data-plane flow. Companion
+   * `meta` nodes receive a filtered subset keyed by the per-type `metaPassthrough`
+   * flag on {@link GraphReFlyConfig}. Built-in defaults: PAUSE / RESUME / DATA /
+   * RESOLVED pass through to meta; INVALIDATE / COMPLETE / ERROR / TEARDOWN do
+   * not.
+   *
+   * **Where lifecycle terminals reach meta:**
+   * - **TEARDOWN** — primary's `_emit` cascades to meta children directly (see
+   *   `core/node.ts` "Meta TEARDOWN fan-out" block) so meta is torn down with
+   *   its primary regardless of the signal-level filter.
+   * - **COMPLETE / ERROR / INVALIDATE** — scoped to primaries on the broadcast
+   *   path. Meta companions are an attribution side-channel, not a lifecycle
+   *   participant; address meta directly via `meta.down(...)` if you need to
+   *   forward these. Audit confirmed 2026-04-17: no current meta consumer
+   *   relies on broadcast COMPLETE/ERROR/INVALIDATE delivery.
+   *
+   * @param messages - Batch to deliver to every registered node (and mounts, recursively).
+   * @param options - Optional `actor` / `internal` for transport.
+   */
+  signal(messages, options) {
+    if (options?.internal !== true) {
+      for (const m of messages) {
+        const tier = this.config.messageTier(m[0]);
+        if (tier === 3) {
+          throw new Error(
+            `Graph "${this.name}": Graph.signal() rejects tier-3 messages (DATA / RESOLVED). Broadcast is for control-plane tiers (START / DIRTY / INVALIDATE / PAUSE / RESUME / COMPLETE / ERROR / TEARDOWN). For per-node value writes, use Graph.set or graph.node(name).down(...).`
+          );
+        }
+      }
+    }
+    const errors = [];
+    this._signalDeliver(messages, options ?? {}, /* @__PURE__ */ new Set(), errors);
+    if (errors.length > 0) throw errors[0];
+  }
+  _signalDeliver(messages, opts, vis, errors) {
+    for (const sub of this._mounts.values()) {
+      sub._signalDeliver(messages, opts, vis, errors);
+    }
+    const internal = opts.internal === true;
+    const downOpts = internal ? { internal: true } : { actor: opts.actor, delivery: "signal" };
+    const metaMessages = filterMetaMessages(messages, this.config);
+    for (const localName of [...this._nodes.keys()].sort()) {
+      const n = this._nodes.get(localName);
+      if (vis.has(n)) continue;
+      vis.add(n);
+      try {
+        n.down(messages, downOpts);
+      } catch (err) {
+        if (err instanceof GuardDenied) throw err;
+        errors.push(err);
+      }
+      if (metaMessages.length === 0) continue;
+      this._signalMetaSubtree(n, metaMessages, vis, downOpts, errors);
+    }
+  }
+  _signalMetaSubtree(root, messages, vis, downOpts, errors) {
+    for (const mk of Object.keys(root.meta).sort()) {
+      const mnode = root.meta[mk];
+      if (vis.has(mnode)) continue;
+      vis.add(mnode);
+      try {
+        mnode.down(messages, downOpts);
+      } catch (err) {
+        if (err instanceof GuardDenied) throw err;
+        errors.push(err);
+      }
+      this._signalMetaSubtree(mnode, messages, vis, downOpts, errors);
+    }
+  }
+  describe(options) {
+    const actor = options?.actor;
+    const filter = options?.filter;
+    const includeFields = resolveDescribeFields(options?.detail, options?.fields);
+    const isSpec = options?.format === "spec";
+    const effectiveFields = isSpec ? resolveDescribeFields("minimal") : includeFields;
+    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, effectiveFields);
+      const deps = n instanceof NodeImpl ? n._deps.map((d) => nodeToPath.get(d.node) ?? d.node.name ?? "") : [];
+      const { name: _name, ...rest } = raw;
+      const entry = { ...rest, deps };
+      if (!isSpec) {
+        const reason = this._annotations.get(p);
+        if (reason != null) entry.reason = reason;
+      }
+      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.edges({ recursive: true }).map(
+      ([from, to]) => ({ from, to })
+    );
+    if (actor != null || filter != null) {
+      edges = edges.filter((e) => nodeKeys.has(e.from) && nodeKeys.has(e.to));
+    }
+    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;
+    const graph = this;
+    const baseOpts = options;
+    const struct = {
+      name: this.name,
+      nodes,
+      edges,
+      subgraphs,
+      expand(detailOrFields) {
+        const merged = { ...baseOpts, format: void 0 };
+        if (Array.isArray(detailOrFields)) {
+          merged.fields = detailOrFields;
+          merged.detail = void 0;
+        } else {
+          merged.detail = detailOrFields;
+          merged.fields = void 0;
+        }
+        return graph.describe(merged);
+      }
+    };
+    const opts = options ?? {};
+    const fmt = opts.format;
+    if (fmt === "json") return renderDescribeAsJson(struct, opts);
+    if (fmt === "pretty") return renderDescribeAsPretty(struct, opts);
+    if (fmt === "mermaid") return renderDescribeAsMermaid(struct, opts);
+    if (fmt === "d2") return renderDescribeAsD2(struct, opts);
+    return struct;
+  }
+  _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;
+  }
+  /**
+   * Snapshot-based resource profile: per-node stats, orphan effect detection,
+   * memory hotspots. Zero runtime overhead — walks nodes on demand.
+   *
+   * @param opts - Optional `topN` for hotspot limit (default 10).
+   * @returns Aggregate profile with per-node details, hotspots, and orphan effects.
+   */
+  resourceProfile(opts) {
+    return graphProfile(this, opts);
+  }
+  reachable(from, direction, opts = {}) {
+    if (opts.withDetail === true) {
+      return reachable(this.describe(), from, direction, {
+        ...opts,
+        withDetail: true
+      });
+    }
+    return reachable(this.describe(), from, direction, opts);
+  }
+  /**
+   * Causal walkback: shortest dep-chain from `from` to `to`, enriched with
+   * each node's value, status, last-mutation actor, and reasoning annotation
+   * from {@link Graph.trace}. Wraps {@link explainPath} (roadmap §9.2).
+   *
+   * @param from - Upstream node (the cause).
+   * @param to - Downstream node (the effect).
+   * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+   *   and `from === to`, returns the shortest cycle through other nodes
+   *   (useful for diagnosing feedback loops, COMPOSITION-GUIDE §7).
+   *   Annotations and lastMutations are collected automatically from the
+   *   live graph.
+   */
+  explain(from, to, opts) {
+    const described = this.describe({ detail: "full" });
+    const annotations = new Map(this._annotations);
+    const lastMutations = /* @__PURE__ */ new Map();
+    for (const [path, n] of Object.entries(described.nodes)) {
+      if (n.lastMutation != null) lastMutations.set(path, n.lastMutation);
+    }
+    return explainPath(described, from, to, {
+      ...opts?.maxDepth != null ? { maxDepth: opts.maxDepth } : {},
+      ...opts?.findCycle === true ? { findCycle: true } : {},
+      annotations,
+      lastMutations
+    });
+  }
+  /**
+   * @internal Collect all qualified paths in this graph tree matching a
+   * glob pattern. Used by scoped autoCheckpoint subscription.
+   */
+  _pathsMatching(glob) {
+    const re = globToRegex(glob);
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    return targets.map(([p]) => p).filter((p) => re.test(p));
+  }
+  _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) {
+    const isPath = typeof pathOrOpts === "string";
+    const rawOpts = isPath ? options : pathOrOpts;
+    const resolved = resolveObserveDetail(rawOpts);
+    const wantsStructured = resolved.structured === true || resolved.timeline === true || resolved.causal === true || resolved.derived === true || resolved.detail === "minimal" || resolved.detail === "full" || resolved.format != null;
+    const actor = resolved.actor;
+    if (isPath) {
+      const path = pathOrOpts;
+      const target = this.resolve(path);
+      if (actor != null && !target.allowsObserve(actor)) {
+        throw new GuardDenied({ actor, action: "observe", nodeName: path });
+      }
+      if (wantsStructured) return this._buildStructuredObserver([[path, target]], resolved, "one");
+      return {
+        subscribe(sink) {
+          return target.subscribe(sink);
+        },
+        up(messages) {
+          try {
+            target.up?.(messages);
+          } catch (err) {
+            if (err instanceof GuardDenied) return;
+            throw err;
+          }
+        }
+      };
+    }
+    const collected = [];
+    this._collectObserveTargets("", collected);
+    collected.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const picked = actor == null ? collected : collected.filter(([, nd]) => nd.allowsObserve(actor));
+    if (wantsStructured) return this._buildStructuredObserver(picked, resolved, "all");
+    return {
+      subscribe: (sink) => {
+        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;
+        }
+      }
+    };
+  }
+  /** Dispatch helper — builds a unified observer + its expand closure. */
+  _buildStructuredObserver(targets, options, mode) {
+    const firstPath = mode === "one" ? targets[0]?.[0] : void 0;
+    const expand = (merged) => {
+      if (mode === "one" && firstPath != null) {
+        const target = this.resolve(firstPath);
+        return this._buildStructuredObserver([[firstPath, target]], merged, "one");
+      }
+      const collected = [];
+      this._collectObserveTargets("", collected);
+      collected.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+      const actor = merged.actor;
+      const picked = actor == null ? collected : collected.filter(([, nd]) => nd.allowsObserve(actor));
+      return this._buildStructuredObserver(picked, merged, "all");
+    };
+    return this._createObserveResult(targets, options, expand);
+  }
+  /**
+   * Unified observer builder — replaces the four ex-creators
+   * (`_createObserveResult` / `...ForAll` / `_createFallback…`). Accepts a
+   * list of `[path, node]` targets (single-element for one-node observe,
+   * N-element for all-nodes). Inspector hooks attach per-target when
+   * `causal`/`derived` requested AND `config.inspectorEnabled`; otherwise
+   * those fields gracefully drop.
+   *
+   * Events flow through a `recordEvent()` helper so the format logger,
+   * ring-buffer, and async-iterable hooks all share one push path.
+   */
+  _createObserveResult(targets, options, expand) {
+    const timeline = options.timeline === true;
+    const causal = options.causal === true;
+    const derived = options.derived === true;
+    const minimal = options.detail === "minimal";
+    const inspectorOn = this.config.inspectorEnabled;
+    const wantInspector = (causal || derived) && inspectorOn;
+    const maxEvents = options.maxEvents;
+    const ring = maxEvents != null && maxEvents > 0 ? new RingBuffer(maxEvents) : null;
+    const events = [];
+    const listeners = /* @__PURE__ */ new Set();
+    const values = {};
+    const nodeErrored = /* @__PURE__ */ new Set();
+    let dirtyCount = 0;
+    let resolvedCount = 0;
+    let invalidateCount = 0;
+    let pauseCount = 0;
+    let resumeCount = 0;
+    let teardownCount = 0;
+    let anyCompletedCleanly = false;
+    let anyErrored = false;
+    let batchSeq = 0;
+    const lastTriggerDepIndex = /* @__PURE__ */ new Map();
+    const lastRunDepValues = /* @__PURE__ */ new Map();
+    const lastRunDepBatches = /* @__PURE__ */ new Map();
+    const recordEvent = (event) => {
+      if (ring) ring.push(event);
+      else events.push(event);
+      for (const listener of listeners) listener(event);
+    };
+    const baseMeta = () => timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching(), batch_id: batchSeq } : {};
+    const attachInspector = (target, path) => {
+      if (!wantInspector || !(target instanceof NodeImpl)) return void 0;
+      return target._setInspectorHook((ev) => {
+        if (ev.kind === "dep_message") {
+          lastTriggerDepIndex.set(target, ev.depIndex);
+        } else if (ev.kind === "run") {
+          const effective = ev.batchData.map(
+            (b, i) => b != null && b.length > 0 ? b.at(-1) : ev.prevData[i]
+          );
+          lastRunDepValues.set(target, effective);
+          const batches = ev.batchData.map(
+            (b) => b != null ? [...b] : void 0
+          );
+          lastRunDepBatches.set(target, batches);
+          if (derived) {
+            recordEvent({
+              type: "derived",
+              path,
+              dep_values: effective,
+              dep_batches: batches,
+              ...baseMeta()
+            });
+          }
+        }
+      });
+    };
+    const buildCausal = (target) => {
+      const idx = lastTriggerDepIndex.get(target);
+      const depValues = lastRunDepValues.get(target);
+      if (!causal || depValues == null) return {};
+      const triggerDep = idx != null && idx >= 0 && target instanceof NodeImpl ? target._deps[idx] : void 0;
+      const triggerNode = triggerDep?.node;
+      const tv = triggerNode?.v;
+      const depBatches = lastRunDepBatches.get(target);
+      return {
+        trigger_dep_index: idx,
+        trigger_dep_name: triggerNode?.name,
+        ...tv != null ? { trigger_version: { id: tv.id, version: tv.version } } : {},
+        dep_values: [...depValues],
+        ...depBatches != null ? { dep_batches: depBatches } : {}
+      };
+    };
+    const inspectorDetaches = [];
+    const unsubs = [];
+    for (const [path, target] of targets) {
+      const detach = attachInspector(target, path);
+      if (detach) inspectorDetaches.push(detach);
+      unsubs.push(
+        target.subscribe((msgs) => {
+          batchSeq++;
+          for (const m of msgs) {
+            const t = m[0];
+            const base = baseMeta();
+            if (t === DATA) {
+              values[path] = m[1];
+              recordEvent({
+                type: "data",
+                path,
+                data: m[1],
+                ...base,
+                ...buildCausal(target)
+              });
+            } else if (minimal) {
+              if (t === DIRTY) dirtyCount++;
+              else if (t === RESOLVED) resolvedCount++;
+              else if (t === INVALIDATE) invalidateCount++;
+              else if (t === PAUSE) pauseCount++;
+              else if (t === RESUME) resumeCount++;
+              else if (t === TEARDOWN) teardownCount++;
+              else if (t === COMPLETE && !nodeErrored.has(path)) anyCompletedCleanly = true;
+              else if (t === ERROR) {
+                anyErrored = true;
+                nodeErrored.add(path);
+              }
+            } else if (t === DIRTY) {
+              dirtyCount++;
+              recordEvent({ type: "dirty", path, ...base });
+            } else if (t === RESOLVED) {
+              resolvedCount++;
+              recordEvent({
+                type: "resolved",
+                path,
+                ...base,
+                ...buildCausal(target)
+              });
+            } else if (t === INVALIDATE) {
+              invalidateCount++;
+              recordEvent({ type: "invalidate", path, ...base });
+            } else if (t === PAUSE) {
+              pauseCount++;
+              recordEvent({ type: "pause", path, lockId: m[1], ...base });
+            } else if (t === RESUME) {
+              resumeCount++;
+              recordEvent({ type: "resume", path, lockId: m[1], ...base });
+            } else if (t === COMPLETE) {
+              if (!nodeErrored.has(path)) anyCompletedCleanly = true;
+              recordEvent({ type: "complete", path, ...base });
+            } else if (t === ERROR) {
+              anyErrored = true;
+              nodeErrored.add(path);
+              recordEvent({
+                type: "error",
+                path,
+                data: m[1],
+                ...base
+              });
+            } else if (t === TEARDOWN) {
+              teardownCount++;
+              recordEvent({ type: "teardown", path, ...base });
+            }
+          }
+        })
+      );
+    }
+    let disposed = false;
+    const dispose = () => {
+      if (disposed) return;
+      disposed = true;
+      for (const u of unsubs) u();
+      for (const d of inspectorDetaches) d();
+      for (const resolve of asyncResolvers) resolve({ value: void 0, done: true });
+      asyncResolvers.length = 0;
+    };
+    const asyncQueue = [];
+    const asyncResolvers = [];
+    listeners.add((ev) => {
+      const resolve = asyncResolvers.shift();
+      if (resolve) resolve({ value: ev, done: false });
+      else asyncQueue.push(ev);
+    });
+    const result = {
+      get values() {
+        return values;
+      },
+      get dirtyCount() {
+        return dirtyCount;
+      },
+      get resolvedCount() {
+        return resolvedCount;
+      },
+      get invalidateCount() {
+        return invalidateCount;
+      },
+      get pauseCount() {
+        return pauseCount;
+      },
+      get resumeCount() {
+        return resumeCount;
+      },
+      get teardownCount() {
+        return teardownCount;
+      },
+      get events() {
+        return ring ? ring.toArray() : [...events];
+      },
+      get anyCompletedCleanly() {
+        return anyCompletedCleanly;
+      },
+      get anyErrored() {
+        return anyErrored;
+      },
+      get completedWithoutErrors() {
+        return anyCompletedCleanly && !anyErrored;
+      },
+      onEvent(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      dispose,
+      expand(extra) {
+        dispose();
+        const merged = { ...options };
+        if (typeof extra === "string") {
+          merged.detail = extra;
+        } else {
+          Object.assign(merged, extra);
+        }
+        return expand(resolveObserveDetail(merged));
+      },
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            if (asyncQueue.length > 0) {
+              return Promise.resolve({ value: asyncQueue.shift(), done: false });
+            }
+            if (disposed) return Promise.resolve({ value: void 0, done: true });
+            return new Promise((resolve) => asyncResolvers.push(resolve));
+          },
+          return() {
+            dispose();
+            return Promise.resolve({ value: void 0, done: true });
+          }
+        };
+      }
+    };
+    if (options.format != null) this._attachFormatLogger(result, options);
+    return result;
+  }
+  /**
+   * Attach format-rendering logger to an ObserveResult by subscribing to its
+   * event stream (no monkey-patching). Renders each event per `format` and
+   * `theme`, filtered by `includeTypes` / `excludeTypes`.
+   */
+  _attachFormatLogger(result, options) {
+    const format = options.format;
+    if (format == null) return;
+    const logger = options.logger ?? ((line) => console.log(line));
+    const include = options.includeTypes ? new Set(options.includeTypes) : null;
+    const exclude = options.excludeTypes ? new Set(options.excludeTypes) : null;
+    const shouldLog = include == null && exclude == null ? () => true : (type) => (include == null || include.has(type)) && (exclude == null || !exclude.has(type));
+    const theme = resolveObserveTheme(options.theme);
+    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 isDataBearing = event.type === "data" || event.type === "error";
+      const isLockBearing = event.type === "pause" || event.type === "resume";
+      const dataPart = isDataBearing ? ` ${describeData(event.data)}` : isLockBearing ? ` ${describeData(event.lockId)}` : "";
+      const causal = event.type === "data" || event.type === "resolved" || event.type === "derived" ? event : void 0;
+      const triggerPart = causal?.trigger_dep_name != null ? ` <- ${causal.trigger_dep_name}` : causal?.trigger_dep_index != null ? ` <- #${causal.trigger_dep_index}` : "";
+      const batchPart = event.in_batch ? " [batch]" : "";
+      return `${pathPart}${color}${event.type.toUpperCase()}${theme.reset}${dataPart}${triggerPart}${batchPart}`;
+    };
+    result.onEvent((event) => {
+      if (shouldLog(event.type)) logger(renderEvent(event), event);
+    });
+  }
+  // `dumpGraph` is folded into `describe({format: "pretty" | "json"})` (Unit 12).
+  // `toMermaid` / `toD2` are folded into `describe({format: "mermaid" | "d2"})` (Unit 20).
+  // ——————————————————————————————————————————————————————————————
+  //  Lifecycle & persistence (§3.7–§3.8)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Register a cleanup function to be called on {@link Graph.destroy}.
+   *
+   * Factories use this to attach teardown logic for internal nodes, keepalive
+   * subscriptions, or other resources that are not registered on the graph and
+   * would otherwise leak on repeated create/destroy cycles.
+   *
+   * Returns a removal function — call it to unregister the disposer early.
+   */
+  addDisposer(fn) {
+    this._disposers.add(fn);
+    return () => {
+      this._disposers.delete(fn);
+    };
+  }
+  /**
+   * Drains disposers (registered via {@link addDisposer}), then sends `[[TEARDOWN]]` to all
+   * nodes and 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() {
+    drainDisposers(this._disposers, this.name);
+    this.signal([[TEARDOWN]], { internal: true });
+    drainDisposers(this._storageDisposers, this.name);
+    for (const child of [...this._mounts.values()]) {
+      child._parent = void 0;
+      child._destroyClearOnly();
+    }
+    this._mounts.clear();
+    this._nodes.clear();
+    this._parent = void 0;
+  }
+  /** Clear structure after parent already signaled TEARDOWN through this subtree. */
+  _destroyClearOnly() {
+    for (const child of [...this._mounts.values()]) {
+      child._parent = void 0;
+      child._destroyClearOnly();
+    }
+    this._mounts.clear();
+    this._nodes.clear();
+    this._parent = void 0;
+  }
+  snapshot(opts) {
+    const { expand: _, ...d } = this.describe({ detail: "full" });
+    const sortedNodes = {};
+    for (const key of Object.keys(d.nodes).sort()) {
+      const { lastMutation: _lm, guard: _g, ...node2 } = d.nodes[key];
+      sortedNodes[key] = node2;
+    }
+    const sortedSubgraphs = [...d.subgraphs].sort();
+    const snap = {
+      ...d,
+      version: 1,
+      nodes: sortedNodes,
+      subgraphs: sortedSubgraphs
+    };
+    if (opts?.format == null) return snap;
+    if (opts.format === "json-string") return JSON.stringify(snap);
+    if (opts.format === "bytes") {
+      if (opts.codec == null) {
+        throw new Error("snapshot({format: 'bytes'}) requires a `codec` name");
+      }
+      const codec = this.config.lookupCodec(opts.codec);
+      if (codec == null) {
+        throw new Error(
+          `snapshot: codec "${opts.codec}" is not registered on this graph's config. Call config.registerCodec(...) before creating nodes.`
+        );
+      }
+      return encodeEnvelope(codec, codec.encode(snap));
+    }
+    throw new Error(`snapshot: unknown format "${String(opts.format)}"`);
+  }
+  /**
+   * Auto-dispatch a byte buffer produced by {@link Graph.snapshot} with
+   * `{format: "bytes", codec: name}`. Reads the v1 envelope, resolves the
+   * named codec on `config` (defaults to `defaultConfig`), and returns the
+   * decoded snapshot. Combine with {@link Graph.fromSnapshot} to rehydrate
+   * a full graph topology from bytes.
+   *
+   * @throws If the envelope is malformed or the named codec isn't
+   *   registered on the target config.
+   */
+  static decode(bytes, opts) {
+    const cfg = opts?.config ?? defaultConfig;
+    const { codec, codecVersion, payload } = decodeEnvelope(bytes, cfg);
+    return codec.decode(payload, codecVersion);
+  }
+  /**
+   * Apply persisted values onto an existing graph whose topology matches the snapshot
+   * (§3.8). Only {@link DescribeNodeOutput.type} `state` entries with a `value` field
+   * are written by default; `derived` / `operator` / `effect` are always skipped so
+   * deps drive recomputation. `producer` entries are skipped unless `includeProducers`
+   * is set (producers recompute on activation, so restoring is usually a no-op
+   * overwritten on the next wave — opt in for audit / forensic round-trip use cases).
+   * 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));
+    const includeProducers = options?.includeProducers === true;
+    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) continue;
+      if (!("value" in slice) || slice.value === void 0) {
+        if ("value" in slice && slice.value === void 0) {
+          options?.onError?.(
+            path,
+            new Error(
+              `restore: slice.value is undefined for "${path}" (undefined is the global SENTINEL; not valid DATA)`
+            )
+          );
+        }
+        continue;
+      }
+      if (slice.type === "derived" || slice.type === "effect") {
+        continue;
+      }
+      if (slice.type === "producer" && !includeProducers) {
+        continue;
+      }
+      if (slice.v != null) {
+        const live = this.tryResolve(path);
+        const lv = live?.v;
+        if (lv != null && lv.id === slice.v.id && lv.version === slice.v.version) {
+          continue;
+        }
+      }
+      try {
+        this.set(path, slice.value);
+      } catch (err) {
+        options?.onError?.(path, err);
+      }
+    }
+  }
+  /**
+   * 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 opts - Either a legacy `build(g)` callback, or an options object:
+   *   - `build?` — topology constructor; skips auto-hydration when present.
+   *   - `factories?` — map from glob pattern to {@link GraphNodeFactory},
+   *     used by auto-hydration to reconstruct non-state nodes. Per-call (no
+   *     process-global registry). First matching pattern wins.
+   * @returns Hydrated `Graph` instance.
+   */
+  static fromSnapshot(data, opts) {
+    parseSnapshotEnvelope(data);
+    const build = typeof opts === "function" ? opts : opts?.build;
+    const factoryMap = typeof opts === "function" ? void 0 : opts?.factories;
+    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 factories = factoryMap ? Object.entries(factoryMap).map(([pattern, factory]) => ({
+      re: globToRegex(pattern),
+      factory
+    })) : [];
+    const factoryForPath = (path) => {
+      for (const entry of factories) {
+        if (entry.re.test(path)) return entry.factory;
+      }
+      return void 0;
+    };
+    const ownerForPath = (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 = g;
+      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];
+    };
+    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] = ownerForPath(path);
+        const meta = { ...slice?.meta ?? {} };
+        const factory = 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}. Pass matching factories via fromSnapshot(data, { factories: { pattern: factoryFn } }).`
+      );
+    }
+    g.restore(data);
+    return g;
+  }
+  /**
+   * ECMAScript `JSON.stringify` hook — returns the same object as
+   * {@link Graph.snapshot}. Makes `JSON.stringify(graph)` "just work"
+   * without double-encoding.
+   */
+  toJSON() {
+    return this.snapshot();
+  }
+  /**
+   * Unified persistence surface (§3.8). Cascades snapshot records through
+   * one or more {@link StorageTier}s, each with its own `debounceMs` /
+   * `compactEvery` cadence and independent diff baseline.
+   *
+   * Subscription gates on {@link messageTier} ≥ 3 (DATA/RESOLVED/terminal),
+   * never on tier-0/1/2 control waves (START/DIRTY/INVALIDATE/PAUSE/RESUME)
+   * or tier-5 TEARDOWN (graceful shutdown is the caller's responsibility).
+   *
+   * Per-tier cadence lets the hot tier stay sync while cold tiers absorb
+   * async writes without blocking the hot path. Each tier holds its own
+   * `{lastSnapshot, lastVersionFingerprint}` so cold-tier diff baselines
+   * aren't polluted by hot-tier flushes. Tiers with `debounceMs === 0`
+   * share a single snapshot computation per observe event; debounced tiers
+   * compute their own snapshot when their timer fires.
+   */
+  attachStorage(tiers, options = {}) {
+    const states = tiers.map((tier) => ({
+      tier,
+      debounceMs: Math.max(0, tier.debounceMs ?? 0),
+      compactEvery: Math.max(1, tier.compactEvery ?? 10),
+      timer: void 0,
+      seq: 0,
+      lastSnapshot: void 0,
+      lastFingerprint: "",
+      disposed: false,
+      savePending: void 0
+    }));
+    if (options.autoRestore === true) {
+      void this._cascadeRestore(tiers, options.onError);
+    }
+    const runFlush = (s, snapshot) => {
+      if (s.disposed) return;
+      const fingerprint = computeVersionFingerprint(snapshot.nodes);
+      if (s.lastSnapshot != null && fingerprint !== "" && fingerprint === s.lastFingerprint) {
+        return;
+      }
+      const nextSeq = s.seq + 1;
+      const timestamp_ns = wallClockNs();
+      const isFirst = s.lastSnapshot == null;
+      const shouldCompact = isFirst || nextSeq % s.compactEvery === 0;
+      const record = shouldCompact ? {
+        mode: "full",
+        snapshot,
+        seq: nextSeq,
+        timestamp_ns,
+        format_version: SNAPSHOT_VERSION
+      } : {
+        mode: "diff",
+        diff: diffForWAL(s.lastSnapshot, snapshot),
+        seq: nextSeq,
+        timestamp_ns,
+        format_version: SNAPSHOT_VERSION
+      };
+      if (s.tier.filter && !s.tier.filter(this.name, record)) {
+        return;
+      }
+      let result;
+      try {
+        result = s.tier.save(this.name, record);
+      } catch (error) {
+        options.onError?.(error, s.tier);
+        return;
+      }
+      if (result && typeof result.then === "function") {
+        const prev = s.savePending ?? Promise.resolve();
+        const chained = prev.then(
+          () => result,
+          // Previous rejection already surfaced; don't block this save.
+          () => result
+        );
+        const final = chained.then(
+          () => {
+            if (s.disposed) return;
+            s.seq = nextSeq;
+            s.lastSnapshot = snapshot;
+            s.lastFingerprint = fingerprint;
+          },
+          (err) => {
+            options.onError?.(err, s.tier);
+          }
+        );
+        s.savePending = final.finally(() => {
+          if (s.savePending === final) s.savePending = void 0;
+        });
+      } else {
+        s.seq = nextSeq;
+        s.lastSnapshot = snapshot;
+        s.lastFingerprint = fingerprint;
+      }
+    };
+    const flushTier = (s, snapshot) => {
+      try {
+        runFlush(s, snapshot);
+      } catch (error) {
+        options.onError?.(error, s.tier);
+      }
+    };
+    const onEvent = (path, messages) => {
+      const triggeredByTier = messages.some((m) => {
+        const tier = this.config.messageTier(m[0]);
+        return tier >= 3 && tier < 5;
+      });
+      if (!triggeredByTier) return;
+      if (options.filter) {
+        const nd = this.tryResolve(path);
+        if (nd == null) return;
+        const described = describeNode(nd, resolveDescribeFields("standard"));
+        if (!options.filter(path, described)) return;
+      }
+      let sharedSnapshot;
+      const getSnapshot = () => {
+        if (sharedSnapshot == null) sharedSnapshot = this.snapshot();
+        return sharedSnapshot;
+      };
+      for (const s of states) {
+        if (s.disposed) continue;
+        if (s.debounceMs === 0) {
+          flushTier(s, getSnapshot());
+        } else {
+          if (s.timer == null) s.timer = new ResettableTimer();
+          s.timer.start(s.debounceMs, () => {
+            if (s.disposed) return;
+            flushTier(s, this.snapshot());
+          });
+        }
+      }
+    };
+    let off;
+    if (options.paths != null) {
+      const paths = typeof options.paths === "string" ? this._pathsMatching(options.paths) : options.paths;
+      const unsubs = paths.map((p) => {
+        const nd = this.tryResolve(p);
+        if (nd == null) return () => {
+        };
+        return nd.subscribe((msgs) => onEvent(p, msgs));
+      });
+      off = () => {
+        for (const u of unsubs) u();
+      };
+    } else {
+      off = this.observe().subscribe((path, messages) => onEvent(path, messages));
+    }
+    const dispose = () => {
+      off();
+      for (const s of states) {
+        s.disposed = true;
+        s.timer?.cancel();
+      }
+      this._storageDisposers.delete(dispose);
+    };
+    this._storageDisposers.add(dispose);
+    return { dispose };
+  }
+  /**
+   * Try tiers in order (hottest first); apply the first record that hits
+   * via {@link Graph.restore}. Returns `true` if any tier produced a
+   * restorable snapshot, `false` if all missed.
+   *
+   * Resilience: a tier that returns data which cannot be restored (load
+   * throws, shape unrecognized, or `restore()` itself throws) does not abort
+   * the cascade — the error is routed through `onError` (if supplied) and
+   * the next colder tier is tried. This mirrors how a multi-tier cache
+   * falls through on a corrupt hot entry.
+   *
+   * Note: `restore()` mutates state incrementally. If a restore throws
+   * partway through, the graph may hold a mixed state (some slices from
+   * the bad tier, some pre-existing). A subsequent successful tier's
+   * `restore()` overwrites the overlapping slices.
+   *
+   * Internal helper shared by {@link Graph.attachStorage}'s `autoRestore`
+   * option and the static {@link Graph.fromStorage} factory.
+   */
+  async _cascadeRestore(tiers, onError) {
+    for (const tier of tiers) {
+      let raw;
+      try {
+        raw = await tier.load(this.name);
+      } catch (err) {
+        onError?.(err, tier);
+        continue;
+      }
+      if (raw == null) continue;
+      if (typeof raw !== "object" || Array.isArray(raw)) continue;
+      const record = raw;
+      try {
+        if (record.mode === "full" && record.snapshot != null) {
+          this.restore(record.snapshot);
+          return true;
+        }
+        if (record.version === SNAPSHOT_VERSION && record.nodes != null) {
+          this.restore(record);
+          return true;
+        }
+      } catch (err) {
+        onError?.(err, tier);
+      }
+    }
+    return false;
+  }
+  /**
+   * Construct a fresh {@link Graph} pre-hydrated from the first tier that
+   * hits. Delegates topology reconstruction to {@link Graph.fromSnapshot}
+   * on `"full"` records and direct {@link Graph.restore} on bare snapshots.
+   *
+   * Always asynchronous — awaits `tier.load()` for async tier support even
+   * when all tiers are sync. Callers that know they only pass sync tiers
+   * can safely `await` immediately.
+   *
+   * @throws If no tier holds a restorable record matching `name` *and* no
+   *   `factories` override is provided for dynamic nodes.
+   */
+  static async fromStorage(name, tiers, opts) {
+    for (const tier of tiers) {
+      let raw;
+      try {
+        raw = await tier.load(name);
+      } catch (err) {
+        opts?.onError?.(err, tier);
+        continue;
+      }
+      if (raw == null) continue;
+      if (typeof raw !== "object" || Array.isArray(raw)) continue;
+      const record = raw;
+      const snapshot = record.mode === "full" && record.snapshot != null ? record.snapshot : record.version === SNAPSHOT_VERSION && record.nodes != null ? record : void 0;
+      if (snapshot == null) continue;
+      try {
+        return _Graph.fromSnapshot(snapshot, opts);
+      } catch (err) {
+        opts?.onError?.(err, tier);
+      }
+    }
+    throw new Error(
+      `Graph.fromStorage: no tier held a restorable record for "${name}" across ${tiers.length} tier(s)`
+    );
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Inspector (roadmap 3.3) — reasoning trace, overhead gating
+  // ——————————————————————————————————————————————————————————————
+  // Inspector gating lives on `this.config.inspectorEnabled` (see
+  // `core/config.ts`). Default: `true` outside `NODE_ENV === "production"`.
+  _annotations = /* @__PURE__ */ new Map();
+  _traceRing;
+  trace(path, reason, opts) {
+    if (path != null && reason != null) {
+      if (!this.config.inspectorEnabled) return;
+      if (this.tryResolve(path) == null) return;
+      this._annotations.set(path, reason);
+      const entry = {
+        path,
+        reason,
+        timestamp_ns: monotonicNs(),
+        ...opts?.actor != null ? { actor: opts.actor } : {}
+      };
+      this._traceRing.push(entry);
+      return;
+    }
+    if (!this.config.inspectorEnabled) return [];
+    return this._traceRing.toArray();
+  }
+  /**
+   * Latest reason annotation attached to `path` via {@link Graph.trace},
+   * or `undefined` if none. `describe()` surfaces this via the `reason`
+   * field on each node entry (when present).
+   */
+  annotation(path) {
+    return this._annotations.get(path);
+  }
+  /**
+   * Clear all reasoning-trace state (both the per-path annotations map and
+   * the ring buffer). Useful for long-running processes that want periodic
+   * resets, or tests that need a clean slate.
+   */
+  clearTrace() {
+    this._annotations.clear();
+    this._traceRing.clear();
+  }
+  /**
+   * Remove trace entries matching `predicate`. Returns the number of
+   * entries removed. Does not touch the per-path annotations map — call
+   * {@link Graph.clearTrace} for a full reset.
+   */
+  pruneTrace(predicate) {
+    const kept = this._traceRing.toArray().filter((e) => !predicate(e));
+    const removed = this._traceRing.size - kept.length;
+    this._traceRing.clear();
+    for (const e of kept) this._traceRing.push(e);
+    return removed;
+  }
+  /**
+   * 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 = [];
+    const versionChanges = [];
+    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) {
+        versionChanges.push({
+          path: key,
+          id: av.id,
+          from: av.version,
+          to: bv.version
+        });
+      }
+      const versionMatches = av != null && bv != null && av.id === bv.id && av.version === bv.version;
+      for (const field of ["type", "status", "sentinel"]) {
+        const va = na[field];
+        const vb = nb[field];
+        if (va !== vb) {
+          nodesChanged.push({ path: key, field, from: va, to: vb });
+        }
+      }
+      if (versionMatches) continue;
+      for (const field of ["value", "meta"]) {
+        const va = na[field];
+        const vb = nb[field];
+        if (!deepEqual(va, vb)) {
+          nodesChanged.push({ path: key, field, from: va, to: vb });
+        }
+      }
+    }
+    const edgeKey = (e) => `${e.from}	${e.to}`;
+    const aEdges = new Set(a.edges.map(edgeKey));
+    const bEdges = new Set(b.edges.map(edgeKey));
+    const edgesAdded = b.edges.filter((e) => !aEdges.has(edgeKey(e)));
+    const edgesRemoved = a.edges.filter((e) => !bEdges.has(edgeKey(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,
+      versionChanges,
+      edgesAdded,
+      edgesRemoved,
+      subgraphsAdded,
+      subgraphsRemoved
+    };
+  }
+};
+function diffForWAL(a, b) {
+  const base = Graph.diff(a, b);
+  const nodesAddedFull = {};
+  for (const path of base.nodesAdded) {
+    const slice = b.nodes[path];
+    if (slice != null) nodesAddedFull[path] = slice;
+  }
+  return { ...base, nodesAddedFull };
+}
+function reachable(described, from, direction, options = {}) {
+  const empty = { paths: [], depths: /* @__PURE__ */ new Map(), truncated: false };
+  if (!from) return options.withDetail ? empty : [];
+  if (!options.both && 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 options.withDetail ? empty : [];
+  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();
+  for (const [path, node2] of Object.entries(described.nodes)) {
+    if (!path) continue;
+    universe.add(path);
+    const deps = node2.deps ?? [];
+    depsByPath.set(path, deps);
+    for (const dep of deps) {
+      if (!dep) continue;
+      universe.add(dep);
+      if (!reverseDeps.has(dep)) reverseDeps.set(dep, /* @__PURE__ */ new Set());
+      reverseDeps.get(dep).add(path);
+    }
+  }
+  for (const edge of described.edges) {
+    if (edge == null || typeof edge !== "object") continue;
+    const from2 = typeof edge.from === "string" ? edge.from : "";
+    const to = typeof edge.to === "string" ? edge.to : "";
+    if (!from2 || !to) continue;
+    universe.add(from2);
+    universe.add(to);
+    if (!outgoingEdges.has(from2)) outgoingEdges.set(from2, /* @__PURE__ */ new Set());
+    outgoingEdges.get(from2).add(to);
+    if (!incomingEdges.has(to)) incomingEdges.set(to, /* @__PURE__ */ new Set());
+    incomingEdges.get(to).add(from2);
+  }
+  if (!universe.has(from)) return options.withDetail ? empty : [];
+  const doBoth = options.both === true;
+  const visit = (path) => {
+    if (doBoth) {
+      const up = depsByPath.get(path) ?? [];
+      const upEdges = incomingEdges.get(path);
+      const down2 = reverseDeps.get(path);
+      const downEdges2 = outgoingEdges.get(path);
+      const acc2 = [...up];
+      if (upEdges) acc2.push(...upEdges);
+      if (down2) acc2.push(...down2);
+      if (downEdges2) acc2.push(...downEdges2);
+      return acc2;
+    }
+    if (direction === "upstream") {
+      const up = depsByPath.get(path) ?? [];
+      const upEdges = incomingEdges.get(path);
+      if (!upEdges) return up;
+      return [...up, ...upEdges];
+    }
+    const down = reverseDeps.get(path);
+    const downEdges = outgoingEdges.get(path);
+    const acc = down ? [...down] : [];
+    if (downEdges) acc.push(...downEdges);
+    return acc;
+  };
+  const visited = /* @__PURE__ */ new Set([from]);
+  const depths = /* @__PURE__ */ new Map();
+  const queue = [{ path: from, depth: 0 }];
+  let head = 0;
+  let truncated = false;
+  while (head < queue.length) {
+    const next = queue[head++];
+    if (maxDepth != null && next.depth >= maxDepth) {
+      if (visit(next.path).length > 0) truncated = true;
+      continue;
+    }
+    for (const nb of visit(next.path)) {
+      if (!nb || visited.has(nb)) continue;
+      visited.add(nb);
+      depths.set(nb, next.depth + 1);
+      queue.push({ path: nb, depth: next.depth + 1 });
+    }
+  }
+  const paths = [...depths.keys()].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  if (options.withDetail) return { paths, depths, truncated };
+  return paths;
+}
+
+// src/compat/zustand/index.ts
+var alwaysDiffer = () => false;
+function create(initializer) {
+  const g = new Graph("zustand");
+  const s = state(void 0, {
+    name: "state",
+    equals: alwaysDiffer
+  });
+  g.add("state", s);
+  const getState = () => s.cache;
+  const setState = (partial, replace) => {
+    const prev = s.cache;
+    const next = typeof partial === "function" ? partial(prev) : partial;
+    s.emit(replace ? next : { ...prev, ...next });
+  };
+  const api = {
+    getState,
+    setState,
+    getInitialState: () => initialValue,
+    subscribe: (listener) => {
+      let initial = true;
+      let prev = s.cache;
+      return s.subscribe((msgs) => {
+        for (const [t, v] of msgs) {
+          if (t === DATA) {
+            if (initial) {
+              initial = false;
+              continue;
+            }
+            listener(v, prev);
+            prev = v;
+          }
+        }
+      });
+    },
+    destroy: g.destroy.bind(g)
+  };
+  const initialValue = initializer(setState, getState, api);
+  s.emit(initialValue);
+  return Object.assign(g, api);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  create
+});
+//# sourceMappingURL=index.cjs.map