@graphrefly/graphrefly 0.17.0 → 0.19.0

package/dist/compat/nestjs/index.cjs

@@ -95,11 +95,8 @@ __export(nestjs_exports, {
   getActor: () => getActor,
   getGraphToken: () => getGraphToken,
   getNodeToken: () => getNodeToken,
-  observeGraph$: () => observeGraph$,
-  observeNode$: () => observeNode$,
   observeSSE: () => observeSSE,
   observeSubscription: () => observeSubscription,
-  toMessages$: () => toMessages$,
   toObservable: () => toObservable
 });
 module.exports = __toCommonJS(nestjs_exports);
@@ -108,6 +105,7 @@ module.exports = __toCommonJS(nestjs_exports);
 var import_rxjs = require("rxjs");
 
 // 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");
@@ -117,13 +115,27 @@ 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 knownMessageTypes = [
+  START,
+  DATA,
+  DIRTY,
+  RESOLVED,
+  INVALIDATE,
+  PAUSE,
+  RESUME,
+  TEARDOWN,
+  COMPLETE,
+  ERROR
+];
+var knownMessageSet = new Set(knownMessageTypes);
 function messageTier(t) {
-  if (t === DIRTY || t === INVALIDATE) return 0;
-  if (t === PAUSE || t === RESUME) return 1;
-  if (t === DATA || t === RESOLVED) return 2;
-  if (t === COMPLETE || t === ERROR) return 3;
-  if (t === TEARDOWN) return 4;
-  return 0;
+  if (t === START) return 0;
+  if (t === DIRTY || t === INVALIDATE) return 1;
+  if (t === PAUSE || t === RESUME) return 2;
+  if (t === DATA || t === RESOLVED) return 3;
+  if (t === COMPLETE || t === ERROR) return 4;
+  if (t === TEARDOWN) return 5;
+  return 1;
 }
 function isPhase2Message(msg) {
   const t = msg[0];
@@ -137,48 +149,28 @@ function propagatesToMeta(t) {
 }
 
 // src/extra/observable.ts
-function toObservable(node2) {
-  return new import_rxjs.Observable((subscriber) => {
-    const unsub = node2.subscribe((msgs) => {
-      for (const m of msgs) {
+function toObservable(node2, options) {
+  if (options?.raw) {
+    return new import_rxjs.Observable((subscriber) => {
+      const unsub = node2.subscribe((msgs) => {
         if (subscriber.closed) return;
-        if (m[0] === DATA) {
-          subscriber.next(m[1]);
-        } else if (m[0] === ERROR) {
-          subscriber.error(m[1]);
-          return;
-        } else if (m[0] === COMPLETE) {
-          subscriber.complete();
-          return;
+        subscriber.next(msgs);
+        for (const m of msgs) {
+          if (m[0] === ERROR) {
+            subscriber.error(m[1]);
+            return;
+          }
+          if (m[0] === COMPLETE) {
+            subscriber.complete();
+            return;
+          }
         }
-      }
+      });
+      return unsub;
     });
-    return unsub;
-  });
-}
-function toMessages$(node2) {
+  }
   return new import_rxjs.Observable((subscriber) => {
     const unsub = node2.subscribe((msgs) => {
-      if (subscriber.closed) return;
-      subscriber.next(msgs);
-      for (const m of msgs) {
-        if (m[0] === ERROR) {
-          subscriber.error(m[1]);
-          return;
-        }
-        if (m[0] === COMPLETE) {
-          subscriber.complete();
-          return;
-        }
-      }
-    });
-    return unsub;
-  });
-}
-function observeNode$(graph, path, options) {
-  return new import_rxjs.Observable((subscriber) => {
-    const handle = graph.observe(path, options);
-    const unsub = handle.subscribe((msgs) => {
       for (const m of msgs) {
         if (subscriber.closed) return;
         if (m[0] === DATA) {
@@ -195,16 +187,6 @@ function observeNode$(graph, path, options) {
     return unsub;
   });
 }
-function observeGraph$(graph, options) {
-  return new import_rxjs.Observable((subscriber) => {
-    const handle = graph.observe(options);
-    const unsub = handle.subscribe((nodePath, messages) => {
-      if (subscriber.closed) return;
-      subscriber.next({ path: nodePath, messages });
-    });
-    return unsub;
-  });
-}
 
 // src/compat/nestjs/decorators.ts
 var import_common = require("@nestjs/common");
@@ -339,6 +321,82 @@ function normalizeActor(actor) {
   };
 }
 
+// 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;
+  }
+};
+function normalizeActions(action) {
+  if (Array.isArray(action)) {
+    return [...action];
+  }
+  return [action];
+}
+function matchesActions(set, action) {
+  return set.has(action) || set.has("*");
+}
+function policy(build) {
+  const rules = [];
+  const allow = (action, opts) => {
+    rules.push({
+      kind: "allow",
+      actions: new Set(normalizeActions(action)),
+      where: opts?.where ?? (() => true)
+    });
+  };
+  const deny = (action, opts) => {
+    rules.push({
+      kind: "deny",
+      actions: new Set(normalizeActions(action)),
+      where: opts?.where ?? (() => true)
+    });
+  };
+  build(allow, deny);
+  return (actor, action) => {
+    let denied = false;
+    let allowed = false;
+    for (const r of rules) {
+      if (!matchesActions(r.actions, action)) continue;
+      if (!r.where(actor)) continue;
+      if (r.kind === "deny") {
+        denied = true;
+      } else {
+        allowed = true;
+      }
+    }
+    if (denied) return false;
+    return allowed;
+  };
+}
+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/batch.ts
 var MAX_DRAIN_ITERATIONS = 1e3;
 var batchDepth = 0;
@@ -495,14 +553,14 @@ function _downSequential(sink, messages, phase = 2) {
   const dataQueue = phase === 3 ? pendingPhase3 : pendingPhase2;
   for (const msg of messages) {
     const tier = messageTier(msg[0]);
-    if (tier === 2) {
+    if (tier === 3) {
       if (isBatching()) {
         const m = msg;
         dataQueue.push(() => sink([m]));
       } else {
         sink([msg]);
       }
-    } else if (tier >= 3) {
+    } else if (tier >= 4) {
       if (isBatching()) {
         const m = msg;
         pendingPhase3.push(() => sink([m]));
@@ -515,82 +573,6 @@ function _downSequential(sink, messages, phase = 2) {
   }
 }
 
-// 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;
-  }
-};
-function normalizeActions(action) {
-  if (Array.isArray(action)) {
-    return [...action];
-  }
-  return [action];
-}
-function matchesActions(set, action) {
-  return set.has(action) || set.has("*");
-}
-function policy(build) {
-  const rules = [];
-  const allow = (action, opts) => {
-    rules.push({
-      kind: "allow",
-      actions: new Set(normalizeActions(action)),
-      where: opts?.where ?? (() => true)
-    });
-  };
-  const deny = (action, opts) => {
-    rules.push({
-      kind: "deny",
-      actions: new Set(normalizeActions(action)),
-      where: opts?.where ?? (() => true)
-    });
-  };
-  build(allow, deny);
-  return (actor, action) => {
-    let denied = false;
-    let allowed = false;
-    for (const r of rules) {
-      if (!matchesActions(r.actions, action)) continue;
-      if (!r.where(actor)) continue;
-      if (r.kind === "deny") {
-        denied = true;
-      } else {
-        allowed = true;
-      }
-    }
-    if (denied) return false;
-    return allowed;
-  };
-}
-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
 var import_node_crypto = require("crypto");
 function canonicalizeForHash(value) {
@@ -643,10 +625,24 @@ function advanceVersion(info, newValue, hashFn) {
   }
 }
 
-// src/core/node.ts
+// src/core/node-base.ts
 var NO_VALUE = /* @__PURE__ */ Symbol.for("graphrefly/NO_VALUE");
 var CLEANUP_RESULT = /* @__PURE__ */ Symbol.for("graphrefly/CLEANUP_RESULT");
-function createIntBitSet() {
+var isCleanupResult = (value) => typeof value === "object" && value !== null && CLEANUP_RESULT in value;
+var isCleanupFn = (value) => typeof value === "function";
+function statusAfterMessage(status, msg) {
+  const t = msg[0];
+  if (t === DIRTY) return "dirty";
+  if (t === DATA) return "settled";
+  if (t === RESOLVED) return "resolved";
+  if (t === COMPLETE) return "completed";
+  if (t === ERROR) return "errored";
+  if (t === INVALIDATE) return "dirty";
+  if (t === TEARDOWN) return "disconnected";
+  return status;
+}
+function createIntBitSet(size) {
+  const fullMask = size >= 32 ? -1 : ~(-1 << size);
   let bits = 0;
   return {
     set(i) {
@@ -659,7 +655,8 @@ function createIntBitSet() {
       return (bits & 1 << i) !== 0;
     },
     covers(other) {
-      return (bits & other._bits()) === other._bits();
+      const otherBits = other._bits();
+      return (bits & otherBits) === otherBits;
     },
     any() {
       return bits !== 0;
@@ -667,6 +664,9 @@ function createIntBitSet() {
     reset() {
       bits = 0;
     },
+    setAll() {
+      bits = fullMask;
+    },
     _bits() {
       return bits;
     }
@@ -674,6 +674,8 @@ function createIntBitSet() {
 }
 function createArrayBitSet(size) {
   const words = new Uint32Array(Math.ceil(size / 32));
+  const lastBits = size % 32;
+  const lastWordMask = lastBits === 0 ? 4294967295 : (1 << lastBits) - 1 >>> 0;
   return {
     set(i) {
       words[i >>> 5] |= 1 << (i & 31);
@@ -700,130 +702,103 @@ function createArrayBitSet(size) {
     reset() {
       words.fill(0);
     },
+    setAll() {
+      for (let w = 0; w < words.length - 1; w++) words[w] = 4294967295;
+      if (words.length > 0) words[words.length - 1] = lastWordMask;
+    },
     _words: words
   };
 }
 function createBitSet(size) {
-  return size <= 31 ? createIntBitSet() : createArrayBitSet(size);
+  return size <= 31 ? createIntBitSet(size) : createArrayBitSet(size);
 }
-var isNodeArray = (value) => Array.isArray(value);
-var isNodeOptions = (value) => typeof value === "object" && value != null && !Array.isArray(value);
-var isCleanupResult = (value) => typeof value === "object" && value !== null && CLEANUP_RESULT in value;
-var isCleanupFn = (value) => typeof value === "function";
-var statusAfterMessage = (status, msg) => {
-  const t = msg[0];
-  if (t === DIRTY) return "dirty";
-  if (t === DATA) return "settled";
-  if (t === RESOLVED) return "resolved";
-  if (t === COMPLETE) return "completed";
-  if (t === ERROR) return "errored";
-  if (t === INVALIDATE) return "dirty";
-  if (t === TEARDOWN) return "disconnected";
-  return status;
-};
-var NodeImpl = class {
-  // --- Configuration (set once, never reassigned) ---
+var NodeBase = class {
+  // --- Identity (set once) ---
   _optsName;
   _registryName;
-  /** @internal — read by {@link describeNode} before inference. */
+  /** @internal Read by `describeNode` before inference. */
   _describeKind;
   meta;
-  _deps;
-  _fn;
-  _opts;
+  // --- Options ---
   _equals;
+  _resubscribable;
+  _resetOnTeardown;
+  _onResubscribe;
   _onMessage;
-  /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
+  /** @internal Read by `describeNode` for `accessHintForGuard`. */
   _guard;
+  /** @internal Subclasses update this through {@link _recordMutation}. */
   _lastMutation;
-  _hasDeps;
-  _autoComplete;
-  _isSingleDep;
-  // --- Mutable state ---
+  // --- Versioning ---
+  _hashFn;
+  _versioning;
+  // --- Lifecycle state ---
+  /** @internal Read by `describeNode` and `graph.ts`. */
   _cached;
+  /** @internal Read externally via `get status()`. */
   _status;
   _terminal = false;
-  _connected = false;
-  _producerStarted = false;
-  _connecting = false;
-  _manualEmitUsed = false;
+  _active = false;
+  // --- Sink storage ---
+  /** @internal Read by `graph/profile.ts` for subscriber counts. */
   _sinkCount = 0;
   _singleDepSinkCount = 0;
-  // --- Object/collection state ---
-  _depDirtyMask;
-  _depSettledMask;
-  _depCompleteMask;
-  _allDepsCompleteMask;
-  _lastDepValues;
-  _cleanup;
-  _sinks = null;
   _singleDepSinks = /* @__PURE__ */ new WeakSet();
-  _upstreamUnsubs = [];
+  _sinks = null;
+  // --- Actions + bound helpers ---
   _actions;
   _boundDownToSinks;
+  // --- Inspector hook (Graph observability) ---
   _inspectorHook;
-  _versioning;
-  _hashFn;
-  constructor(deps, fn, opts) {
-    this._deps = deps;
-    this._fn = fn;
-    this._opts = opts;
+  constructor(opts) {
     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._onResubscribe = opts.onResubscribe;
     this._onMessage = opts.onMessage;
     this._guard = opts.guard;
-    this._hasDeps = deps.length > 0;
-    this._autoComplete = opts.completeWhenDepsComplete ?? true;
-    this._isSingleDep = deps.length === 1 && fn != null;
     this._cached = "initial" in opts ? opts.initial : NO_VALUE;
-    this._status = this._hasDeps ? "disconnected" : "settled";
+    this._status = "disconnected";
     this._hashFn = opts.versioningHash ?? defaultHash;
     this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached === NO_VALUE ? void 0 : this._cached, {
       id: opts.versioningId,
       hash: this._hashFn
     }) : void 0;
-    this._depDirtyMask = createBitSet(deps.length);
-    this._depSettledMask = createBitSet(deps.length);
-    this._depCompleteMask = createBitSet(deps.length);
-    this._allDepsCompleteMask = createBitSet(deps.length);
-    for (let i = 0; i < deps.length; i++) this._allDepsCompleteMask.set(i);
     const meta = {};
     for (const [k, v] of Object.entries(opts.meta ?? {})) {
-      meta[k] = node({
-        initial: v,
-        name: `${opts.name ?? "node"}:meta:${k}`,
-        describeKind: "state",
-        ...opts.guard != null ? { guard: opts.guard } : {}
-      });
+      meta[k] = this._createMetaNode(k, v, opts);
     }
     Object.freeze(meta);
     this.meta = meta;
     const self = this;
     this._actions = {
       down(messages) {
-        self._manualEmitUsed = true;
+        self._onManualEmit();
         self._downInternal(messages);
       },
       emit(value) {
-        self._manualEmitUsed = true;
+        self._onManualEmit();
         self._downAutoValue(value);
       },
       up(messages) {
         self._upInternal(messages);
       }
     };
-    this.down = this.down.bind(this);
-    this.up = this.up.bind(this);
     this._boundDownToSinks = this._downToSinks.bind(this);
   }
+  /**
+   * Subclass hook invoked by `actions.down` / `actions.emit`. Default no-op;
+   * {@link NodeImpl} overrides to set `_manualEmitUsed`.
+   */
+  _onManualEmit() {
+  }
+  // --- Identity getters ---
   get name() {
     return this._registryName ?? this._optsName;
   }
-  /**
-   * When a node is registered with {@link Graph.add} without an options `name`,
-   * the graph assigns the registry local name for introspection (parity with graphrefly-py).
-   */
+  /** @internal Assigned by `Graph.add` when registered without an options `name`. */
   _assignRegistryName(localName) {
     if (this._optsName !== void 0 || this._registryName !== void 0) return;
     this._registryName = localName;
@@ -841,7 +816,10 @@ var NodeImpl = class {
       }
     };
   }
-  // --- Public interface (Node<T>) ---
+  /** @internal Used by subclasses to surface inspector events. */
+  _emitInspectorHook(event) {
+    this._inspectorHook?.(event);
+  }
   get status() {
     return this._status;
   }
@@ -851,15 +829,7 @@ var NodeImpl = class {
   get v() {
     return this._versioning;
   }
-  /**
-   * Retroactively apply versioning to a node that was created without it.
-   * No-op if versioning is already enabled.
-   *
-   * Version starts at 0 regardless of prior DATA emissions — it tracks
-   * changes from the moment versioning is enabled, not historical ones.
-   *
-   * @internal — used by {@link Graph.setVersioning}.
-   */
+  /** @internal Used by `Graph.setVersioning` to retroactively apply versioning. */
   _applyVersioning(level, opts) {
     if (this._versioning != null) return;
     this._hashFn = opts?.hash ?? this._hashFn;
@@ -879,6 +849,7 @@ var NodeImpl = class {
     if (this._guard == null) return true;
     return this._guard(normalizeActor(actor), "observe");
   }
+  // --- Public transport ---
   get() {
     return this._cached === NO_VALUE ? void 0 : this._cached;
   }
@@ -891,43 +862,25 @@ var NodeImpl = class {
       if (!this._guard(actor, action)) {
         throw new GuardDenied({ actor, action, nodeName: this.name });
       }
-      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+      this._recordMutation(actor);
     }
     this._downInternal(messages);
   }
-  _downInternal(messages) {
-    if (messages.length === 0) return;
-    let lifecycleMessages = messages;
-    let sinkMessages = messages;
-    if (this._terminal && !this._opts.resubscribable) {
-      const terminalPassthrough = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
-      if (terminalPassthrough.length === 0) return;
-      lifecycleMessages = terminalPassthrough;
-      sinkMessages = terminalPassthrough;
-    }
-    this._handleLocalLifecycle(lifecycleMessages);
-    if (this._canSkipDirty()) {
-      let hasPhase2 = false;
-      for (let i = 0; i < sinkMessages.length; i++) {
-        const t = sinkMessages[i][0];
-        if (t === DATA || t === RESOLVED) {
-          hasPhase2 = true;
-          break;
-        }
-      }
-      if (hasPhase2) {
-        const filtered = [];
-        for (let i = 0; i < sinkMessages.length; i++) {
-          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
-        }
-        if (filtered.length > 0) {
-          downWithBatch(this._boundDownToSinks, filtered);
-        }
-        return;
-      }
-    }
-    downWithBatch(this._boundDownToSinks, sinkMessages);
+  /** @internal Record a successful guarded mutation (called by `down` and subclass `up`). */
+  _recordMutation(actor) {
+    this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+  }
+  /**
+   * At-most-once deactivation guard. Both TEARDOWN (eager) and
+   * unsubscribe-body (lazy) call this. The `_active` flag ensures
+   * `_doDeactivate` runs exactly once per activation cycle.
+   */
+  _onDeactivate() {
+    if (!this._active) return;
+    this._active = false;
+    this._doDeactivate();
   }
+  // --- Subscribe (uniform across node shapes) ---
   subscribe(sink, hints) {
     if (hints?.actor != null && this._guard != null) {
       const actor = normalizeActor(hints.actor);
@@ -935,17 +888,21 @@ var NodeImpl = class {
         throw new GuardDenied({ actor, action: "observe", nodeName: this.name });
       }
     }
-    if (this._terminal && this._opts.resubscribable) {
+    if (this._terminal && this._resubscribable) {
       this._terminal = false;
       this._cached = NO_VALUE;
-      this._status = this._hasDeps ? "disconnected" : "settled";
-      this._opts.onResubscribe?.();
+      this._status = "disconnected";
+      this._onResubscribe?.();
     }
     this._sinkCount += 1;
     if (hints?.singleDep) {
       this._singleDepSinkCount += 1;
       this._singleDepSinks.add(sink);
     }
+    if (!this._terminal) {
+      const startMessages = this._cached === NO_VALUE ? [[START]] : [[START], [DATA, this._cached]];
+      downWithBatch(sink, startMessages);
+    }
     if (this._sinks == null) {
       this._sinks = sink;
     } else if (typeof this._sinks === "function") {
@@ -953,10 +910,12 @@ var NodeImpl = class {
     } else {
       this._sinks.add(sink);
     }
-    if (this._hasDeps) {
-      this._connectUpstream();
-    } else if (this._fn) {
-      this._startProducer();
+    if (this._sinkCount === 1 && !this._terminal) {
+      this._active = true;
+      this._onActivate();
+    }
+    if (!this._terminal && this._status === "disconnected" && this._cached === NO_VALUE) {
+      this._status = "pending";
     }
     let removed = false;
     return () => {
@@ -980,39 +939,49 @@ var NodeImpl = class {
         }
       }
       if (this._sinks == null) {
-        this._disconnectUpstream();
-        this._stopProducer();
+        this._onDeactivate();
       }
     };
   }
-  up(messages, options) {
-    if (!this._hasDeps) return;
-    if (!options?.internal && this._guard != null) {
-      const actor = normalizeActor(options?.actor);
-      if (!this._guard(actor, "write")) {
-        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
-      }
-      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+  // --- Down pipeline ---
+  /**
+   * Core outgoing dispatch. Applies terminal filter + local lifecycle
+   * update, then hands messages to `downWithBatch` for tier-aware delivery.
+   */
+  _downInternal(messages) {
+    if (messages.length === 0) return;
+    let sinkMessages = messages;
+    if (this._terminal && !this._resubscribable) {
+      const pass = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
+      if (pass.length === 0) return;
+      sinkMessages = pass;
     }
-    for (const dep of this._deps) {
-      if (options === void 0) {
-        dep.up?.(messages);
-      } else {
-        dep.up?.(messages, options);
+    this._handleLocalLifecycle(sinkMessages);
+    if (this._canSkipDirty()) {
+      let hasPhase2 = false;
+      for (let i = 0; i < sinkMessages.length; i++) {
+        const t = sinkMessages[i][0];
+        if (t === DATA || t === RESOLVED) {
+          hasPhase2 = true;
+          break;
+        }
+      }
+      if (hasPhase2) {
+        const filtered = [];
+        for (let i = 0; i < sinkMessages.length; i++) {
+          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
+        }
+        if (filtered.length > 0) {
+          downWithBatch(this._boundDownToSinks, filtered);
+        }
+        return;
       }
     }
+    downWithBatch(this._boundDownToSinks, sinkMessages);
   }
-  _upInternal(messages) {
-    if (!this._hasDeps) return;
-    for (const dep of this._deps) {
-      dep.up?.(messages, { internal: true });
-    }
-  }
-  unsubscribe() {
-    if (!this._hasDeps) return;
-    this._disconnectUpstream();
+  _canSkipDirty() {
+    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
   }
-  // --- Private methods (prototype, _ prefix) ---
   _downToSinks(messages) {
     if (this._sinks == null) return;
     if (typeof this._sinks === "function") {
@@ -1024,6 +993,11 @@ var NodeImpl = class {
       sink(messages);
     }
   }
+  /**
+   * Update `_cached`, `_status`, `_terminal` from message batch before
+   * delivery. Subclass hooks `_onInvalidate` / `_onTeardown` let
+   * {@link NodeImpl} clear `_lastDepValues` and invoke cleanup fns.
+   */
   _handleLocalLifecycle(messages) {
     for (const m of messages) {
       const t = m[0];
@@ -1037,28 +1011,22 @@ var NodeImpl = class {
         }
       }
       if (t === INVALIDATE) {
-        const cleanupFn = this._cleanup;
-        this._cleanup = void 0;
-        cleanupFn?.();
+        this._onInvalidate();
         this._cached = NO_VALUE;
-        this._lastDepValues = void 0;
       }
       this._status = statusAfterMessage(this._status, m);
       if (t === COMPLETE || t === ERROR) {
         this._terminal = true;
       }
       if (t === TEARDOWN) {
-        if (this._opts.resetOnTeardown) {
+        if (this._resetOnTeardown) {
           this._cached = NO_VALUE;
         }
-        const teardownCleanup = this._cleanup;
-        this._cleanup = void 0;
-        teardownCleanup?.();
+        this._onTeardown();
         try {
           this._propagateToMeta(t);
         } finally {
-          this._disconnectUpstream();
-          this._stopProducer();
+          this._onDeactivate();
         }
       }
       if (t !== TEARDOWN && propagatesToMeta(t)) {
@@ -1066,7 +1034,20 @@ var NodeImpl = class {
       }
     }
   }
-  /** Propagate a signal to all companion meta nodes (best-effort). */
+  /**
+   * Subclass hook: invoked when INVALIDATE arrives (before `_cached` is
+   * cleared). {@link NodeImpl} uses this to run the fn cleanup fn and
+   * drop `_lastDepValues` so the next wave re-runs fn.
+   */
+  _onInvalidate() {
+  }
+  /**
+   * Subclass hook: invoked when TEARDOWN arrives, before `_onDeactivate`.
+   * {@link NodeImpl} uses this to run any pending cleanup fn.
+   */
+  _onTeardown() {
+  }
+  /** Forward a signal to all companion meta nodes (best-effort). */
   _propagateToMeta(t) {
     for (const metaNode of Object.values(this.meta)) {
       try {
@@ -1075,9 +1056,10 @@ var NodeImpl = class {
       }
     }
   }
-  _canSkipDirty() {
-    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
-  }
+  /**
+   * Frame a computed value into the right protocol messages and dispatch
+   * via `_downInternal`. Used by `_runFn` and `actions.emit`.
+   */
   _downAutoValue(value) {
     const wasDirty = this._status === "dirty";
     let unchanged;
@@ -1085,7 +1067,9 @@ var NodeImpl = class {
       unchanged = this._cached !== NO_VALUE && this._equals(this._cached, value);
     } catch (eqErr) {
       const eqMsg = eqErr instanceof Error ? eqErr.message : String(eqErr);
-      const wrapped = new Error(`Node "${this.name}": equals threw: ${eqMsg}`, { cause: eqErr });
+      const wrapped = new Error(`Node "${this.name}": equals threw: ${eqMsg}`, {
+        cause: eqErr
+      });
       this._downInternal([[ERROR, wrapped]]);
       return;
     }
@@ -1095,89 +1079,173 @@ var NodeImpl = class {
     }
     this._downInternal(wasDirty ? [[DATA, value]] : [[DIRTY], [DATA, value]]);
   }
-  _runFn() {
-    if (!this._fn) return;
-    if (this._terminal && !this._opts.resubscribable) return;
-    if (this._connecting) return;
-    try {
-      const n = this._deps.length;
-      const depValues = new Array(n);
-      for (let i = 0; i < n; i++) depValues[i] = this._deps[i].get();
-      const prev = this._lastDepValues;
-      if (n > 0 && prev != null && prev.length === n) {
-        let allSame = true;
-        for (let i = 0; i < n; i++) {
-          if (!Object.is(depValues[i], prev[i])) {
-            allSame = false;
-            break;
-          }
-        }
-        if (allSame) {
-          if (this._status === "dirty") {
-            this._downInternal([[RESOLVED]]);
-          }
-          return;
-        }
-      }
-      const prevCleanup = this._cleanup;
-      this._cleanup = void 0;
-      prevCleanup?.();
-      this._manualEmitUsed = false;
-      this._lastDepValues = depValues;
-      this._inspectorHook?.({ kind: "run", depValues });
-      const out = this._fn(depValues, this._actions);
-      if (isCleanupResult(out)) {
-        this._cleanup = out.cleanup;
-        if (this._manualEmitUsed) return;
-        if ("value" in out) {
-          this._downAutoValue(out.value);
-        }
-        return;
+};
+
+// src/core/node.ts
+var NodeImpl = class extends NodeBase {
+  // --- Dep configuration (set once) ---
+  _deps;
+  _fn;
+  _opts;
+  _hasDeps;
+  _isSingleDep;
+  _autoComplete;
+  // --- Wave tracking masks ---
+  _depDirtyMask;
+  _depSettledMask;
+  _depCompleteMask;
+  _allDepsCompleteMask;
+  // --- Identity-skip optimization ---
+  _lastDepValues;
+  _cleanup;
+  // --- Upstream bookkeeping ---
+  _upstreamUnsubs = [];
+  // --- Fn behavior flag ---
+  /** @internal Read by `describeNode` to infer `"operator"` label. */
+  _manualEmitUsed = false;
+  constructor(deps, fn, opts) {
+    super(opts);
+    this._deps = deps;
+    this._fn = fn;
+    this._opts = opts;
+    this._hasDeps = deps.length > 0;
+    this._isSingleDep = deps.length === 1 && fn != null;
+    this._autoComplete = opts.completeWhenDepsComplete ?? true;
+    if (!this._hasDeps && fn == null && this._cached !== NO_VALUE) {
+      this._status = "settled";
+    }
+    this._depDirtyMask = createBitSet(deps.length);
+    this._depSettledMask = createBitSet(deps.length);
+    this._depCompleteMask = createBitSet(deps.length);
+    this._allDepsCompleteMask = createBitSet(deps.length);
+    for (let i = 0; i < deps.length; i++) this._allDepsCompleteMask.set(i);
+    this.down = this.down.bind(this);
+    this.up = this.up.bind(this);
+  }
+  // --- Meta node factory (called from base constructor) ---
+  _createMetaNode(key, initialValue, opts) {
+    return node({
+      initial: initialValue,
+      name: `${opts.name ?? "node"}:meta:${key}`,
+      describeKind: "state",
+      ...opts.guard != null ? { guard: opts.guard } : {}
+    });
+  }
+  // --- Manual emit tracker (set by actions.down / actions.emit) ---
+  _onManualEmit() {
+    this._manualEmitUsed = true;
+  }
+  // --- Up / unsubscribe ---
+  up(messages, options) {
+    if (!this._hasDeps) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      if (!this._guard(actor, "write")) {
+        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
       }
-      if (isCleanupFn(out)) {
-        this._cleanup = out;
-        return;
+      this._recordMutation(actor);
+    }
+    for (const dep of this._deps) {
+      if (options === void 0) {
+        dep.up?.(messages);
+      } else {
+        dep.up?.(messages, options);
       }
-      if (this._manualEmitUsed) return;
-      if (out === void 0) return;
-      this._downAutoValue(out);
-    } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
-      const wrapped = new Error(`Node "${this.name}": fn threw: ${errMsg}`, { cause: err });
-      this._downInternal([[ERROR, wrapped]]);
     }
   }
-  _onDepDirty(index) {
-    const wasDirty = this._depDirtyMask.has(index);
-    this._depDirtyMask.set(index);
-    this._depSettledMask.clear(index);
-    if (!wasDirty) {
-      this._downInternal([[DIRTY]]);
+  _upInternal(messages) {
+    if (!this._hasDeps) return;
+    for (const dep of this._deps) {
+      dep.up?.(messages, { internal: true });
     }
   }
-  _onDepSettled(index) {
-    if (!this._depDirtyMask.has(index)) {
-      this._onDepDirty(index);
+  unsubscribe() {
+    if (!this._hasDeps) return;
+    this._disconnectUpstream();
+  }
+  // --- Activation (first-subscriber / last-subscriber hooks) ---
+  _onActivate() {
+    if (this._hasDeps) {
+      this._connectUpstream();
+      return;
     }
-    this._depSettledMask.set(index);
-    if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
-      this._depDirtyMask.reset();
-      this._depSettledMask.reset();
+    if (this._fn) {
       this._runFn();
+      return;
     }
   }
-  _maybeCompleteFromDeps() {
-    if (this._autoComplete && this._deps.length > 0 && this._depCompleteMask.covers(this._allDepsCompleteMask)) {
-      this._downInternal([[COMPLETE]]);
+  _doDeactivate() {
+    this._disconnectUpstream();
+    const cleanup = this._cleanup;
+    this._cleanup = void 0;
+    cleanup?.();
+    if (this._fn != null) {
+      this._cached = NO_VALUE;
+      this._lastDepValues = void 0;
     }
+    if (this._hasDeps || this._fn != null) {
+      this._status = "disconnected";
+    }
+  }
+  // --- INVALIDATE / TEARDOWN hooks (clear fn state) ---
+  _onInvalidate() {
+    const cleanup = this._cleanup;
+    this._cleanup = void 0;
+    cleanup?.();
+    this._lastDepValues = void 0;
+  }
+  _onTeardown() {
+    const cleanup = this._cleanup;
+    this._cleanup = void 0;
+    cleanup?.();
   }
+  // --- Upstream connect / disconnect ---
+  _connectUpstream() {
+    if (!this._hasDeps) return;
+    if (this._upstreamUnsubs.length > 0) return;
+    this._depDirtyMask.setAll();
+    this._depSettledMask.reset();
+    this._depCompleteMask.reset();
+    const depValuesBefore = this._lastDepValues;
+    const subHints = this._isSingleDep ? { singleDep: true } : void 0;
+    for (let i = 0; i < this._deps.length; i += 1) {
+      const dep = this._deps[i];
+      this._upstreamUnsubs.push(
+        dep.subscribe((msgs) => this._handleDepMessages(i, msgs), subHints)
+      );
+    }
+    if (this._fn && this._onMessage && !this._terminal && this._lastDepValues === depValuesBefore) {
+      this._runFn();
+    }
+  }
+  _disconnectUpstream() {
+    if (this._upstreamUnsubs.length === 0) return;
+    for (const unsub of this._upstreamUnsubs.splice(0)) {
+      unsub();
+    }
+    this._depDirtyMask.reset();
+    this._depSettledMask.reset();
+    this._depCompleteMask.reset();
+  }
+  // --- Wave handling ---
   _handleDepMessages(index, messages) {
     for (const msg of messages) {
-      this._inspectorHook?.({ kind: "dep_message", depIndex: index, message: msg });
+      this._emitInspectorHook({ kind: "dep_message", depIndex: index, message: msg });
       const t = msg[0];
       if (this._onMessage) {
         try {
-          if (this._onMessage(msg, index, this._actions)) continue;
+          const consumed = this._onMessage(msg, index, this._actions);
+          if (consumed) {
+            if (t === START) {
+              this._depDirtyMask.clear(index);
+              if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
+                this._depDirtyMask.reset();
+                this._depSettledMask.reset();
+                this._runFn();
+              }
+            }
+            continue;
+          }
         } catch (err) {
           const errMsg = err instanceof Error ? err.message : String(err);
           const wrapped = new Error(`Node "${this.name}": onMessage threw: ${errMsg}`, {
@@ -1187,6 +1255,7 @@ var NodeImpl = class {
           return;
         }
       }
+      if (messageTier(t) < 1) continue;
       if (!this._fn) {
         if (t === COMPLETE && this._deps.length > 1) {
           this._depCompleteMask.set(index);
@@ -1230,53 +1299,85 @@ var NodeImpl = class {
       this._downInternal([msg]);
     }
   }
-  _connectUpstream() {
-    if (!this._hasDeps || this._connected) return;
-    this._connected = true;
-    this._depDirtyMask.reset();
-    this._depSettledMask.reset();
-    this._depCompleteMask.reset();
-    this._status = "settled";
-    const subHints = this._isSingleDep ? { singleDep: true } : void 0;
-    this._connecting = true;
-    try {
-      for (let i = 0; i < this._deps.length; i += 1) {
-        const dep = this._deps[i];
-        this._upstreamUnsubs.push(
-          dep.subscribe((msgs) => this._handleDepMessages(i, msgs), subHints)
-        );
-      }
-    } finally {
-      this._connecting = false;
+  _onDepDirty(index) {
+    const wasDirty = this._depDirtyMask.has(index);
+    this._depDirtyMask.set(index);
+    this._depSettledMask.clear(index);
+    if (!wasDirty) {
+      this._downInternal([[DIRTY]]);
     }
-    if (this._fn) {
+  }
+  _onDepSettled(index) {
+    if (!this._depDirtyMask.has(index)) {
+      this._onDepDirty(index);
+    }
+    this._depSettledMask.set(index);
+    if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
+      this._depDirtyMask.reset();
+      this._depSettledMask.reset();
       this._runFn();
     }
   }
-  _stopProducer() {
-    if (!this._producerStarted) return;
-    this._producerStarted = false;
-    const producerCleanup = this._cleanup;
-    this._cleanup = void 0;
-    producerCleanup?.();
-  }
-  _startProducer() {
-    if (this._deps.length !== 0 || !this._fn || this._producerStarted) return;
-    this._producerStarted = true;
-    this._runFn();
+  _maybeCompleteFromDeps() {
+    if (this._autoComplete && this._deps.length > 0 && this._depCompleteMask.covers(this._allDepsCompleteMask)) {
+      this._downInternal([[COMPLETE]]);
+    }
   }
-  _disconnectUpstream() {
-    if (!this._connected) return;
-    for (const unsub of this._upstreamUnsubs.splice(0)) {
-      unsub();
+  // --- Fn execution ---
+  _runFn() {
+    if (!this._fn) return;
+    if (this._terminal && !this._resubscribable) return;
+    try {
+      const n = this._deps.length;
+      const depValues = new Array(n);
+      for (let i = 0; i < n; i++) depValues[i] = this._deps[i].get();
+      const prev = this._lastDepValues;
+      if (n > 0 && prev != null && prev.length === n) {
+        let allSame = true;
+        for (let i = 0; i < n; i++) {
+          if (!Object.is(depValues[i], prev[i])) {
+            allSame = false;
+            break;
+          }
+        }
+        if (allSame) {
+          if (this._status === "dirty") {
+            this._downInternal([[RESOLVED]]);
+          }
+          return;
+        }
+      }
+      const prevCleanup = this._cleanup;
+      this._cleanup = void 0;
+      prevCleanup?.();
+      this._manualEmitUsed = false;
+      this._lastDepValues = depValues;
+      this._emitInspectorHook({ kind: "run", depValues });
+      const out = this._fn(depValues, this._actions);
+      if (isCleanupResult(out)) {
+        this._cleanup = out.cleanup;
+        if (this._manualEmitUsed) return;
+        if ("value" in out) {
+          this._downAutoValue(out.value);
+        }
+        return;
+      }
+      if (isCleanupFn(out)) {
+        this._cleanup = out;
+        return;
+      }
+      if (this._manualEmitUsed) return;
+      if (out === void 0) return;
+      this._downAutoValue(out);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const wrapped = new Error(`Node "${this.name}": fn threw: ${errMsg}`, { cause: err });
+      this._downInternal([[ERROR, wrapped]]);
     }
-    this._connected = false;
-    this._depDirtyMask.reset();
-    this._depSettledMask.reset();
-    this._depCompleteMask.reset();
-    this._status = "disconnected";
   }
 };
+var isNodeArray = (value) => Array.isArray(value);
+var isNodeOptions = (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;
@@ -2125,449 +2226,272 @@ var import_common2 = require("@nestjs/common");
 var import_core2 = require("@nestjs/core");
 
 // src/core/dynamic-node.ts
-var DynamicNodeImpl = class {
-  _optsName;
-  _registryName;
-  _describeKind;
-  meta;
+var MAX_RERUN = 16;
+var DynamicNodeImpl = class extends NodeBase {
   _fn;
-  _equals;
-  _resubscribable;
-  _resetOnTeardown;
   _autoComplete;
-  _onMessage;
-  _onResubscribe;
-  /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
-  _guard;
-  _lastMutation;
-  _inspectorHook;
-  // Sink tracking
-  _sinkCount = 0;
-  _singleDepSinkCount = 0;
-  _singleDepSinks = /* @__PURE__ */ new WeakSet();
-  // Actions object (for onMessage handler)
-  _actions;
-  _boundDownToSinks;
-  // Mutable state
-  _cached = NO_VALUE;
-  _status = "disconnected";
-  _terminal = false;
-  _connected = false;
-  _rewiring = false;
-  // re-entrancy guard
   // Dynamic deps tracking
+  /** @internal Read by `describeNode`. */
   _deps = [];
   _depUnsubs = [];
   _depIndexMap = /* @__PURE__ */ new Map();
-  // node → index in _deps
-  _dirtyBits = /* @__PURE__ */ new Set();
-  _settledBits = /* @__PURE__ */ new Set();
-  _completeBits = /* @__PURE__ */ new Set();
-  // Sinks
-  _sinks = null;
+  _depDirtyBits = /* @__PURE__ */ new Set();
+  _depSettledBits = /* @__PURE__ */ new Set();
+  _depCompleteBits = /* @__PURE__ */ new Set();
+  // Execution state
+  _running = false;
+  _rewiring = false;
+  _bufferedDepMessages = [];
+  _trackedValues = /* @__PURE__ */ new Map();
+  _rerunCount = 0;
   constructor(fn, opts) {
+    super(opts);
     this._fn = fn;
-    this._optsName = opts.name;
-    this._describeKind = opts.describeKind;
-    this._equals = opts.equals ?? Object.is;
-    this._resubscribable = opts.resubscribable ?? false;
-    this._resetOnTeardown = opts.resetOnTeardown ?? false;
     this._autoComplete = opts.completeWhenDepsComplete ?? true;
-    this._onMessage = opts.onMessage;
-    this._onResubscribe = opts.onResubscribe;
-    this._guard = opts.guard;
-    this._inspectorHook = void 0;
-    const meta = {};
-    for (const [k, v] of Object.entries(opts.meta ?? {})) {
-      meta[k] = node({
-        initial: v,
-        name: `${opts.name ?? "dynamicNode"}:meta:${k}`,
-        describeKind: "state",
-        ...opts.guard != null ? { guard: opts.guard } : {}
-      });
-    }
-    Object.freeze(meta);
-    this.meta = meta;
-    const self = this;
-    this._actions = {
-      down(messages) {
-        self._downInternal(messages);
-      },
-      emit(value) {
-        self._downAutoValue(value);
-      },
-      up(messages) {
-        for (const dep of self._deps) {
-          dep.up?.(messages, { internal: true });
-        }
-      }
-    };
-    this._boundDownToSinks = this._downToSinks.bind(this);
-  }
-  get name() {
-    return this._registryName ?? this._optsName;
-  }
-  /** @internal */
-  _assignRegistryName(localName) {
-    if (this._optsName !== void 0 || this._registryName !== void 0) return;
-    this._registryName = localName;
-  }
-  /**
-   * @internal Attach/remove inspector hook for graph-level observability.
-   * Returns a disposer that restores the previous hook.
-   */
-  _setInspectorHook(hook) {
-    const prev = this._inspectorHook;
-    this._inspectorHook = hook;
-    return () => {
-      if (this._inspectorHook === hook) {
-        this._inspectorHook = prev;
-      }
-    };
-  }
-  get status() {
-    return this._status;
-  }
-  get lastMutation() {
-    return this._lastMutation;
-  }
-  /** Versioning not yet supported on DynamicNodeImpl. */
-  get v() {
-    return void 0;
-  }
-  hasGuard() {
-    return this._guard != null;
-  }
-  allowsObserve(actor) {
-    if (this._guard == null) return true;
-    return this._guard(normalizeActor(actor), "observe");
-  }
-  get() {
-    return this._cached === NO_VALUE ? void 0 : this._cached;
-  }
-  down(messages, options) {
-    if (messages.length === 0) return;
-    if (!options?.internal && this._guard != null) {
-      const actor = normalizeActor(options?.actor);
-      const delivery = options?.delivery ?? "write";
-      const action = delivery === "signal" ? "signal" : "write";
-      if (!this._guard(actor, action)) {
-        throw new GuardDenied({ actor, action, nodeName: this.name });
-      }
-      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
-    }
-    this._downInternal(messages);
-  }
-  _downInternal(messages) {
-    if (messages.length === 0) return;
-    let sinkMessages = messages;
-    if (this._terminal && !this._resubscribable) {
-      const pass = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
-      if (pass.length === 0) return;
-      sinkMessages = pass;
-    }
-    this._handleLocalLifecycle(sinkMessages);
-    if (this._canSkipDirty()) {
-      let hasPhase2 = false;
-      for (let i = 0; i < sinkMessages.length; i++) {
-        const t = sinkMessages[i][0];
-        if (t === DATA || t === RESOLVED) {
-          hasPhase2 = true;
-          break;
-        }
-      }
-      if (hasPhase2) {
-        const filtered = [];
-        for (let i = 0; i < sinkMessages.length; i++) {
-          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
-        }
-        if (filtered.length > 0) {
-          downWithBatch(this._boundDownToSinks, filtered);
-        }
-        return;
-      }
-    }
-    downWithBatch(this._boundDownToSinks, sinkMessages);
-  }
-  _canSkipDirty() {
-    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
-  }
-  subscribe(sink, hints) {
-    if (hints?.actor != null && this._guard != null) {
-      const actor = normalizeActor(hints.actor);
-      if (!this._guard(actor, "observe")) {
-        throw new GuardDenied({ actor, action: "observe", nodeName: this.name });
-      }
-    }
-    if (this._terminal && this._resubscribable) {
-      this._terminal = false;
-      this._cached = NO_VALUE;
-      this._status = "disconnected";
-      this._onResubscribe?.();
-    }
-    this._sinkCount += 1;
-    if (hints?.singleDep) {
-      this._singleDepSinkCount += 1;
-      this._singleDepSinks.add(sink);
-    }
-    if (this._sinks == null) {
-      this._sinks = sink;
-    } else if (typeof this._sinks === "function") {
-      this._sinks = /* @__PURE__ */ new Set([this._sinks, sink]);
-    } else {
-      this._sinks.add(sink);
-    }
-    if (!this._connected) {
-      this._connect();
-    }
-    let removed = false;
-    return () => {
-      if (removed) return;
-      removed = true;
-      this._sinkCount -= 1;
-      if (this._singleDepSinks.has(sink)) {
-        this._singleDepSinkCount -= 1;
-        this._singleDepSinks.delete(sink);
-      }
-      if (this._sinks == null) return;
-      if (typeof this._sinks === "function") {
-        if (this._sinks === sink) this._sinks = null;
-      } else {
-        this._sinks.delete(sink);
-        if (this._sinks.size === 1) {
-          const [only] = this._sinks;
-          this._sinks = only;
-        } else if (this._sinks.size === 0) {
-          this._sinks = null;
-        }
-      }
-      if (this._sinks == null) {
-        this._disconnect();
-      }
-    };
-  }
-  up(messages, options) {
-    if (this._deps.length === 0) return;
-    if (!options?.internal && this._guard != null) {
-      const actor = normalizeActor(options?.actor);
-      if (!this._guard(actor, "write")) {
-        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
-      }
-      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
-    }
-    for (const dep of this._deps) {
-      dep.up?.(messages, options);
-    }
-  }
-  unsubscribe() {
-    this._disconnect();
-  }
-  // --- Private methods ---
-  _downToSinks(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);
-    }
+    this.down = this.down.bind(this);
+    this.up = this.up.bind(this);
   }
-  _handleLocalLifecycle(messages) {
-    for (const m of messages) {
-      const t = m[0];
-      if (t === DATA) this._cached = m[1];
-      if (t === INVALIDATE) {
-        this._cached = NO_VALUE;
-        this._status = "dirty";
-      }
-      if (t === DATA) {
-        this._status = "settled";
-      } else if (t === RESOLVED) {
-        this._status = "resolved";
-      } else if (t === DIRTY) {
-        this._status = "dirty";
-      } else if (t === COMPLETE) {
-        this._status = "completed";
-        this._terminal = true;
-      } else if (t === ERROR) {
-        this._status = "errored";
-        this._terminal = true;
-      }
-      if (t === TEARDOWN) {
-        if (this._resetOnTeardown) this._cached = NO_VALUE;
-        try {
-          this._propagateToMeta(t);
-        } finally {
-          this._disconnect();
-        }
-      }
-      if (t !== TEARDOWN && propagatesToMeta(t)) {
-        this._propagateToMeta(t);
-      }
-    }
+  _createMetaNode(key, initialValue, opts) {
+    return node({
+      initial: initialValue,
+      name: `${opts.name ?? "dynamicNode"}:meta:${key}`,
+      describeKind: "state",
+      ...opts.guard != null ? { guard: opts.guard } : {}
+    });
   }
-  /** Propagate a signal to all companion meta nodes (best-effort). */
-  _propagateToMeta(t) {
-    for (const metaNode of Object.values(this.meta)) {
-      try {
-        metaNode.down([[t]], { internal: true });
-      } catch {
+  /** Versioning not supported on DynamicNodeImpl (override base). */
+  get v() {
+    return void 0;
+  }
+  // --- Up / unsubscribe ---
+  up(messages, options) {
+    if (this._deps.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      if (!this._guard(actor, "write")) {
+        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
       }
+      this._recordMutation(actor);
     }
-  }
-  _downAutoValue(value) {
-    const wasDirty = this._status === "dirty";
-    let unchanged;
-    try {
-      unchanged = this._cached !== NO_VALUE && this._equals(this._cached, value);
-    } catch (eqErr) {
-      const eqMsg = eqErr instanceof Error ? eqErr.message : String(eqErr);
-      const wrapped = new Error(`Node "${this.name}": equals threw: ${eqMsg}`, { cause: eqErr });
-      this._downInternal([[ERROR, wrapped]]);
-      return;
+    for (const dep of this._deps) {
+      dep.up?.(messages, options);
     }
-    if (unchanged) {
-      this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
-      return;
+  }
+  _upInternal(messages) {
+    for (const dep of this._deps) {
+      dep.up?.(messages, { internal: true });
     }
-    this._cached = value;
-    this._downInternal(wasDirty ? [[DATA, value]] : [[DIRTY], [DATA, value]]);
   }
-  _connect() {
-    if (this._connected) return;
-    this._connected = true;
-    this._status = "settled";
-    this._dirtyBits.clear();
-    this._settledBits.clear();
-    this._completeBits.clear();
+  unsubscribe() {
+    this._disconnect();
+  }
+  // --- Activation hooks ---
+  _onActivate() {
     this._runFn();
   }
+  _doDeactivate() {
+    this._disconnect();
+  }
   _disconnect() {
-    if (!this._connected) return;
     for (const unsub of this._depUnsubs) unsub();
     this._depUnsubs = [];
     this._deps = [];
     this._depIndexMap.clear();
-    this._dirtyBits.clear();
-    this._settledBits.clear();
-    this._completeBits.clear();
-    this._connected = false;
+    this._depDirtyBits.clear();
+    this._depSettledBits.clear();
+    this._depCompleteBits.clear();
+    this._cached = NO_VALUE;
     this._status = "disconnected";
   }
+  // --- Fn execution with rewire buffer ---
   _runFn() {
     if (this._terminal && !this._resubscribable) return;
-    if (this._rewiring) return;
-    const trackedDeps = [];
-    const trackedSet = /* @__PURE__ */ new Set();
-    const get = (dep) => {
-      if (!trackedSet.has(dep)) {
-        trackedSet.add(dep);
-        trackedDeps.push(dep);
-      }
-      return dep.get();
-    };
+    if (this._running) return;
+    this._running = true;
+    this._rerunCount = 0;
+    let result;
     try {
-      const depValues = [];
-      for (const dep of this._deps) {
-        depValues.push(dep.get());
-      }
-      this._inspectorHook?.({ kind: "run", depValues });
-      const result = this._fn(get);
-      this._rewire(trackedDeps);
-      if (result === void 0) return;
-      this._downAutoValue(result);
-    } catch (err) {
-      this._downInternal([[ERROR, err]]);
+      for (; ; ) {
+        const trackedDeps = [];
+        const trackedValuesMap = /* @__PURE__ */ new Map();
+        const trackedSet = /* @__PURE__ */ new Set();
+        const get = (dep) => {
+          if (!trackedSet.has(dep)) {
+            trackedSet.add(dep);
+            trackedDeps.push(dep);
+            trackedValuesMap.set(dep, dep.get());
+          }
+          return dep.get();
+        };
+        this._trackedValues = trackedValuesMap;
+        const depValues = [];
+        for (const dep of this._deps) depValues.push(dep.get());
+        this._emitInspectorHook({ kind: "run", depValues });
+        try {
+          result = this._fn(get);
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const wrapped = new Error(`Node "${this.name}": fn threw: ${errMsg}`, {
+            cause: err
+          });
+          this._downInternal([[ERROR, wrapped]]);
+          return;
+        }
+        this._rewiring = true;
+        this._bufferedDepMessages = [];
+        try {
+          this._rewire(trackedDeps);
+        } finally {
+          this._rewiring = false;
+        }
+        let needsRerun = false;
+        for (const entry of this._bufferedDepMessages) {
+          for (const msg of entry.msgs) {
+            if (msg[0] === DATA) {
+              const dep = this._deps[entry.index];
+              const trackedValue = dep != null ? this._trackedValues.get(dep) : void 0;
+              const actualValue = msg[1];
+              if (!this._equals(trackedValue, actualValue)) {
+                needsRerun = true;
+                break;
+              }
+            }
+          }
+          if (needsRerun) break;
+        }
+        if (needsRerun) {
+          this._rerunCount += 1;
+          if (this._rerunCount > MAX_RERUN) {
+            this._bufferedDepMessages = [];
+            this._downInternal([
+              [
+                ERROR,
+                new Error(
+                  `dynamicNode "${this.name ?? "anonymous"}": rewire did not stabilize within ${MAX_RERUN} iterations`
+                )
+              ]
+            ]);
+            return;
+          }
+          this._bufferedDepMessages = [];
+          continue;
+        }
+        const drain = this._bufferedDepMessages;
+        this._bufferedDepMessages = [];
+        for (const entry of drain) {
+          for (const msg of entry.msgs) {
+            this._updateMasksForMessage(entry.index, msg);
+          }
+        }
+        this._depDirtyBits.clear();
+        this._depSettledBits.clear();
+        break;
+      }
+    } finally {
+      this._running = false;
     }
+    this._downAutoValue(result);
   }
   _rewire(newDeps) {
-    this._rewiring = true;
-    try {
-      const oldMap = this._depIndexMap;
-      const newMap = /* @__PURE__ */ new Map();
-      const newUnsubs = [];
-      for (let i = 0; i < newDeps.length; i++) {
-        const dep = newDeps[i];
-        newMap.set(dep, i);
-        const oldIdx = oldMap.get(dep);
-        if (oldIdx !== void 0) {
-          newUnsubs.push(this._depUnsubs[oldIdx]);
-          this._depUnsubs[oldIdx] = () => {
-          };
-        } else {
-          const idx = i;
-          const unsub = dep.subscribe((msgs) => this._handleDepMessages(idx, msgs));
-          newUnsubs.push(unsub);
-        }
+    const oldMap = this._depIndexMap;
+    const newMap = /* @__PURE__ */ new Map();
+    const newUnsubs = [];
+    for (let i = 0; i < newDeps.length; i++) {
+      const dep = newDeps[i];
+      newMap.set(dep, i);
+      const oldIdx = oldMap.get(dep);
+      if (oldIdx !== void 0) {
+        newUnsubs.push(this._depUnsubs[oldIdx]);
+        this._depUnsubs[oldIdx] = () => {
+        };
+      } else {
+        const idx = i;
+        const unsub = dep.subscribe((msgs) => this._handleDepMessages(idx, msgs));
+        newUnsubs.push(unsub);
       }
-      for (const [dep, oldIdx] of oldMap) {
-        if (!newMap.has(dep)) {
-          this._depUnsubs[oldIdx]();
-        }
+    }
+    for (const [dep, oldIdx] of oldMap) {
+      if (!newMap.has(dep)) {
+        this._depUnsubs[oldIdx]();
       }
-      this._deps = newDeps;
-      this._depUnsubs = newUnsubs;
-      this._depIndexMap = newMap;
-      this._dirtyBits.clear();
-      this._settledBits.clear();
-      const newCompleteBits = /* @__PURE__ */ new Set();
-      for (const oldIdx of this._completeBits) {
-        const dep = [...oldMap.entries()].find(([, idx]) => idx === oldIdx)?.[0];
-        if (dep && newMap.has(dep)) {
+    }
+    this._deps = newDeps;
+    this._depUnsubs = newUnsubs;
+    this._depIndexMap = newMap;
+    this._depDirtyBits.clear();
+    this._depSettledBits.clear();
+    const newCompleteBits = /* @__PURE__ */ new Set();
+    for (const oldIdx of this._depCompleteBits) {
+      for (const [dep, idx] of oldMap) {
+        if (idx === oldIdx && newMap.has(dep)) {
           newCompleteBits.add(newMap.get(dep));
+          break;
         }
       }
-      this._completeBits = newCompleteBits;
-    } finally {
-      this._rewiring = false;
     }
+    this._depCompleteBits = newCompleteBits;
   }
+  // --- Dep message handling ---
   _handleDepMessages(index, messages) {
-    if (this._rewiring) return;
+    if (this._rewiring) {
+      this._bufferedDepMessages.push({ index, msgs: messages });
+      return;
+    }
     for (const msg of messages) {
-      this._inspectorHook?.({ kind: "dep_message", depIndex: index, message: msg });
+      this._emitInspectorHook({ kind: "dep_message", depIndex: index, message: msg });
       const t = msg[0];
       if (this._onMessage) {
         try {
           if (this._onMessage(msg, index, this._actions)) continue;
         } catch (err) {
-          this._downInternal([[ERROR, err]]);
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const wrapped = new Error(`Node "${this.name}": onMessage threw: ${errMsg}`, {
+            cause: err
+          });
+          this._downInternal([[ERROR, wrapped]]);
           return;
         }
       }
+      if (messageTier(t) < 1) continue;
       if (t === DIRTY) {
-        this._dirtyBits.add(index);
-        this._settledBits.delete(index);
-        if (this._dirtyBits.size === 1) {
-          downWithBatch(this._boundDownToSinks, [[DIRTY]]);
+        const wasEmpty = this._depDirtyBits.size === 0;
+        this._depDirtyBits.add(index);
+        this._depSettledBits.delete(index);
+        if (wasEmpty) {
+          this._downInternal([[DIRTY]]);
         }
         continue;
       }
       if (t === DATA || t === RESOLVED) {
-        if (!this._dirtyBits.has(index)) {
-          this._dirtyBits.add(index);
-          downWithBatch(this._boundDownToSinks, [[DIRTY]]);
+        if (!this._depDirtyBits.has(index)) {
+          const wasEmpty = this._depDirtyBits.size === 0;
+          this._depDirtyBits.add(index);
+          if (wasEmpty) {
+            this._downInternal([[DIRTY]]);
+          }
         }
-        this._settledBits.add(index);
+        this._depSettledBits.add(index);
         if (this._allDirtySettled()) {
-          this._dirtyBits.clear();
-          this._settledBits.clear();
-          this._runFn();
+          this._depDirtyBits.clear();
+          this._depSettledBits.clear();
+          if (!this._running) {
+            if (this._depValuesDifferFromTracked()) {
+              this._runFn();
+            }
+          }
         }
         continue;
       }
       if (t === COMPLETE) {
-        this._completeBits.add(index);
-        this._dirtyBits.delete(index);
-        this._settledBits.delete(index);
+        this._depCompleteBits.add(index);
+        this._depDirtyBits.delete(index);
+        this._depSettledBits.delete(index);
         if (this._allDirtySettled()) {
-          this._dirtyBits.clear();
-          this._settledBits.clear();
-          this._runFn();
+          this._depDirtyBits.clear();
+          this._depSettledBits.clear();
+          if (!this._running) this._runFn();
         }
-        if (this._autoComplete && this._completeBits.size >= this._deps.length && this._deps.length > 0) {
+        if (this._autoComplete && this._depCompleteBits.size >= this._deps.length && this._deps.length > 0) {
           this._downInternal([[COMPLETE]]);
         }
         continue;
@@ -2583,13 +2507,46 @@ var DynamicNodeImpl = class {
       this._downInternal([msg]);
     }
   }
+  /**
+   * Update dep masks for a message without triggering `_runFn` — used
+   * during post-rewire drain so the wave state is consistent with the
+   * buffered activation cascade without recursing.
+   */
+  _updateMasksForMessage(index, msg) {
+    const t = msg[0];
+    if (t === DIRTY) {
+      this._depDirtyBits.add(index);
+      this._depSettledBits.delete(index);
+    } else if (t === DATA || t === RESOLVED) {
+      this._depDirtyBits.add(index);
+      this._depSettledBits.add(index);
+    } else if (t === COMPLETE) {
+      this._depCompleteBits.add(index);
+      this._depDirtyBits.delete(index);
+      this._depSettledBits.delete(index);
+    }
+  }
   _allDirtySettled() {
-    if (this._dirtyBits.size === 0) return false;
-    for (const idx of this._dirtyBits) {
-      if (!this._settledBits.has(idx)) return false;
+    if (this._depDirtyBits.size === 0) return false;
+    for (const idx of this._depDirtyBits) {
+      if (!this._depSettledBits.has(idx)) return false;
     }
     return true;
   }
+  /**
+   * True if any current dep value differs from what the last `_runFn`
+   * saw via `get()`. Used to suppress redundant re-runs when deferred
+   * handshake messages arrive after `_rewire` for a dep whose value
+   * already matches `_trackedValues`.
+   */
+  _depValuesDifferFromTracked() {
+    for (const dep of this._deps) {
+      const current = dep.get();
+      const tracked = this._trackedValues.get(dep);
+      if (!this._equals(current, tracked)) return true;
+    }
+    return false;
+  }
 };
 
 // src/core/meta.ts
@@ -2659,6 +2616,10 @@ function describeNode(node2, includeFields) {
     out.name = node2.name;
   }
   if (all || includeFields.has("value")) {
+    const isSentinel = node2 instanceof NodeImpl && node2._cached === NO_VALUE || node2 instanceof DynamicNodeImpl && node2._cached === NO_VALUE;
+    if (isSentinel) {
+      out.sentinel = true;
+    }
     try {
       out.value = node2.get();
     } catch {
@@ -2685,6 +2646,129 @@ function describeNode(node2, includeFields) {
   return out;
 }
 
+// src/graph/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,
+  function: 120,
+  map: 72,
+  set: 72,
+  mapEntry: 40,
+  setEntry: 24
+};
+function sizeof(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return _sizeof(value, seen);
+}
+function _sizeof(value, seen) {
+  if (value == null) 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;
+    // UTF-16
+    case "bigint":
+      return OVERHEAD.bigint;
+    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);
+  if (obj instanceof Map) {
+    let size2 = OVERHEAD.map;
+    for (const [k, v] of obj) {
+      size2 += OVERHEAD.mapEntry + _sizeof(k, seen) + _sizeof(v, seen);
+    }
+    return size2;
+  }
+  if (obj instanceof Set) {
+    let size2 = OVERHEAD.set;
+    for (const v of obj) {
+      size2 += OVERHEAD.setEntry + _sizeof(v, seen);
+    }
+    return size2;
+  }
+  if (Array.isArray(obj)) {
+    let size2 = OVERHEAD.array + obj.length * 8;
+    for (const item of obj) {
+      size2 += _sizeof(item, seen);
+    }
+    return size2;
+  }
+  if (obj instanceof ArrayBuffer) return obj.byteLength;
+  if (ArrayBuffer.isView(obj)) return obj.byteLength;
+  let size = OVERHEAD.object;
+  const keys = Object.keys(obj);
+  for (const key of keys) {
+    size += OVERHEAD.string + key.length * 2;
+    size += _sizeof(obj[key], seen);
+  }
+  return size;
+}
+
+// src/graph/profile.ts
+function graphProfile(graph, opts) {
+  const topN = opts?.topN ?? 10;
+  const desc = graph.describe({ detail: "standard" });
+  const targets = [];
+  if (typeof graph._collectObserveTargets === "function") {
+    graph._collectObserveTargets("", 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.get()) : 0;
+    const subscriberCount = impl ? impl._sinkCount : 0;
+    const depCount = nodeDesc.deps?.length ?? 0;
+    const isOrphanEffect = nodeDesc.type === "effect" && subscriberCount === 0;
+    profiles.push({
+      path,
+      type: nodeDesc.type,
+      status: nodeDesc.status ?? "unknown",
+      valueSizeBytes,
+      subscriberCount,
+      depCount,
+      isOrphanEffect
+    });
+  }
+  const totalValueSizeBytes = profiles.reduce((sum, p) => sum + p.valueSizeBytes, 0);
+  const hotspots = [...profiles].sort((a, b) => b.valueSizeBytes - a.valueSizeBytes).slice(0, topN);
+  const orphanEffects = profiles.filter((p) => p.isOrphanEffect);
+  return {
+    nodeCount: profiles.length,
+    edgeCount: desc.edges.length,
+    subgraphCount: desc.subgraphs.length,
+    nodes: profiles,
+    totalValueSizeBytes,
+    hotspots,
+    orphanEffects
+  };
+}
+
 // src/graph/graph.ts
 var PATH_SEP = "::";
 var GRAPH_META_SEGMENT = "__meta__";
@@ -2827,7 +2911,7 @@ var RingBuffer = class {
     return result;
   }
 };
-var SPY_ANSI_THEME = {
+var OBSERVE_ANSI_THEME = {
   data: "\x1B[32m",
   dirty: "\x1B[33m",
   resolved: "\x1B[36m",
@@ -2837,7 +2921,7 @@ var SPY_ANSI_THEME = {
   path: "\x1B[90m",
   reset: "\x1B[0m"
 };
-var SPY_NO_COLOR_THEME = {
+var OBSERVE_NO_COLOR_THEME = {
   data: "",
   dirty: "",
   resolved: "",
@@ -2857,9 +2941,9 @@ function describeData(value) {
     return "[unserializable]";
   }
 }
-function resolveSpyTheme(theme) {
-  if (theme === "none") return SPY_NO_COLOR_THEME;
-  if (theme === "ansi" || theme == null) return SPY_ANSI_THEME;
+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 ?? "",
@@ -3597,6 +3681,16 @@ var Graph = class _Graph {
     }
     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);
+  }
   _qualifyEdgeEndpoint(part, prefix) {
     if (part.includes(PATH_SEP)) return part;
     return prefix === "" ? part : `${prefix}${PATH_SEP}${part}`;
@@ -3630,9 +3724,13 @@ var Graph = class _Graph {
       if (actor2 != null && !target.allowsObserve(actor2)) {
         throw new GuardDenied({ actor: actor2, action: "observe", nodeName: path });
       }
-      const wantsStructured2 = resolved.structured === true || resolved.timeline === true || resolved.causal === true || resolved.derived === true || resolved.detail === "minimal" || resolved.detail === "full";
-      if (wantsStructured2 && _Graph.inspectorEnabled) {
-        return this._createObserveResult(path, target, resolved);
+      const wantsStructured2 = resolved.structured === true || resolved.timeline === true || resolved.causal === true || resolved.derived === true || resolved.detail === "minimal" || resolved.detail === "full" || resolved.format != null;
+      if (wantsStructured2) {
+        const result = _Graph.inspectorEnabled ? this._createObserveResult(path, target, resolved) : this._createFallbackObserveResult(path, resolved);
+        if (resolved.format != null) {
+          this._attachFormatLogger(result, resolved);
+        }
+        return result;
       }
       return {
         subscribe(sink) {
@@ -3650,9 +3748,13 @@ var Graph = class _Graph {
     }
     const opts = resolveObserveDetail(pathOrOpts);
     const actor = opts.actor;
-    const wantsStructured = opts.structured === true || opts.timeline === true || opts.causal === true || opts.derived === true || opts.detail === "minimal" || opts.detail === "full";
-    if (wantsStructured && _Graph.inspectorEnabled) {
-      return this._createObserveResultForAll(opts);
+    const wantsStructured = opts.structured === true || opts.timeline === true || opts.causal === true || opts.derived === true || opts.detail === "minimal" || opts.detail === "full" || opts.format != null;
+    if (wantsStructured) {
+      const result = _Graph.inspectorEnabled ? this._createObserveResultForAll(opts) : this._createFallbackObserveResultForAll(opts);
+      if (opts.format != null) {
+        this._attachFormatLogger(result, opts);
+      }
+      return result;
     }
     return {
       subscribe: (sink) => {
@@ -3690,12 +3792,13 @@ var Graph = class _Graph {
       dirtyCount: 0,
       resolvedCount: 0,
       events: [],
-      completedCleanly: false,
-      errored: false
+      anyCompletedCleanly: false,
+      anyErrored: false
     };
     let lastTriggerDepIndex;
     let lastRunDepValues;
     let detachInspectorHook;
+    let batchSeq = 0;
     if ((causal || derived2) && target instanceof NodeImpl) {
       detachInspectorHook = target._setInspectorHook((event) => {
         if (event.kind === "dep_message") {
@@ -3708,15 +3811,16 @@ var Graph = class _Graph {
             type: "derived",
             path,
             dep_values: [...event.depValues],
-            ...timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {}
+            ...timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching(), batch_id: batchSeq } : {}
           });
         }
       });
     }
     const unsub = target.subscribe((msgs) => {
+      batchSeq++;
       for (const m of msgs) {
         const t = m[0];
-        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching(), batch_id: batchSeq } : {};
         const withCausal = causal && lastRunDepValues != null ? (() => {
           const triggerDep = lastTriggerDepIndex != null && lastTriggerDepIndex >= 0 && target instanceof NodeImpl ? target._deps[lastTriggerDepIndex] : void 0;
           const tv = triggerDep?.v;
@@ -3733,8 +3837,8 @@ var Graph = class _Graph {
         } else if (minimal) {
           if (t === DIRTY) result.dirtyCount++;
           else if (t === RESOLVED) result.resolvedCount++;
-          else if (t === COMPLETE && !result.errored) result.completedCleanly = true;
-          else if (t === ERROR) result.errored = true;
+          else if (t === COMPLETE && !result.anyErrored) result.anyCompletedCleanly = true;
+          else if (t === ERROR) result.anyErrored = true;
         } else if (t === DIRTY) {
           result.dirtyCount++;
           result.events.push({ type: "dirty", path, ...base });
@@ -3742,10 +3846,10 @@ var Graph = class _Graph {
           result.resolvedCount++;
           result.events.push({ type: "resolved", path, ...base, ...withCausal });
         } else if (t === COMPLETE) {
-          if (!result.errored) result.completedCleanly = true;
+          if (!result.anyErrored) result.anyCompletedCleanly = true;
           result.events.push({ type: "complete", path, ...base });
         } else if (t === ERROR) {
-          result.errored = true;
+          result.anyErrored = true;
           result.events.push({ type: "error", path, data: m[1], ...base });
         }
       }
@@ -3765,11 +3869,14 @@ var Graph = class _Graph {
       get events() {
         return result.events;
       },
-      get completedCleanly() {
-        return result.completedCleanly;
+      get anyCompletedCleanly() {
+        return result.anyCompletedCleanly;
+      },
+      get anyErrored() {
+        return result.anyErrored;
       },
-      get errored() {
-        return result.errored;
+      get completedWithoutErrors() {
+        return result.anyCompletedCleanly && !result.anyErrored;
       },
       dispose() {
         unsub();
@@ -3785,11 +3892,15 @@ var Graph = class _Graph {
           Object.assign(merged, extra);
         }
         const resolvedTarget = graph.resolve(basePath);
-        return graph._createObserveResult(
+        const expanded = graph._createObserveResult(
           basePath,
           resolvedTarget,
           resolveObserveDetail(merged)
         );
+        if (merged.format != null) {
+          graph._attachFormatLogger(expanded, merged);
+        }
+        return expanded;
       }
     };
   }
@@ -3801,27 +3912,33 @@ var Graph = class _Graph {
       dirtyCount: 0,
       resolvedCount: 0,
       events: [],
-      completedCleanly: false,
-      errored: false
+      anyCompletedCleanly: false,
+      anyErrored: false
     };
+    const nodeErrored = /* @__PURE__ */ new Set();
     const actor = options.actor;
     const targets = [];
     this._collectObserveTargets("", targets);
     targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
     const picked = actor == null ? targets : targets.filter(([, nd]) => nd.allowsObserve(actor));
+    let batchSeq = 0;
     const unsubs = picked.map(
       ([path, nd]) => nd.subscribe((msgs) => {
+        batchSeq++;
         for (const m of msgs) {
           const t = m[0];
-          const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+          const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching(), batch_id: batchSeq } : {};
           if (t === DATA) {
             result.values[path] = m[1];
             result.events.push({ type: "data", path, data: m[1], ...base });
           } else if (minimal) {
             if (t === DIRTY) result.dirtyCount++;
             else if (t === RESOLVED) result.resolvedCount++;
-            else if (t === COMPLETE && !result.errored) result.completedCleanly = true;
-            else if (t === ERROR) result.errored = true;
+            else if (t === COMPLETE && !nodeErrored.has(path)) result.anyCompletedCleanly = true;
+            else if (t === ERROR) {
+              result.anyErrored = true;
+              nodeErrored.add(path);
+            }
           } else if (t === DIRTY) {
             result.dirtyCount++;
             result.events.push({ type: "dirty", path, ...base });
@@ -3829,10 +3946,11 @@ var Graph = class _Graph {
             result.resolvedCount++;
             result.events.push({ type: "resolved", path, ...base });
           } else if (t === COMPLETE) {
-            if (!result.errored) result.completedCleanly = true;
+            if (!nodeErrored.has(path)) result.anyCompletedCleanly = true;
             result.events.push({ type: "complete", path, ...base });
           } else if (t === ERROR) {
-            result.errored = true;
+            result.anyErrored = true;
+            nodeErrored.add(path);
             result.events.push({ type: "error", path, data: m[1], ...base });
           }
         }
@@ -3852,11 +3970,14 @@ var Graph = class _Graph {
       get events() {
         return result.events;
       },
-      get completedCleanly() {
-        return result.completedCleanly;
+      get anyCompletedCleanly() {
+        return result.anyCompletedCleanly;
       },
-      get errored() {
-        return result.errored;
+      get anyErrored() {
+        return result.anyErrored;
+      },
+      get completedWithoutErrors() {
+        return result.anyCompletedCleanly && !result.anyErrored;
       },
       dispose() {
         for (const u of unsubs) u();
@@ -3869,25 +3990,169 @@ var Graph = class _Graph {
         } else {
           Object.assign(merged, extra);
         }
-        return graph._createObserveResultForAll(resolveObserveDetail(merged));
+        const expanded = graph._createObserveResultForAll(resolveObserveDetail(merged));
+        if (merged.format != null) {
+          graph._attachFormatLogger(expanded, merged);
+        }
+        return expanded;
       }
     };
   }
   /**
-   * Convenience live debugger over {@link Graph.observe}. Logs protocol events as they flow.
-   *
-   * Supports one-node (`path`) and graph-wide modes, event filtering, and JSON/pretty rendering.
-   * Color themes are built in (`ansi` / `none`) to avoid external dependencies.
-   *
-   * @param options - Spy configuration.
-   * @returns Disposable handle plus a structured observation accumulator.
+   * Fallback ObserveResult for single-node when inspector is disabled but `format` is requested.
+   * Subscribes to raw messages and accumulates events with timeline info.
+   */
+  _createFallbackObserveResult(path, options) {
+    const timeline = options.timeline !== false;
+    const acc = {
+      values: {},
+      dirtyCount: 0,
+      resolvedCount: 0,
+      events: [],
+      anyCompletedCleanly: false,
+      anyErrored: false
+    };
+    const target = this.resolve(path);
+    let batchSeq = 0;
+    const unsub = target.subscribe((msgs) => {
+      batchSeq++;
+      for (const m of msgs) {
+        const t = m[0];
+        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching(), batch_id: batchSeq } : {};
+        if (t === DATA) {
+          acc.values[path] = m[1];
+          acc.events.push({ type: "data", path, data: m[1], ...base });
+        } else if (t === DIRTY) {
+          acc.dirtyCount++;
+          acc.events.push({ type: "dirty", path, ...base });
+        } else if (t === RESOLVED) {
+          acc.resolvedCount++;
+          acc.events.push({ type: "resolved", path, ...base });
+        } else if (t === COMPLETE) {
+          if (!acc.anyErrored) acc.anyCompletedCleanly = true;
+          acc.events.push({ type: "complete", path, ...base });
+        } else if (t === ERROR) {
+          acc.anyErrored = true;
+          acc.events.push({ type: "error", path, data: m[1], ...base });
+        }
+      }
+    });
+    return {
+      get values() {
+        return acc.values;
+      },
+      get dirtyCount() {
+        return acc.dirtyCount;
+      },
+      get resolvedCount() {
+        return acc.resolvedCount;
+      },
+      get events() {
+        return acc.events;
+      },
+      get anyCompletedCleanly() {
+        return acc.anyCompletedCleanly;
+      },
+      get anyErrored() {
+        return acc.anyErrored;
+      },
+      get completedWithoutErrors() {
+        return acc.anyCompletedCleanly && !acc.anyErrored;
+      },
+      dispose() {
+        unsub();
+      },
+      expand() {
+        throw new Error("expand() requires inspector mode (Graph.inspectorEnabled = true)");
+      }
+    };
+  }
+  /**
+   * Fallback ObserveResult for graph-wide when inspector is disabled but `format` is requested.
+   */
+  _createFallbackObserveResultForAll(options) {
+    const timeline = options.timeline !== false;
+    const actor = options.actor;
+    const acc = {
+      values: {},
+      dirtyCount: 0,
+      resolvedCount: 0,
+      events: [],
+      anyCompletedCleanly: false,
+      anyErrored: false
+    };
+    const nodeErrored = /* @__PURE__ */ new Set();
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const picked = actor == null ? targets : targets.filter(([, nd]) => nd.allowsObserve(actor));
+    let batchSeq = 0;
+    const unsubs = picked.map(
+      ([path, nd]) => nd.subscribe((msgs) => {
+        batchSeq++;
+        for (const m of msgs) {
+          const t = m[0];
+          const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching(), batch_id: batchSeq } : {};
+          if (t === DATA) {
+            acc.values[path] = m[1];
+            acc.events.push({ type: "data", path, data: m[1], ...base });
+          } else if (t === DIRTY) {
+            acc.dirtyCount++;
+            acc.events.push({ type: "dirty", path, ...base });
+          } else if (t === RESOLVED) {
+            acc.resolvedCount++;
+            acc.events.push({ type: "resolved", path, ...base });
+          } else if (t === COMPLETE) {
+            if (!nodeErrored.has(path)) acc.anyCompletedCleanly = true;
+            acc.events.push({ type: "complete", path, ...base });
+          } else if (t === ERROR) {
+            acc.anyErrored = true;
+            nodeErrored.add(path);
+            acc.events.push({ type: "error", path, data: m[1], ...base });
+          }
+        }
+      })
+    );
+    return {
+      get values() {
+        return acc.values;
+      },
+      get dirtyCount() {
+        return acc.dirtyCount;
+      },
+      get resolvedCount() {
+        return acc.resolvedCount;
+      },
+      get events() {
+        return acc.events;
+      },
+      get anyCompletedCleanly() {
+        return acc.anyCompletedCleanly;
+      },
+      get anyErrored() {
+        return acc.anyErrored;
+      },
+      get completedWithoutErrors() {
+        return acc.anyCompletedCleanly && !acc.anyErrored;
+      },
+      dispose() {
+        for (const u of unsubs) u();
+      },
+      expand() {
+        throw new Error("expand() requires inspector mode (Graph.inspectorEnabled = true)");
+      }
+    };
+  }
+  /**
+   * Attaches a format logger to an ObserveResult, rendering events as they arrive.
+   * Wraps the result's dispose to flush pending events.
    */
-  spy(options = {}) {
+  _attachFormatLogger(result, options) {
+    const format = options.format;
+    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 theme = resolveSpyTheme(options.theme);
-    const format = options.format ?? "pretty";
-    const logger = options.logger ?? ((line) => console.log(line));
+    const theme = resolveObserveTheme(options.theme);
     const shouldLog = (type) => {
       if (include?.has(type) === false) return false;
       if (exclude?.has(type) === true) return false;
@@ -3912,133 +4177,26 @@ var Graph = class _Graph {
       const batchPart = event.in_batch ? " [batch]" : "";
       return `${pathPart}${color}${event.type.toUpperCase()}${theme.reset}${dataPart}${triggerPart}${batchPart}`;
     };
-    if (!_Graph.inspectorEnabled) {
-      const timeline = options.timeline ?? true;
-      const acc = {
-        values: {},
-        dirtyCount: 0,
-        resolvedCount: 0,
-        events: [],
-        completedCleanly: false,
-        errored: false
-      };
-      let stop2 = () => {
-      };
-      const result2 = {
-        get values() {
-          return acc.values;
-        },
-        get dirtyCount() {
-          return acc.dirtyCount;
-        },
-        get resolvedCount() {
-          return acc.resolvedCount;
-        },
-        get events() {
-          return acc.events;
-        },
-        get completedCleanly() {
-          return acc.completedCleanly;
-        },
-        get errored() {
-          return acc.errored;
-        },
-        dispose() {
-          stop2();
-        },
-        expand() {
-          throw new Error("expand() requires inspector mode (Graph.inspectorEnabled = true)");
-        }
-      };
-      const pushEvent = (path, message) => {
-        const t = message[0];
-        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
-        let event;
-        if (t === DATA) {
-          if (path != null) acc.values[path] = message[1];
-          event = { type: "data", ...path != null ? { path } : {}, data: message[1], ...base };
-        } else if (t === DIRTY) {
-          acc.dirtyCount += 1;
-          event = { type: "dirty", ...path != null ? { path } : {}, ...base };
-        } else if (t === RESOLVED) {
-          acc.resolvedCount += 1;
-          event = { type: "resolved", ...path != null ? { path } : {}, ...base };
-        } else if (t === COMPLETE) {
-          if (!acc.errored) acc.completedCleanly = true;
-          event = { type: "complete", ...path != null ? { path } : {}, ...base };
-        } else if (t === ERROR) {
-          acc.errored = true;
-          event = {
-            type: "error",
-            ...path != null ? { path } : {},
-            data: message[1],
-            ...base
-          };
+    let cursor = 0;
+    const flush = () => {
+      const events = result.events;
+      while (cursor < events.length) {
+        const event = events[cursor++];
+        if (shouldLog(event.type)) {
+          logger(renderEvent(event), event);
         }
-        if (!event) return;
-        acc.events.push(event);
-        if (!shouldLog(event.type)) return;
-        logger(renderEvent(event), event);
-      };
-      if (options.path != null) {
-        const stream2 = this.observe(options.path, {
-          actor: options.actor,
-          structured: false
-        });
-        stop2 = stream2.subscribe((messages) => {
-          for (const m of messages) {
-            pushEvent(options.path, m);
-          }
-        });
-      } else {
-        const stream2 = this.observe({ actor: options.actor, structured: false });
-        stop2 = stream2.subscribe((path, messages) => {
-          for (const m of messages) {
-            pushEvent(path, m);
-          }
-        });
       }
-      return {
-        result: result2,
-        dispose() {
-          result2.dispose();
-        }
-      };
-    }
-    const structuredObserveOptions = {
-      actor: options.actor,
-      structured: true,
-      ...options.timeline !== false ? { timeline: true } : {},
-      ...options.causal ? { causal: true } : {},
-      ...options.derived ? { derived: true } : {}
     };
-    const result = options.path != null ? this.observe(options.path, structuredObserveOptions) : this.observe(structuredObserveOptions);
-    let cursor = 0;
-    const flushNewEvents = () => {
-      const nextEvents = result.events.slice(cursor);
-      cursor = result.events.length;
-      for (const event of nextEvents) {
-        if (!shouldLog(event.type)) continue;
-        logger(renderEvent(event), event);
-      }
+    const origPush = result.events.push;
+    result.events.push = function(...items) {
+      const ret = origPush.apply(this, items);
+      flush();
+      return ret;
     };
-    const stream = options.path != null ? this.observe(options.path, { actor: options.actor, structured: false }) : this.observe({ actor: options.actor, structured: false });
-    const stop = options.path != null ? stream.subscribe((messages) => {
-      if (messages.length > 0) {
-        flushNewEvents();
-      }
-    }) : stream.subscribe((_path, messages) => {
-      if (messages.length > 0) {
-        flushNewEvents();
-      }
-    });
-    return {
-      result,
-      dispose() {
-        stop();
-        flushNewEvents();
-        result.dispose();
-      }
+    const origDispose = result.dispose.bind(result);
+    result.dispose = () => {
+      origDispose();
+      flush();
     };
   }
   /**
@@ -4301,8 +4459,9 @@ var Graph = class _Graph {
   /**
    * Debounced persistence wired to graph-wide observe stream (spec §3.8 auto-checkpoint).
    *
-   * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 2 messages
-   * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1 control waves.
+   * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 3 messages
+   * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1/2 control
+   * waves (`START`/`DIRTY`/`INVALIDATE`/`PAUSE`/`RESUME`).
    */
   autoCheckpoint(adapter, options = {}) {
     const debounceMs = Math.max(0, options.debounceMs ?? 500);
@@ -4349,7 +4508,7 @@ var Graph = class _Graph {
       timer = setTimeout(flush, debounceMs);
     };
     const off = this.observe().subscribe((path, messages) => {
-      const triggeredByTier = messages.some((m) => messageTier(m[0]) >= 2);
+      const triggeredByTier = messages.some((m) => messageTier(m[0]) >= 3);
       if (!triggeredByTier) return;
       if (options.filter) {
         const nd = this.resolve(path);
@@ -4433,33 +4592,21 @@ var Graph = class _Graph {
   // ——————————————————————————————————————————————————————————————
   /**
    * When `false`, structured observation options (`causal`, `timeline`),
-   * `annotate()`, and `traceLog()` are no-ops. Raw `observe()` always works.
+   * and `trace()` writes are no-ops. Raw `observe()` always works.
    *
    * Default: `true` outside production (`process.env.NODE_ENV !== "production"`).
    */
   static inspectorEnabled = !(typeof process !== "undefined" && process.env?.NODE_ENV === "production");
   _annotations = /* @__PURE__ */ new Map();
   _traceRing = new RingBuffer(1e3);
-  /**
-   * Attaches a reasoning annotation to a node — captures *why* an AI agent set a value.
-   *
-   * No-op when {@link Graph.inspectorEnabled} is `false`.
-   *
-   * @param path - Qualified node path.
-   * @param reason - Free-text note stored in the trace ring buffer.
-   */
-  annotate(path, reason) {
-    if (!_Graph.inspectorEnabled) return;
-    this.resolve(path);
-    this._annotations.set(path, reason);
-    this._traceRing.push({ path, reason, timestamp_ns: monotonicNs() });
-  }
-  /**
-   * Returns a chronological log of all reasoning annotations (ring buffer).
-   *
-   * @returns `[]` when {@link Graph.inspectorEnabled} is `false`.
-   */
-  traceLog() {
+  trace(path, reason) {
+    if (path != null && reason != null) {
+      if (!_Graph.inspectorEnabled) return;
+      this.resolve(path);
+      this._annotations.set(path, reason);
+      this._traceRing.push({ path, reason, timestamp_ns: monotonicNs() });
+      return;
+    }
     if (!_Graph.inspectorEnabled) return [];
     return this._traceRing.toArray();
   }
@@ -5084,11 +5231,8 @@ var GraphReflyModule = _GraphReflyModule;
   getActor,
   getGraphToken,
   getNodeToken,
-  observeGraph$,
-  observeNode$,
   observeSSE,
   observeSubscription,
-  toMessages$,
   toObservable
 });
 //# sourceMappingURL=index.cjs.map