@graphrefly/graphrefly 0.1.0

package/dist/compat/nestjs/index.cjs

@@ -0,0 +1,4883 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x) {
+    return __privateSet(this, extra, x);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => name in x };
+      if (k ^ 3) access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2) access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/compat/nestjs/index.ts
+var nestjs_exports = {};
+__export(nestjs_exports, {
+  ACTOR_KEY: () => ACTOR_KEY,
+  COMMAND_HANDLERS: () => COMMAND_HANDLERS,
+  CQRS_EVENT_HANDLERS: () => CQRS_EVENT_HANDLERS,
+  CRON_HANDLERS: () => CRON_HANDLERS,
+  CommandHandler: () => CommandHandler,
+  EVENT_HANDLERS: () => EVENT_HANDLERS,
+  EventHandler: () => EventHandler,
+  GRAPHREFLY_REQUEST_GRAPH: () => GRAPHREFLY_REQUEST_GRAPH,
+  GRAPHREFLY_ROOT_GRAPH: () => GRAPHREFLY_ROOT_GRAPH,
+  GraphCron: () => GraphCron,
+  GraphInterval: () => GraphInterval,
+  GraphReflyEventExplorer: () => GraphReflyEventExplorer,
+  GraphReflyGuard: () => GraphReflyGuard,
+  GraphReflyGuardImpl: () => GraphReflyGuardImpl,
+  GraphReflyModule: () => GraphReflyModule,
+  INTERVAL_HANDLERS: () => INTERVAL_HANDLERS,
+  InjectCqrsGraph: () => InjectCqrsGraph,
+  InjectGraph: () => InjectGraph,
+  InjectNode: () => InjectNode,
+  ObserveGateway: () => ObserveGateway,
+  OnGraphEvent: () => OnGraphEvent,
+  QUERY_HANDLERS: () => QUERY_HANDLERS,
+  QueryHandler: () => QueryHandler,
+  SAGA_HANDLERS: () => SAGA_HANDLERS,
+  SagaHandler: () => SagaHandler,
+  fromHeader: () => fromHeader,
+  fromJwtPayload: () => fromJwtPayload,
+  getActor: () => getActor,
+  getGraphToken: () => getGraphToken,
+  getNodeToken: () => getNodeToken,
+  observeGraph$: () => observeGraph$,
+  observeNode$: () => observeNode$,
+  observeSSE: () => observeSSE,
+  observeSubscription: () => observeSubscription,
+  toMessages$: () => toMessages$,
+  toObservable: () => toObservable
+});
+module.exports = __toCommonJS(nestjs_exports);
+
+// src/extra/observable.ts
+var import_rxjs = require("rxjs");
+
+// src/core/messages.ts
+var DATA = /* @__PURE__ */ Symbol.for("graphrefly/DATA");
+var DIRTY = /* @__PURE__ */ Symbol.for("graphrefly/DIRTY");
+var RESOLVED = /* @__PURE__ */ Symbol.for("graphrefly/RESOLVED");
+var INVALIDATE = /* @__PURE__ */ Symbol.for("graphrefly/INVALIDATE");
+var PAUSE = /* @__PURE__ */ Symbol.for("graphrefly/PAUSE");
+var RESUME = /* @__PURE__ */ Symbol.for("graphrefly/RESUME");
+var TEARDOWN = /* @__PURE__ */ Symbol.for("graphrefly/TEARDOWN");
+var COMPLETE = /* @__PURE__ */ Symbol.for("graphrefly/COMPLETE");
+var ERROR = /* @__PURE__ */ Symbol.for("graphrefly/ERROR");
+function messageTier(t) {
+  if (t === DIRTY || t === INVALIDATE) return 0;
+  if (t === PAUSE || t === RESUME) return 1;
+  if (t === DATA || t === RESOLVED) return 2;
+  if (t === COMPLETE || t === ERROR) return 3;
+  if (t === TEARDOWN) return 4;
+  return 0;
+}
+function isPhase2Message(msg) {
+  const t = msg[0];
+  return t === DATA || t === RESOLVED;
+}
+function isTerminalMessage(t) {
+  return t === COMPLETE || t === ERROR;
+}
+function propagatesToMeta(t) {
+  return t === TEARDOWN;
+}
+
+// src/extra/observable.ts
+function toObservable(node2) {
+  return new import_rxjs.Observable((subscriber) => {
+    const unsub = node2.subscribe((msgs) => {
+      for (const m of 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;
+        }
+      }
+    });
+    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) {
+          subscriber.next(m[1]);
+        } else if (m[0] === ERROR) {
+          subscriber.error(m[1]);
+          return;
+        } else if (m[0] === COMPLETE) {
+          subscriber.complete();
+          return;
+        }
+      }
+    });
+    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");
+
+// src/compat/nestjs/tokens.ts
+var GRAPHREFLY_ROOT_GRAPH = /* @__PURE__ */ Symbol.for("graphrefly:root-graph");
+var GRAPHREFLY_REQUEST_GRAPH = /* @__PURE__ */ Symbol.for("graphrefly:request-graph");
+function getGraphToken(name) {
+  return /* @__PURE__ */ Symbol.for(`graphrefly:graph:${name}`);
+}
+function getNodeToken(path) {
+  return /* @__PURE__ */ Symbol.for(`graphrefly:node:${path}`);
+}
+
+// src/compat/nestjs/decorators.ts
+var EVENT_HANDLERS = /* @__PURE__ */ new Map();
+var INTERVAL_HANDLERS = /* @__PURE__ */ new Map();
+var CRON_HANDLERS = /* @__PURE__ */ new Map();
+var COMMAND_HANDLERS = /* @__PURE__ */ new Map();
+var CQRS_EVENT_HANDLERS = /* @__PURE__ */ new Map();
+var QUERY_HANDLERS = /* @__PURE__ */ new Map();
+var SAGA_HANDLERS = /* @__PURE__ */ new Map();
+function InjectGraph(name) {
+  if (name === "request") return (0, import_common.Inject)(GRAPHREFLY_REQUEST_GRAPH);
+  return (0, import_common.Inject)(name ? getGraphToken(name) : GRAPHREFLY_ROOT_GRAPH);
+}
+function InjectCqrsGraph(name) {
+  return (0, import_common.Inject)(getGraphToken(name));
+}
+function InjectNode(path) {
+  return (0, import_common.Inject)(getNodeToken(path));
+}
+function OnGraphEvent(nodeName) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = EVENT_HANDLERS.get(ctor) ?? [];
+      existing.push({ nodeName, methodKey });
+      EVENT_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+function GraphInterval(ms) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = INTERVAL_HANDLERS.get(ctor) ?? [];
+      existing.push({ ms, methodKey });
+      INTERVAL_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+function GraphCron(expr) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = CRON_HANDLERS.get(ctor) ?? [];
+      existing.push({ expr, methodKey });
+      CRON_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+function CommandHandler(cqrsName, commandName) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = COMMAND_HANDLERS.get(ctor) ?? [];
+      existing.push({ cqrsName, commandName, methodKey });
+      COMMAND_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+function EventHandler(cqrsName, eventName) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = CQRS_EVENT_HANDLERS.get(ctor) ?? [];
+      existing.push({ cqrsName, eventName, methodKey });
+      CQRS_EVENT_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+function QueryHandler(cqrsName, projectionName) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = QUERY_HANDLERS.get(ctor) ?? [];
+      existing.push({ cqrsName, projectionName, methodKey });
+      QUERY_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+function SagaHandler(cqrsName, sagaName, eventNames) {
+  return (_value, context) => {
+    const methodKey = context.name;
+    context.addInitializer(function() {
+      const ctor = this.constructor;
+      const existing = SAGA_HANDLERS.get(ctor) ?? [];
+      existing.push({ cqrsName, eventNames, sagaName, methodKey });
+      SAGA_HANDLERS.set(ctor, existing);
+    });
+  };
+}
+
+// src/extra/sources.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/core/clock.ts
+function monotonicNs() {
+  return Math.trunc(performance.now() * 1e6);
+}
+function wallClockNs() {
+  return Date.now() * 1e6;
+}
+
+// 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 pendingPhase2 = [];
+var pendingPhase3 = [];
+function isBatching() {
+  return batchDepth > 0 || flushInProgress;
+}
+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) {
+          pendingPhase2.length = 0;
+          pendingPhase3.length = 0;
+        }
+      } else {
+        drainPending();
+      }
+    }
+  }
+}
+function drainPending() {
+  const ownsFlush = !flushInProgress;
+  if (ownsFlush) {
+    flushInProgress = true;
+  }
+  let firstError;
+  let hasError = false;
+  try {
+    let iterations = 0;
+    while (pendingPhase2.length > 0 || pendingPhase3.length > 0) {
+      while (pendingPhase2.length > 0) {
+        iterations += 1;
+        if (iterations > MAX_DRAIN_ITERATIONS) {
+          pendingPhase2.length = 0;
+          pendingPhase3.length = 0;
+          throw new Error(
+            `batch drain exceeded ${MAX_DRAIN_ITERATIONS} iterations \u2014 likely a reactive cycle`
+          );
+        }
+        const ops = pendingPhase2.splice(0);
+        for (const run of ops) {
+          try {
+            run();
+          } catch (e) {
+            if (!hasError) {
+              firstError = e;
+              hasError = true;
+            }
+          }
+        }
+      }
+      if (pendingPhase3.length > 0) {
+        iterations += 1;
+        if (iterations > MAX_DRAIN_ITERATIONS) {
+          pendingPhase2.length = 0;
+          pendingPhase3.length = 0;
+          throw new Error(
+            `batch drain exceeded ${MAX_DRAIN_ITERATIONS} iterations \u2014 likely a reactive cycle`
+          );
+        }
+        const ops = pendingPhase3.splice(0);
+        for (const run of ops) {
+          try {
+            run();
+          } catch (e) {
+            if (!hasError) {
+              firstError = e;
+              hasError = true;
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    if (ownsFlush) {
+      flushInProgress = false;
+    }
+  }
+  if (hasError) {
+    throw firstError;
+  }
+}
+function partitionForBatch(messages) {
+  const immediate = [];
+  const deferred = [];
+  const terminal = [];
+  for (const m of messages) {
+    if (isPhase2Message(m)) {
+      deferred.push(m);
+    } else if (isTerminalMessage(m[0])) {
+      terminal.push(m);
+    } else {
+      immediate.push(m);
+    }
+  }
+  return { immediate, deferred, terminal };
+}
+function emitWithBatch(emit, messages, phase = 2) {
+  if (messages.length === 0) {
+    return;
+  }
+  const queue = phase === 3 ? pendingPhase3 : pendingPhase2;
+  if (messages.length === 1) {
+    const t = messages[0][0];
+    if (t === DATA || t === RESOLVED) {
+      if (isBatching()) {
+        queue.push(() => emit(messages));
+      } else {
+        emit(messages);
+      }
+    } else if (isTerminalMessage(t)) {
+      if (isBatching()) {
+        queue.push(() => emit(messages));
+      } else {
+        emit(messages);
+      }
+    } else {
+      emit(messages);
+    }
+    return;
+  }
+  const { immediate, deferred, terminal } = partitionForBatch(messages);
+  if (immediate.length > 0) {
+    emit(immediate);
+  }
+  if (isBatching()) {
+    if (deferred.length > 0) {
+      queue.push(() => emit(deferred));
+    }
+    if (terminal.length > 0) {
+      queue.push(() => emit(terminal));
+    }
+  } else {
+    if (deferred.length > 0) {
+      emit(deferred);
+    }
+    if (terminal.length > 0) {
+      emit(terminal);
+    }
+  }
+}
+
+// src/core/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) {
+  if (value === void 0) return null;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Cannot hash non-finite number: ${value}`);
+    }
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw new TypeError(
+        `Cannot hash integer outside safe range (|n| > 2^53-1): ${value}. Cross-language cid parity is not guaranteed for unsafe integers.`
+      );
+    }
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(canonicalizeForHash);
+  }
+  if (typeof value === "object" && value !== null) {
+    const sorted = {};
+    for (const k of Object.keys(value).sort()) {
+      sorted[k] = canonicalizeForHash(value[k]);
+    }
+    return sorted;
+  }
+  return null;
+}
+function defaultHash(value) {
+  const canonical = canonicalizeForHash(value ?? null);
+  const json = JSON.stringify(canonical);
+  return (0, import_node_crypto.createHash)("sha256").update(json).digest("hex").slice(0, 16);
+}
+function createVersioning(level, initialValue, opts) {
+  const id = opts?.id ?? (0, import_node_crypto.randomUUID)();
+  if (level === 0) {
+    return { id, version: 0 };
+  }
+  const hash = opts?.hash ?? defaultHash;
+  const cid = hash(initialValue);
+  return { id, version: 0, cid, prev: null };
+}
+function advanceVersion(info, newValue, hashFn) {
+  info.version += 1;
+  if ("cid" in info) {
+    info.prev = info.cid;
+    info.cid = hashFn(newValue);
+  }
+}
+
+// src/core/node.ts
+function createIntBitSet() {
+  let bits = 0;
+  return {
+    set(i) {
+      bits |= 1 << i;
+    },
+    clear(i) {
+      bits &= ~(1 << i);
+    },
+    has(i) {
+      return (bits & 1 << i) !== 0;
+    },
+    covers(other) {
+      return (bits & other._bits()) === other._bits();
+    },
+    any() {
+      return bits !== 0;
+    },
+    reset() {
+      bits = 0;
+    },
+    _bits() {
+      return bits;
+    }
+  };
+}
+function createArrayBitSet(size) {
+  const words = new Uint32Array(Math.ceil(size / 32));
+  return {
+    set(i) {
+      words[i >>> 5] |= 1 << (i & 31);
+    },
+    clear(i) {
+      words[i >>> 5] &= ~(1 << (i & 31));
+    },
+    has(i) {
+      return (words[i >>> 5] & 1 << (i & 31)) !== 0;
+    },
+    covers(other) {
+      const ow = other._words;
+      for (let w = 0; w < words.length; w++) {
+        if ((words[w] & ow[w]) >>> 0 !== ow[w]) return false;
+      }
+      return true;
+    },
+    any() {
+      for (let w = 0; w < words.length; w++) {
+        if (words[w] !== 0) return true;
+      }
+      return false;
+    },
+    reset() {
+      words.fill(0);
+    },
+    _words: words
+  };
+}
+function createBitSet(size) {
+  return size <= 31 ? createIntBitSet() : createArrayBitSet(size);
+}
+var isNodeArray = (value) => Array.isArray(value);
+var isNodeOptions = (value) => typeof value === "object" && value != null && !Array.isArray(value);
+var isCleanupFn = (value) => typeof value === "function";
+var statusAfterMessage = (status, msg) => {
+  const t = msg[0];
+  if (t === DIRTY) return "dirty";
+  if (t === DATA) return "settled";
+  if (t === RESOLVED) return "resolved";
+  if (t === COMPLETE) return "completed";
+  if (t === ERROR) return "errored";
+  if (t === INVALIDATE) return "dirty";
+  if (t === TEARDOWN) return "disconnected";
+  return status;
+};
+var NodeImpl = class {
+  // --- Configuration (set once, never reassigned) ---
+  _optsName;
+  _registryName;
+  /** @internal — read by {@link describeNode} before inference. */
+  _describeKind;
+  meta;
+  _deps;
+  _fn;
+  _opts;
+  _equals;
+  _onMessage;
+  /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
+  _guard;
+  _lastMutation;
+  _hasDeps;
+  _autoComplete;
+  _isSingleDep;
+  // --- Mutable state ---
+  _cached;
+  _status;
+  _terminal = false;
+  _connected = false;
+  _producerStarted = false;
+  _connecting = false;
+  _manualEmitUsed = false;
+  _sinkCount = 0;
+  _singleDepSinkCount = 0;
+  // --- Object/collection state ---
+  _depDirtyMask;
+  _depSettledMask;
+  _depCompleteMask;
+  _allDepsCompleteMask;
+  _lastDepValues;
+  _cleanup;
+  _sinks = null;
+  _singleDepSinks = /* @__PURE__ */ new WeakSet();
+  _upstreamUnsubs = [];
+  _actions;
+  _boundEmitToSinks;
+  _inspectorHook;
+  _versioning;
+  _hashFn;
+  constructor(deps, fn, opts) {
+    this._deps = deps;
+    this._fn = fn;
+    this._opts = opts;
+    this._optsName = opts.name;
+    this._describeKind = opts.describeKind;
+    this._equals = opts.equals ?? Object.is;
+    this._onMessage = opts.onMessage;
+    this._guard = opts.guard;
+    this._hasDeps = deps.length > 0;
+    this._autoComplete = opts.completeWhenDepsComplete ?? true;
+    this._isSingleDep = deps.length === 1 && fn != null;
+    this._cached = opts.initial;
+    this._status = this._hasDeps ? "disconnected" : "settled";
+    this._hashFn = opts.versioningHash ?? defaultHash;
+    this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached, {
+      id: opts.versioningId,
+      hash: this._hashFn
+    }) : void 0;
+    this._depDirtyMask = createBitSet(deps.length);
+    this._depSettledMask = createBitSet(deps.length);
+    this._depCompleteMask = createBitSet(deps.length);
+    this._allDepsCompleteMask = createBitSet(deps.length);
+    for (let i = 0; i < deps.length; i++) this._allDepsCompleteMask.set(i);
+    const meta = {};
+    for (const [k, v] of Object.entries(opts.meta ?? {})) {
+      meta[k] = node({
+        initial: v,
+        name: `${opts.name ?? "node"}:meta:${k}`,
+        describeKind: "state",
+        ...opts.guard != null ? { guard: opts.guard } : {}
+      });
+    }
+    Object.freeze(meta);
+    this.meta = meta;
+    const self = this;
+    this._actions = {
+      down(messages) {
+        self._manualEmitUsed = true;
+        self._downInternal(messages);
+      },
+      emit(value) {
+        self._manualEmitUsed = true;
+        self._emitAutoValue(value);
+      },
+      up(messages) {
+        self._upInternal(messages);
+      }
+    };
+    this.down = this.down.bind(this);
+    this.up = this.up.bind(this);
+    this._boundEmitToSinks = this._emitToSinks.bind(this);
+  }
+  get name() {
+    return this._registryName ?? this._optsName;
+  }
+  /**
+   * When a node is registered with {@link Graph.add} without an options `name`,
+   * the graph assigns the registry local name for introspection (parity with graphrefly-py).
+   */
+  _assignRegistryName(localName) {
+    if (this._optsName !== void 0 || this._registryName !== void 0) return;
+    this._registryName = localName;
+  }
+  /**
+   * @internal Attach/remove inspector hook for graph-level observability.
+   * Returns a disposer that restores the previous hook.
+   */
+  _setInspectorHook(hook) {
+    const prev = this._inspectorHook;
+    this._inspectorHook = hook;
+    return () => {
+      if (this._inspectorHook === hook) {
+        this._inspectorHook = prev;
+      }
+    };
+  }
+  // --- Public interface (Node<T>) ---
+  get status() {
+    return this._status;
+  }
+  get lastMutation() {
+    return this._lastMutation;
+  }
+  get v() {
+    return this._versioning;
+  }
+  /**
+   * Retroactively apply versioning to a node that was created without it.
+   * No-op if versioning is already enabled.
+   *
+   * Version starts at 0 regardless of prior DATA emissions — it tracks
+   * changes from the moment versioning is enabled, not historical ones.
+   *
+   * @internal — used by {@link Graph.setVersioning}.
+   */
+  _applyVersioning(level, opts) {
+    if (this._versioning != null) return;
+    this._hashFn = opts?.hash ?? this._hashFn;
+    this._versioning = createVersioning(level, this._cached, {
+      id: opts?.id,
+      hash: this._hashFn
+    });
+  }
+  hasGuard() {
+    return this._guard != null;
+  }
+  allowsObserve(actor) {
+    if (this._guard == null) return true;
+    return this._guard(normalizeActor(actor), "observe");
+  }
+  get() {
+    return this._cached;
+  }
+  down(messages, options) {
+    if (messages.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      const delivery = options?.delivery ?? "write";
+      const action = delivery === "signal" ? "signal" : "write";
+      if (!this._guard(actor, action)) {
+        throw new GuardDenied({ actor, action, nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    this._downInternal(messages);
+  }
+  _downInternal(messages) {
+    if (messages.length === 0) return;
+    let lifecycleMessages = messages;
+    let sinkMessages = messages;
+    if (this._terminal && !this._opts.resubscribable) {
+      const terminalPassthrough = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
+      if (terminalPassthrough.length === 0) return;
+      lifecycleMessages = terminalPassthrough;
+      sinkMessages = terminalPassthrough;
+    }
+    this._handleLocalLifecycle(lifecycleMessages);
+    if (this._canSkipDirty()) {
+      let hasPhase2 = false;
+      for (let i = 0; i < sinkMessages.length; i++) {
+        const t = sinkMessages[i][0];
+        if (t === DATA || t === RESOLVED) {
+          hasPhase2 = true;
+          break;
+        }
+      }
+      if (hasPhase2) {
+        const filtered = [];
+        for (let i = 0; i < sinkMessages.length; i++) {
+          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
+        }
+        if (filtered.length > 0) {
+          emitWithBatch(this._boundEmitToSinks, filtered);
+        }
+        return;
+      }
+    }
+    emitWithBatch(this._boundEmitToSinks, sinkMessages);
+  }
+  subscribe(sink, hints) {
+    if (hints?.actor != null && this._guard != null) {
+      const actor = normalizeActor(hints.actor);
+      if (!this._guard(actor, "observe")) {
+        throw new GuardDenied({ actor, action: "observe", nodeName: this.name });
+      }
+    }
+    if (this._terminal && this._opts.resubscribable) {
+      this._terminal = false;
+      this._status = this._hasDeps ? "disconnected" : "settled";
+      this._opts.onResubscribe?.();
+    }
+    this._sinkCount += 1;
+    if (hints?.singleDep) {
+      this._singleDepSinkCount += 1;
+      this._singleDepSinks.add(sink);
+    }
+    if (this._sinks == null) {
+      this._sinks = sink;
+    } else if (typeof this._sinks === "function") {
+      this._sinks = /* @__PURE__ */ new Set([this._sinks, sink]);
+    } else {
+      this._sinks.add(sink);
+    }
+    if (this._hasDeps) {
+      this._connectUpstream();
+    } else if (this._fn) {
+      this._startProducer();
+    }
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this._sinkCount -= 1;
+      if (this._singleDepSinks.has(sink)) {
+        this._singleDepSinkCount -= 1;
+        this._singleDepSinks.delete(sink);
+      }
+      if (this._sinks == null) return;
+      if (typeof this._sinks === "function") {
+        if (this._sinks === sink) this._sinks = null;
+      } else {
+        this._sinks.delete(sink);
+        if (this._sinks.size === 1) {
+          const [only] = this._sinks;
+          this._sinks = only;
+        } else if (this._sinks.size === 0) {
+          this._sinks = null;
+        }
+      }
+      if (this._sinks == null) {
+        this._disconnectUpstream();
+        this._stopProducer();
+      }
+    };
+  }
+  up(messages, options) {
+    if (!this._hasDeps) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      if (!this._guard(actor, "write")) {
+        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    for (const dep of this._deps) {
+      if (options === void 0) {
+        dep.up?.(messages);
+      } else {
+        dep.up?.(messages, options);
+      }
+    }
+  }
+  _upInternal(messages) {
+    if (!this._hasDeps) return;
+    for (const dep of this._deps) {
+      dep.up?.(messages, { internal: true });
+    }
+  }
+  unsubscribe() {
+    if (!this._hasDeps) return;
+    this._disconnectUpstream();
+  }
+  // --- Private methods (prototype, _ prefix) ---
+  _emitToSinks(messages) {
+    if (this._sinks == null) return;
+    if (typeof this._sinks === "function") {
+      this._sinks(messages);
+      return;
+    }
+    const snapshot = [...this._sinks];
+    for (const sink of snapshot) {
+      sink(messages);
+    }
+  }
+  _handleLocalLifecycle(messages) {
+    for (const m of messages) {
+      const t = m[0];
+      if (t === DATA) {
+        this._cached = m[1];
+        if (this._versioning != null) {
+          advanceVersion(this._versioning, m[1], this._hashFn);
+        }
+      }
+      if (t === INVALIDATE) {
+        const cleanupFn = this._cleanup;
+        this._cleanup = void 0;
+        cleanupFn?.();
+        this._cached = void 0;
+        this._lastDepValues = void 0;
+      }
+      this._status = statusAfterMessage(this._status, m);
+      if (t === COMPLETE || t === ERROR) {
+        this._terminal = true;
+      }
+      if (t === TEARDOWN) {
+        if (this._opts.resetOnTeardown) {
+          this._cached = void 0;
+        }
+        const teardownCleanup = this._cleanup;
+        this._cleanup = void 0;
+        teardownCleanup?.();
+        try {
+          this._propagateToMeta(t);
+        } finally {
+          this._disconnectUpstream();
+          this._stopProducer();
+        }
+      }
+      if (t !== TEARDOWN && propagatesToMeta(t)) {
+        this._propagateToMeta(t);
+      }
+    }
+  }
+  /** Propagate a signal to all companion meta nodes (best-effort). */
+  _propagateToMeta(t) {
+    for (const metaNode of Object.values(this.meta)) {
+      try {
+        metaNode._downInternal([[t]]);
+      } catch {
+      }
+    }
+  }
+  _canSkipDirty() {
+    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
+  }
+  _emitAutoValue(value) {
+    const wasDirty = this._status === "dirty";
+    const unchanged = this._equals(this._cached, value);
+    if (unchanged) {
+      this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
+      return;
+    }
+    this._cached = value;
+    this._downInternal(wasDirty ? [[DATA, value]] : [[DIRTY], [DATA, value]]);
+  }
+  _runFn() {
+    if (!this._fn) return;
+    if (this._terminal && !this._opts.resubscribable) return;
+    if (this._connecting) return;
+    try {
+      const n = this._deps.length;
+      const depValues = new Array(n);
+      for (let i = 0; i < n; i++) depValues[i] = this._deps[i].get();
+      const prev = this._lastDepValues;
+      if (n > 0 && prev != null && prev.length === n) {
+        let allSame = true;
+        for (let i = 0; i < n; i++) {
+          if (!Object.is(depValues[i], prev[i])) {
+            allSame = false;
+            break;
+          }
+        }
+        if (allSame) {
+          if (this._status === "dirty") {
+            this._downInternal([[RESOLVED]]);
+          }
+          return;
+        }
+      }
+      const prevCleanup = this._cleanup;
+      this._cleanup = void 0;
+      prevCleanup?.();
+      this._manualEmitUsed = false;
+      this._lastDepValues = depValues;
+      this._inspectorHook?.({ kind: "run", depValues });
+      const out = this._fn(depValues, this._actions);
+      if (isCleanupFn(out)) {
+        this._cleanup = out;
+        return;
+      }
+      if (this._manualEmitUsed) return;
+      if (out === void 0) return;
+      this._emitAutoValue(out);
+    } catch (err) {
+      this._downInternal([[ERROR, err]]);
+    }
+  }
+  _onDepDirty(index) {
+    const wasDirty = this._depDirtyMask.has(index);
+    this._depDirtyMask.set(index);
+    this._depSettledMask.clear(index);
+    if (!wasDirty) {
+      this._downInternal([[DIRTY]]);
+    }
+  }
+  _onDepSettled(index) {
+    if (!this._depDirtyMask.has(index)) {
+      this._onDepDirty(index);
+    }
+    this._depSettledMask.set(index);
+    if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
+      this._depDirtyMask.reset();
+      this._depSettledMask.reset();
+      this._runFn();
+    }
+  }
+  _maybeCompleteFromDeps() {
+    if (this._autoComplete && this._deps.length > 0 && this._depCompleteMask.covers(this._allDepsCompleteMask)) {
+      this._downInternal([[COMPLETE]]);
+    }
+  }
+  _handleDepMessages(index, messages) {
+    for (const msg of messages) {
+      this._inspectorHook?.({ kind: "dep_message", depIndex: index, message: msg });
+      const t = msg[0];
+      if (this._onMessage) {
+        try {
+          if (this._onMessage(msg, index, this._actions)) continue;
+        } catch (err) {
+          this._downInternal([[ERROR, err]]);
+          return;
+        }
+      }
+      if (!this._fn) {
+        if (t === COMPLETE && this._deps.length > 1) {
+          this._depCompleteMask.set(index);
+          this._maybeCompleteFromDeps();
+          continue;
+        }
+        this._downInternal([msg]);
+        continue;
+      }
+      if (t === DIRTY) {
+        this._onDepDirty(index);
+        continue;
+      }
+      if (t === DATA || t === RESOLVED) {
+        this._onDepSettled(index);
+        continue;
+      }
+      if (t === COMPLETE) {
+        this._depCompleteMask.set(index);
+        this._depDirtyMask.clear(index);
+        this._depSettledMask.clear(index);
+        if (this._depDirtyMask.any() && this._depSettledMask.covers(this._depDirtyMask)) {
+          this._depDirtyMask.reset();
+          this._depSettledMask.reset();
+          this._runFn();
+        } else if (!this._depDirtyMask.any() && this._status === "dirty") {
+          this._depSettledMask.reset();
+          this._runFn();
+        }
+        this._maybeCompleteFromDeps();
+        continue;
+      }
+      if (t === ERROR) {
+        this._downInternal([msg]);
+        continue;
+      }
+      if (t === INVALIDATE || t === TEARDOWN || t === PAUSE || t === RESUME) {
+        this._downInternal([msg]);
+        continue;
+      }
+      this._downInternal([msg]);
+    }
+  }
+  _connectUpstream() {
+    if (!this._hasDeps || this._connected) return;
+    this._connected = true;
+    this._depDirtyMask.reset();
+    this._depSettledMask.reset();
+    this._depCompleteMask.reset();
+    this._status = "settled";
+    const subHints = this._isSingleDep ? { singleDep: true } : void 0;
+    this._connecting = true;
+    try {
+      for (let i = 0; i < this._deps.length; i += 1) {
+        const dep = this._deps[i];
+        this._upstreamUnsubs.push(
+          dep.subscribe((msgs) => this._handleDepMessages(i, msgs), subHints)
+        );
+      }
+    } finally {
+      this._connecting = false;
+    }
+    if (this._fn) {
+      this._runFn();
+    }
+  }
+  _stopProducer() {
+    if (!this._producerStarted) return;
+    this._producerStarted = false;
+    const producerCleanup = this._cleanup;
+    this._cleanup = void 0;
+    producerCleanup?.();
+  }
+  _startProducer() {
+    if (this._deps.length !== 0 || !this._fn || this._producerStarted) return;
+    this._producerStarted = true;
+    this._runFn();
+  }
+  _disconnectUpstream() {
+    if (!this._connected) return;
+    for (const unsub of this._upstreamUnsubs.splice(0)) {
+      unsub();
+    }
+    this._connected = false;
+    this._depDirtyMask.reset();
+    this._depSettledMask.reset();
+    this._depCompleteMask.reset();
+    this._status = "disconnected";
+  }
+};
+function node(depsOrFn, fnOrOpts, optsArg) {
+  const deps = isNodeArray(depsOrFn) ? depsOrFn : [];
+  const fn = typeof depsOrFn === "function" ? depsOrFn : typeof fnOrOpts === "function" ? fnOrOpts : void 0;
+  let opts = {};
+  if (isNodeArray(depsOrFn)) {
+    opts = (isNodeOptions(fnOrOpts) ? fnOrOpts : optsArg) ?? {};
+  } else if (isNodeOptions(depsOrFn)) {
+    opts = depsOrFn;
+  } else {
+    opts = (isNodeOptions(fnOrOpts) ? fnOrOpts : optsArg) ?? {};
+  }
+  return new NodeImpl(deps, fn, opts);
+}
+
+// src/core/sugar.ts
+function state(initial, opts) {
+  return node([], { ...opts, initial });
+}
+function producer(fn, opts) {
+  return node(fn, { describeKind: "producer", ...opts });
+}
+function derived(deps, fn, opts) {
+  return node(deps, fn, { describeKind: "derived", ...opts });
+}
+
+// src/extra/cron.ts
+function parseField(field, min, max) {
+  const result = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    const [range, stepStr] = part.split("/");
+    const step = stepStr ? Number.parseInt(stepStr, 10) : 1;
+    if (Number.isNaN(step) || step < 1) throw new Error(`Invalid cron step: ${part}`);
+    let start;
+    let end;
+    if (range === "*") {
+      start = min;
+      end = max;
+    } else if (range.includes("-")) {
+      const [a, b] = range.split("-");
+      start = Number.parseInt(a, 10);
+      end = Number.parseInt(b, 10);
+    } else {
+      start = Number.parseInt(range, 10);
+      end = start;
+    }
+    if (Number.isNaN(start) || Number.isNaN(end)) throw new Error(`Invalid cron field: ${field}`);
+    if (start < min || end > max)
+      throw new Error(`Cron field out of range: ${field} (${min}-${max})`);
+    if (start > end) throw new Error(`Invalid cron range: ${start}-${end} in ${field}`);
+    for (let i = start; i <= end; i += step) result.add(i);
+  }
+  return result;
+}
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error(`Invalid cron: expected 5 fields, got ${parts.length}`);
+  return {
+    minutes: parseField(parts[0], 0, 59),
+    hours: parseField(parts[1], 0, 23),
+    daysOfMonth: parseField(parts[2], 1, 31),
+    months: parseField(parts[3], 1, 12),
+    daysOfWeek: parseField(parts[4], 0, 6)
+  };
+}
+function matchesCron(schedule, date) {
+  return schedule.minutes.has(date.getMinutes()) && schedule.hours.has(date.getHours()) && schedule.daysOfMonth.has(date.getDate()) && schedule.months.has(date.getMonth() + 1) && schedule.daysOfWeek.has(date.getDay());
+}
+
+// src/extra/sources.ts
+function sourceOpts(opts) {
+  return { describeKind: "producer", ...opts };
+}
+function fromTimer(ms, opts) {
+  const { signal, period, ...rest } = opts ?? {};
+  return producer((_d, a) => {
+    let done = false;
+    let count = 0;
+    let t;
+    let iv;
+    const cleanup = () => {
+      done = true;
+      if (t !== void 0) clearTimeout(t);
+      if (iv !== void 0) clearInterval(iv);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = () => {
+      if (done) return;
+      a.emit(count++);
+      if (period != null) {
+        iv = setInterval(() => {
+          if (done) return;
+          a.emit(count++);
+        }, period);
+      } else {
+        done = true;
+        signal?.removeEventListener("abort", onAbort);
+        queueMicrotask(() => a.down([[COMPLETE]]));
+      }
+    };
+    const onAbort = () => {
+      if (done) return;
+      cleanup();
+      a.down([[ERROR, signal.reason]]);
+    };
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    t = setTimeout(finish, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    return cleanup;
+  }, sourceOpts(rest));
+}
+function fromCron(expr, opts) {
+  const schedule = parseCron(expr);
+  const { tickMs: tickOpt, output, ...rest } = opts ?? {};
+  const tickMs = tickOpt ?? 6e4;
+  const emitDate = output === "date";
+  return producer(
+    (_d, a) => {
+      let lastFiredKey = -1;
+      const check = () => {
+        const now = /* @__PURE__ */ new Date();
+        const key = now.getFullYear() * 1e8 + (now.getMonth() + 1) * 1e6 + now.getDate() * 1e4 + now.getHours() * 100 + now.getMinutes();
+        if (key !== lastFiredKey && matchesCron(schedule, now)) {
+          lastFiredKey = key;
+          a.emit(emitDate ? now : wallClockNs());
+        }
+      };
+      check();
+      const id = setInterval(check, tickMs);
+      return () => clearInterval(id);
+    },
+    { ...sourceOpts(rest), name: rest.name ?? `cron:${expr}` }
+  );
+}
+
+// src/compat/nestjs/explorer.ts
+var scheduleSeq = 0;
+var GraphReflyEventExplorer = class {
+  constructor(graph, moduleRef) {
+    this.graph = graph;
+    this.moduleRef = moduleRef;
+  }
+  disposers = [];
+  scheduleNodeNames = [];
+  onModuleInit() {
+    this.wireEvents();
+    this.wireIntervals();
+    this.wireCrons();
+    this.wireCqrsCommands();
+    this.wireCqrsEvents();
+    this.wireCqrsQueries();
+    this.wireCqrsSagas();
+  }
+  onModuleDestroy() {
+    for (const dispose of this.disposers) dispose();
+    this.disposers.length = 0;
+    for (const name of this.scheduleNodeNames) {
+      try {
+        this.graph.remove(name);
+      } catch {
+      }
+    }
+    this.scheduleNodeNames.length = 0;
+  }
+  // -----------------------------------------------------------------------
+  // @OnGraphEvent — reactive subscription via graph.observe()
+  // -----------------------------------------------------------------------
+  wireEvents() {
+    for (const [ctor, metas] of EVENT_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireEventHandler(instance, meta);
+      }
+    }
+  }
+  wireEventHandler(instance, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const handle = this.observeNode(meta.nodeName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA) {
+          bound(m[1]);
+        }
+      }
+    });
+    this.disposers.push(unsub);
+  }
+  // -----------------------------------------------------------------------
+  // @GraphInterval — reactive via fromTimer central timer primitive
+  // -----------------------------------------------------------------------
+  wireIntervals() {
+    for (const [ctor, metas] of INTERVAL_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireIntervalHandler(instance, ctor, meta);
+      }
+    }
+  }
+  wireIntervalHandler(instance, ctor, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const className = ctor.name ?? "anonymous";
+    const nodeName = `__schedule__.${className}.${String(meta.methodKey)}.${scheduleSeq++}`;
+    const timerNode = fromTimer(meta.ms, { period: meta.ms, name: nodeName });
+    this.graph.add(nodeName, timerNode);
+    this.scheduleNodeNames.push(nodeName);
+    const handle = this.observeNode(nodeName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA) bound(m[1]);
+      }
+    });
+    this.disposers.push(unsub);
+  }
+  // -----------------------------------------------------------------------
+  // @GraphCron — reactive via fromCron central timer primitive
+  // -----------------------------------------------------------------------
+  wireCrons() {
+    for (const [ctor, metas] of CRON_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireCronHandler(instance, ctor, meta);
+      }
+    }
+  }
+  wireCronHandler(instance, ctor, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const className = ctor.name ?? "anonymous";
+    const nodeName = `__schedule__.${className}.${String(meta.methodKey)}.${scheduleSeq++}`;
+    const cronNode = fromCron(meta.expr, { name: nodeName });
+    this.graph.add(nodeName, cronNode);
+    this.scheduleNodeNames.push(nodeName);
+    const handle = this.observeNode(nodeName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA) bound(m[1]);
+      }
+    });
+    this.disposers.push(unsub);
+  }
+  // -----------------------------------------------------------------------
+  // @CommandHandler — register method as CqrsGraph command handler
+  // -----------------------------------------------------------------------
+  wireCqrsCommands() {
+    for (const [ctor, metas] of COMMAND_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireCqrsCommand(instance, meta);
+      }
+    }
+  }
+  wireCqrsCommand(instance, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const cqrsGraph = this.resolveCqrsGraph(meta.cqrsName);
+    if (!cqrsGraph) return;
+    cqrsGraph.command(meta.commandName, bound);
+  }
+  // -----------------------------------------------------------------------
+  // @EventHandler — subscribe method to CQRS event stream
+  // -----------------------------------------------------------------------
+  wireCqrsEvents() {
+    for (const [ctor, metas] of CQRS_EVENT_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireCqrsEventHandler(instance, meta);
+      }
+    }
+  }
+  wireCqrsEventHandler(instance, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const cqrsGraph = this.resolveCqrsGraph(meta.cqrsName);
+    if (!cqrsGraph) return;
+    cqrsGraph.event(meta.eventName);
+    const eventNode = cqrsGraph.resolve(meta.eventName);
+    const currentSnap = eventNode.get();
+    const existingEntries = currentSnap?.value?.entries;
+    let lastSeq = existingEntries && existingEntries.length > 0 ? existingEntries[existingEntries.length - 1].seq : 0;
+    const handle = this.observeNodeOn(cqrsGraph, meta.eventName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA) {
+          const snap = m[1];
+          for (const entry of snap.value.entries) {
+            if (entry.seq > lastSeq) {
+              bound(entry);
+              lastSeq = entry.seq;
+            }
+          }
+        }
+      }
+    });
+    this.disposers.push(unsub);
+  }
+  // -----------------------------------------------------------------------
+  // @QueryHandler — subscribe method to CQRS projection changes
+  // -----------------------------------------------------------------------
+  wireCqrsQueries() {
+    for (const [ctor, metas] of QUERY_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireCqrsQuery(instance, meta);
+      }
+    }
+  }
+  wireCqrsQuery(instance, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const cqrsGraph = this.resolveCqrsGraph(meta.cqrsName);
+    if (!cqrsGraph) return;
+    const handle = this.observeNodeOn(cqrsGraph, meta.projectionName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === DATA) {
+          bound(m[1]);
+        }
+      }
+    });
+    this.disposers.push(unsub);
+  }
+  // -----------------------------------------------------------------------
+  // @SagaHandler — register method as CqrsGraph saga (subgraph side effect)
+  // -----------------------------------------------------------------------
+  wireCqrsSagas() {
+    for (const [ctor, metas] of SAGA_HANDLERS) {
+      const instance = this.resolveInstance(ctor);
+      if (!instance) continue;
+      for (const meta of metas) {
+        this.wireCqrsSaga(instance, meta);
+      }
+    }
+  }
+  wireCqrsSaga(instance, meta) {
+    const method = instance[meta.methodKey];
+    if (typeof method !== "function") return;
+    const bound = method.bind(instance);
+    const cqrsGraph = this.resolveCqrsGraph(meta.cqrsName);
+    if (!cqrsGraph) return;
+    cqrsGraph.saga(meta.sagaName, meta.eventNames, bound);
+  }
+  // -----------------------------------------------------------------------
+  // Helpers
+  // -----------------------------------------------------------------------
+  observeNode(name) {
+    return this.graph.observe(name);
+  }
+  observeNodeOn(graph, name) {
+    return graph.observe(name);
+  }
+  resolveCqrsGraph(name) {
+    try {
+      return this.moduleRef.get(getGraphToken(name), { strict: false });
+    } catch {
+      console.warn(
+        `[GraphReFly] CqrsGraph "${name}" not found in DI \u2014 did you import GraphReflyModule.forCqrs({ name: "${name}" })?`
+      );
+      return null;
+    }
+  }
+  resolveInstance(ctor) {
+    try {
+      return this.moduleRef.get(ctor, { strict: false });
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/extra/backpressure.ts
+var nextLockId = 0;
+function createWatermarkController(sendUp, opts) {
+  if (opts.highWaterMark < 1) throw new RangeError("highWaterMark must be >= 1");
+  if (opts.lowWaterMark < 0) throw new RangeError("lowWaterMark must be >= 0");
+  if (opts.lowWaterMark >= opts.highWaterMark)
+    throw new RangeError("lowWaterMark must be < highWaterMark");
+  const lockId = /* @__PURE__ */ Symbol(`bp-${++nextLockId}`);
+  let pending = 0;
+  let paused = false;
+  return {
+    onEnqueue() {
+      pending += 1;
+      if (!paused && pending >= opts.highWaterMark) {
+        paused = true;
+        sendUp([[PAUSE, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    onDequeue() {
+      if (pending > 0) pending -= 1;
+      if (paused && pending <= opts.lowWaterMark) {
+        paused = false;
+        sendUp([[RESUME, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    get pending() {
+      return pending;
+    },
+    get paused() {
+      return paused;
+    },
+    dispose() {
+      if (paused) {
+        paused = false;
+        sendUp([[RESUME, lockId]]);
+      }
+    }
+  };
+}
+
+// src/compat/nestjs/gateway.ts
+function observeSSE(graph, path, opts) {
+  const { actor, serialize = defaultSerialize, keepAliveMs, signal } = opts ?? {};
+  const encoder = new TextEncoder();
+  let stop;
+  const useBackpressure = opts?.highWaterMark != null;
+  let wm;
+  let pullResolve;
+  const taggedBuf = [];
+  let closed = false;
+  return new ReadableStream({
+    start(controller) {
+      let keepAlive;
+      let unsub = () => {
+      };
+      const close = () => {
+        if (closed) return;
+        closed = true;
+        if (keepAlive !== void 0) clearInterval(keepAlive);
+        signal?.removeEventListener("abort", onAbort);
+        unsub();
+        wm?.dispose();
+        pullResolve?.();
+        pullResolve = void 0;
+        for (const entry of taggedBuf) controller.enqueue(entry.frame);
+        taggedBuf.length = 0;
+        controller.close();
+      };
+      stop = close;
+      const onAbort = () => close();
+      const handle = graph.observe(path, { actor });
+      if (useBackpressure) {
+        wm = createWatermarkController((msgs) => handle.up(msgs), {
+          highWaterMark: opts.highWaterMark,
+          lowWaterMark: opts.lowWaterMark ?? Math.floor(opts.highWaterMark / 2)
+        });
+      }
+      unsub = handle.subscribe((msgs) => {
+        for (const msg of msgs) {
+          if (closed) return;
+          const t = msg[0];
+          if (t === DATA) {
+            const frame = encoder.encode(sseFrame("data", serialize(msg[1])));
+            if (useBackpressure) {
+              taggedBuf.push({ frame, counted: true });
+              wm.onEnqueue();
+              pullResolve?.();
+              pullResolve = void 0;
+            } else {
+              controller.enqueue(frame);
+            }
+          } else if (t === ERROR) {
+            const frame = encoder.encode(sseFrame("error", serialize(msg[1])));
+            if (useBackpressure) {
+              taggedBuf.push({ frame, counted: false });
+              pullResolve?.();
+              pullResolve = void 0;
+            } else {
+              controller.enqueue(frame);
+            }
+            close();
+            return;
+          } else if (t === COMPLETE || t === TEARDOWN) {
+            if (t === COMPLETE) {
+              const frame = encoder.encode(sseFrame("complete"));
+              if (useBackpressure) {
+                taggedBuf.push({ frame, counted: false });
+                pullResolve?.();
+                pullResolve = void 0;
+              } else {
+                controller.enqueue(frame);
+              }
+            }
+            close();
+            return;
+          }
+        }
+      });
+      if (keepAliveMs !== void 0 && keepAliveMs > 0) {
+        keepAlive = setInterval(() => {
+          if (closed) return;
+          if (useBackpressure) {
+            taggedBuf.push({ frame: encoder.encode(": keepalive\n\n"), counted: false });
+            pullResolve?.();
+            pullResolve = void 0;
+          } else {
+            controller.enqueue(encoder.encode(": keepalive\n\n"));
+          }
+        }, keepAliveMs);
+      }
+      if (signal?.aborted) onAbort();
+      else signal?.addEventListener("abort", onAbort, { once: true });
+    },
+    pull(controller) {
+      if (!useBackpressure) return;
+      if (closed) return;
+      if (taggedBuf.length > 0) {
+        const entry = taggedBuf.shift();
+        controller.enqueue(entry.frame);
+        if (entry.counted) wm.onDequeue();
+        return;
+      }
+      return new Promise((resolve) => {
+        pullResolve = resolve;
+      });
+    },
+    cancel() {
+      try {
+        stop?.();
+      } catch {
+      }
+    }
+  });
+}
+function observeSubscription(graph, path, opts) {
+  const { actor, filter } = opts ?? {};
+  const queue = [];
+  const waiters = [];
+  let disposed = false;
+  const handle = graph.observe(path, { actor });
+  const wm = opts?.highWaterMark != null ? createWatermarkController((msgs) => handle.up(msgs), {
+    highWaterMark: opts.highWaterMark,
+    lowWaterMark: opts.lowWaterMark ?? Math.floor(opts.highWaterMark / 2)
+  }) : void 0;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    wm?.dispose();
+    unsub();
+  };
+  const push = (item) => {
+    if (disposed) return;
+    if (waiters.length > 0) {
+      const w = waiters.shift();
+      if (item.done && item.error) w.reject(item.error);
+      else if (item.done) w.resolve({ done: true, value: void 0 });
+      else w.resolve({ done: false, value: item.value });
+    } else {
+      queue.push(item);
+      if (!item.done) wm?.onEnqueue();
+    }
+  };
+  const unsub = handle.subscribe((msgs) => {
+    for (const msg of msgs) {
+      const t = msg[0];
+      if (t === DATA) {
+        const value = msg[1];
+        if (filter && !filter(value)) continue;
+        push({ done: false, value });
+      } else if (t === ERROR) {
+        const err = msg[1] instanceof Error ? msg[1] : new Error(String(msg[1]));
+        push({ done: true, error: err });
+        dispose();
+        return;
+      } else if (t === COMPLETE || t === TEARDOWN) {
+        push({ done: true });
+        dispose();
+        return;
+      }
+    }
+  });
+  const iterator = {
+    next() {
+      if (queue.length > 0) {
+        const item = queue.shift();
+        if (!item.done) wm?.onDequeue();
+        if (item.done && item.error) return Promise.reject(item.error);
+        return Promise.resolve(
+          item.done ? { done: true, value: void 0 } : { done: false, value: item.value }
+        );
+      }
+      if (disposed) return Promise.resolve({ done: true, value: void 0 });
+      return new Promise((resolve, reject) => {
+        waiters.push({ resolve, reject });
+      });
+    },
+    return() {
+      dispose();
+      for (const w of waiters) w.resolve({ done: true, value: void 0 });
+      waiters.length = 0;
+      return Promise.resolve({ done: true, value: void 0 });
+    },
+    throw(err) {
+      dispose();
+      return Promise.reject(err);
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    }
+  };
+  return iterator;
+}
+var ObserveGateway = class {
+  constructor(graph, opts) {
+    this.graph = graph;
+    this.extractActor = opts?.extractActor ?? (() => void 0);
+    this.parse = opts?.parse ?? defaultParseCommand;
+    this.highWaterMark = opts?.highWaterMark;
+    this.lowWaterMark = opts?.lowWaterMark;
+  }
+  clients = /* @__PURE__ */ new Map();
+  extractActor;
+  parse;
+  highWaterMark;
+  lowWaterMark;
+  /**
+   * Register a new client. Call from `handleConnection`.
+   */
+  handleConnection(client) {
+    if (!this.clients.has(client)) {
+      this.clients.set(client, /* @__PURE__ */ new Map());
+    }
+  }
+  /**
+   * Unregister a client and dispose all its subscriptions. Call from `handleDisconnect`.
+   */
+  handleDisconnect(client) {
+    const subs = this.clients.get(client);
+    if (!subs) return;
+    for (const entry of subs.values()) {
+      entry.wm?.dispose();
+      entry.unsub();
+    }
+    this.clients.delete(client);
+  }
+  /**
+   * Handle an incoming client message (subscribe/unsubscribe/ack command).
+   *
+   * @param client - The WebSocket client reference.
+   * @param raw - Raw message data (string or parsed object).
+   * @param send - Function to send a message back to the client.
+   *   Defaults to `client.send(JSON.stringify(msg))`.
+   */
+  handleMessage(client, raw, send) {
+    const sender = send ?? defaultSend.bind(null, client);
+    let cmd;
+    try {
+      cmd = typeof raw === "string" ? this.parse(raw) : raw;
+    } catch {
+      sender({ type: "err", message: "invalid command" });
+      return;
+    }
+    if (cmd.type === "subscribe") {
+      this.subscribe(client, cmd.path, sender);
+    } else if (cmd.type === "unsubscribe") {
+      this.unsubscribe(client, cmd.path, sender);
+    } else if (cmd.type === "ack") {
+      this.ack(client, cmd.path, cmd.count ?? 1);
+    } else {
+      sender({ type: "err", message: `unknown command type: ${cmd.type}` });
+    }
+  }
+  /**
+   * Number of active subscriptions for a client. Useful for tests.
+   */
+  subscriptionCount(client) {
+    return this.clients.get(client)?.size ?? 0;
+  }
+  /**
+   * Dispose all clients and subscriptions.
+   */
+  destroy() {
+    for (const [client] of this.clients) {
+      this.handleDisconnect(client);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  subscribe(client, path, send) {
+    let subs = this.clients.get(client);
+    if (!subs) {
+      subs = /* @__PURE__ */ new Map();
+      this.clients.set(client, subs);
+    }
+    if (subs.has(path)) {
+      send({ type: "subscribed", path });
+      return;
+    }
+    const actor = this.extractActor(client);
+    let handle;
+    try {
+      handle = this.graph.observe(path, { actor });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      send({ type: "err", message });
+      return;
+    }
+    const wm = this.highWaterMark != null ? createWatermarkController((msgs) => handle.up(msgs), {
+      highWaterMark: this.highWaterMark,
+      lowWaterMark: this.lowWaterMark ?? Math.floor(this.highWaterMark / 2)
+    }) : void 0;
+    const cleanup = () => {
+      wm?.dispose();
+      unsub();
+      subs.delete(path);
+    };
+    const unsub = handle.subscribe((msgs) => {
+      for (const msg of msgs) {
+        const t = msg[0];
+        if (t === DATA) {
+          wm?.onEnqueue();
+          trySend(send, { type: "data", path, value: msg[1] });
+        } else if (t === ERROR) {
+          const errMsg = msg[1] instanceof Error ? msg[1].message : String(msg[1]);
+          trySend(send, { type: "error", path, error: errMsg });
+          cleanup();
+          return;
+        } else if (t === COMPLETE || t === TEARDOWN) {
+          trySend(send, { type: "complete", path });
+          cleanup();
+          return;
+        }
+      }
+    });
+    subs.set(path, { unsub, wm });
+    send({ type: "subscribed", path });
+  }
+  unsubscribe(client, path, send) {
+    const subs = this.clients.get(client);
+    const entry = subs?.get(path);
+    if (entry) {
+      entry.wm?.dispose();
+      entry.unsub();
+      subs.delete(path);
+    }
+    send({ type: "unsubscribed", path });
+  }
+  ack(client, path, count) {
+    const entry = this.clients.get(client)?.get(path);
+    if (!entry?.wm) return;
+    const n = Math.min(Math.max(0, Math.floor(count)), 1024);
+    for (let i = 0; i < n; i++) entry.wm.onDequeue();
+  }
+};
+function defaultSerialize(value) {
+  if (value instanceof Error) return value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function sseFrame(event, data) {
+  let frame = `event: ${event}
+`;
+  if (data !== void 0) {
+    for (const line of data.split("\n")) {
+      frame += `data: ${line}
+`;
+    }
+  }
+  frame += "\n";
+  return frame;
+}
+function defaultParseCommand(data) {
+  return JSON.parse(data);
+}
+function defaultSend(client, msg) {
+  try {
+    client.send(JSON.stringify(msg));
+  } catch {
+  }
+}
+function trySend(send, msg) {
+  try {
+    send(msg);
+  } catch {
+  }
+}
+
+// src/compat/nestjs/guard.ts
+var ACTOR_KEY = "graphReflyActor";
+function fromJwtPayload(mapping) {
+  return (context) => {
+    const req = context.switchToHttp().getRequest();
+    const user = req?.user;
+    if (user == null) return void 0;
+    if (mapping) return mapping(user);
+    return user;
+  };
+}
+function fromHeader(headerName = "x-graphrefly-actor") {
+  return (context) => {
+    const req = context.switchToHttp().getRequest();
+    const raw = req?.headers?.[headerName.toLowerCase()];
+    if (typeof raw !== "string" || raw.length === 0) return void 0;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  };
+}
+function getActor(req) {
+  const actor = req?.[ACTOR_KEY];
+  return actor != null ? normalizeActor(actor) : DEFAULT_ACTOR;
+}
+var GraphReflyGuardImpl = class {
+  constructor(extractor) {
+    this.extractor = extractor;
+  }
+  canActivate(context) {
+    const actor = normalizeActor(this.extractor(context));
+    const req = context.switchToHttp().getRequest();
+    if (req != null) {
+      req[ACTOR_KEY] = actor;
+    }
+    return true;
+  }
+};
+function GraphReflyGuard(extractor) {
+  return new GraphReflyGuardImpl(extractor ?? fromJwtPayload());
+}
+
+// src/compat/nestjs/module.ts
+var import_common2 = require("@nestjs/common");
+var import_core2 = require("@nestjs/core");
+
+// src/core/dynamic-node.ts
+var DynamicNodeImpl = class {
+  _optsName;
+  _registryName;
+  _describeKind;
+  meta;
+  _fn;
+  _equals;
+  _resubscribable;
+  _resetOnTeardown;
+  _autoComplete;
+  _onMessage;
+  _onResubscribe;
+  /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
+  _guard;
+  _lastMutation;
+  _inspectorHook;
+  // Sink tracking
+  _sinkCount = 0;
+  _singleDepSinkCount = 0;
+  _singleDepSinks = /* @__PURE__ */ new WeakSet();
+  // Actions object (for onMessage handler)
+  _actions;
+  _boundEmitToSinks;
+  // Mutable state
+  _cached;
+  _status = "disconnected";
+  _terminal = false;
+  _connected = false;
+  _rewiring = false;
+  // re-entrancy guard
+  // Dynamic deps tracking
+  _deps = [];
+  _depUnsubs = [];
+  _depIndexMap = /* @__PURE__ */ new Map();
+  // node → index in _deps
+  _dirtyBits = /* @__PURE__ */ new Set();
+  _settledBits = /* @__PURE__ */ new Set();
+  _completeBits = /* @__PURE__ */ new Set();
+  // Sinks
+  _sinks = null;
+  constructor(fn, opts) {
+    this._fn = fn;
+    this._optsName = opts.name;
+    this._describeKind = opts.describeKind;
+    this._equals = opts.equals ?? Object.is;
+    this._resubscribable = opts.resubscribable ?? false;
+    this._resetOnTeardown = opts.resetOnTeardown ?? false;
+    this._autoComplete = opts.completeWhenDepsComplete ?? true;
+    this._onMessage = opts.onMessage;
+    this._onResubscribe = opts.onResubscribe;
+    this._guard = opts.guard;
+    this._inspectorHook = void 0;
+    const meta = {};
+    for (const [k, v] of Object.entries(opts.meta ?? {})) {
+      meta[k] = node({
+        initial: v,
+        name: `${opts.name ?? "dynamicNode"}:meta:${k}`,
+        describeKind: "state",
+        ...opts.guard != null ? { guard: opts.guard } : {}
+      });
+    }
+    Object.freeze(meta);
+    this.meta = meta;
+    const self = this;
+    this._actions = {
+      down(messages) {
+        self._downInternal(messages);
+      },
+      emit(value) {
+        self._emitAutoValue(value);
+      },
+      up(messages) {
+        for (const dep of self._deps) {
+          dep.up?.(messages, { internal: true });
+        }
+      }
+    };
+    this._boundEmitToSinks = this._emitToSinks.bind(this);
+  }
+  get name() {
+    return this._registryName ?? this._optsName;
+  }
+  /** @internal */
+  _assignRegistryName(localName) {
+    if (this._optsName !== void 0 || this._registryName !== void 0) return;
+    this._registryName = localName;
+  }
+  /**
+   * @internal Attach/remove inspector hook for graph-level observability.
+   * Returns a disposer that restores the previous hook.
+   */
+  _setInspectorHook(hook) {
+    const prev = this._inspectorHook;
+    this._inspectorHook = hook;
+    return () => {
+      if (this._inspectorHook === hook) {
+        this._inspectorHook = prev;
+      }
+    };
+  }
+  get status() {
+    return this._status;
+  }
+  get lastMutation() {
+    return this._lastMutation;
+  }
+  /** Versioning not yet supported on DynamicNodeImpl. */
+  get v() {
+    return void 0;
+  }
+  hasGuard() {
+    return this._guard != null;
+  }
+  allowsObserve(actor) {
+    if (this._guard == null) return true;
+    return this._guard(normalizeActor(actor), "observe");
+  }
+  get() {
+    return this._cached;
+  }
+  down(messages, options) {
+    if (messages.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      const delivery = options?.delivery ?? "write";
+      const action = delivery === "signal" ? "signal" : "write";
+      if (!this._guard(actor, action)) {
+        throw new GuardDenied({ actor, action, nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    this._downInternal(messages);
+  }
+  _downInternal(messages) {
+    if (messages.length === 0) return;
+    let sinkMessages = messages;
+    if (this._terminal && !this._resubscribable) {
+      const pass = messages.filter((m) => m[0] === TEARDOWN || m[0] === INVALIDATE);
+      if (pass.length === 0) return;
+      sinkMessages = pass;
+    }
+    this._handleLocalLifecycle(sinkMessages);
+    if (this._canSkipDirty()) {
+      let hasPhase2 = false;
+      for (let i = 0; i < sinkMessages.length; i++) {
+        const t = sinkMessages[i][0];
+        if (t === DATA || t === RESOLVED) {
+          hasPhase2 = true;
+          break;
+        }
+      }
+      if (hasPhase2) {
+        const filtered = [];
+        for (let i = 0; i < sinkMessages.length; i++) {
+          if (sinkMessages[i][0] !== DIRTY) filtered.push(sinkMessages[i]);
+        }
+        if (filtered.length > 0) {
+          emitWithBatch(this._boundEmitToSinks, filtered);
+        }
+        return;
+      }
+    }
+    emitWithBatch(this._boundEmitToSinks, sinkMessages);
+  }
+  _canSkipDirty() {
+    return this._sinkCount === 1 && this._singleDepSinkCount === 1;
+  }
+  subscribe(sink, hints) {
+    if (hints?.actor != null && this._guard != null) {
+      const actor = normalizeActor(hints.actor);
+      if (!this._guard(actor, "observe")) {
+        throw new GuardDenied({ actor, action: "observe", nodeName: this.name });
+      }
+    }
+    if (this._terminal && this._resubscribable) {
+      this._terminal = false;
+      this._status = "disconnected";
+      this._onResubscribe?.();
+    }
+    this._sinkCount += 1;
+    if (hints?.singleDep) {
+      this._singleDepSinkCount += 1;
+      this._singleDepSinks.add(sink);
+    }
+    if (this._sinks == null) {
+      this._sinks = sink;
+    } else if (typeof this._sinks === "function") {
+      this._sinks = /* @__PURE__ */ new Set([this._sinks, sink]);
+    } else {
+      this._sinks.add(sink);
+    }
+    if (!this._connected) {
+      this._connect();
+    }
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this._sinkCount -= 1;
+      if (this._singleDepSinks.has(sink)) {
+        this._singleDepSinkCount -= 1;
+        this._singleDepSinks.delete(sink);
+      }
+      if (this._sinks == null) return;
+      if (typeof this._sinks === "function") {
+        if (this._sinks === sink) this._sinks = null;
+      } else {
+        this._sinks.delete(sink);
+        if (this._sinks.size === 1) {
+          const [only] = this._sinks;
+          this._sinks = only;
+        } else if (this._sinks.size === 0) {
+          this._sinks = null;
+        }
+      }
+      if (this._sinks == null) {
+        this._disconnect();
+      }
+    };
+  }
+  up(messages, options) {
+    if (this._deps.length === 0) return;
+    if (!options?.internal && this._guard != null) {
+      const actor = normalizeActor(options?.actor);
+      if (!this._guard(actor, "write")) {
+        throw new GuardDenied({ actor, action: "write", nodeName: this.name });
+      }
+      this._lastMutation = { actor, timestamp_ns: wallClockNs() };
+    }
+    for (const dep of this._deps) {
+      dep.up?.(messages, options);
+    }
+  }
+  unsubscribe() {
+    this._disconnect();
+  }
+  // --- Private methods ---
+  _emitToSinks(messages) {
+    if (this._sinks == null) return;
+    if (typeof this._sinks === "function") {
+      this._sinks(messages);
+      return;
+    }
+    const snapshot = [...this._sinks];
+    for (const sink of snapshot) {
+      sink(messages);
+    }
+  }
+  _handleLocalLifecycle(messages) {
+    for (const m of messages) {
+      const t = m[0];
+      if (t === DATA) this._cached = m[1];
+      if (t === INVALIDATE) {
+        this._cached = void 0;
+      }
+      if (t === DATA || t === RESOLVED) {
+        this._status = "settled";
+      } else if (t === DIRTY) {
+        this._status = "dirty";
+      } else if (t === COMPLETE) {
+        this._status = "completed";
+        this._terminal = true;
+      } else if (t === ERROR) {
+        this._status = "errored";
+        this._terminal = true;
+      }
+      if (t === TEARDOWN) {
+        if (this._resetOnTeardown) this._cached = void 0;
+        try {
+          this._propagateToMeta(t);
+        } finally {
+          this._disconnect();
+        }
+      }
+      if (t !== TEARDOWN && propagatesToMeta(t)) {
+        this._propagateToMeta(t);
+      }
+    }
+  }
+  /** Propagate a signal to all companion meta nodes (best-effort). */
+  _propagateToMeta(t) {
+    for (const metaNode of Object.values(this.meta)) {
+      try {
+        metaNode.down([[t]], { internal: true });
+      } catch {
+      }
+    }
+  }
+  _emitAutoValue(value) {
+    const wasDirty = this._status === "dirty";
+    const unchanged = this._equals(this._cached, value);
+    if (unchanged) {
+      this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
+      return;
+    }
+    this._cached = value;
+    this._downInternal(wasDirty ? [[DATA, value]] : [[DIRTY], [DATA, value]]);
+  }
+  _connect() {
+    if (this._connected) return;
+    this._connected = true;
+    this._status = "settled";
+    this._dirtyBits.clear();
+    this._settledBits.clear();
+    this._completeBits.clear();
+    this._runFn();
+  }
+  _disconnect() {
+    if (!this._connected) return;
+    for (const unsub of this._depUnsubs) unsub();
+    this._depUnsubs = [];
+    this._deps = [];
+    this._depIndexMap.clear();
+    this._dirtyBits.clear();
+    this._settledBits.clear();
+    this._completeBits.clear();
+    this._connected = false;
+    this._status = "disconnected";
+  }
+  _runFn() {
+    if (this._terminal && !this._resubscribable) return;
+    if (this._rewiring) return;
+    const trackedDeps = [];
+    const trackedSet = /* @__PURE__ */ new Set();
+    const get = (dep) => {
+      if (!trackedSet.has(dep)) {
+        trackedSet.add(dep);
+        trackedDeps.push(dep);
+      }
+      return dep.get();
+    };
+    try {
+      const depValues = [];
+      for (const dep of this._deps) {
+        depValues.push(dep.get());
+      }
+      this._inspectorHook?.({ kind: "run", depValues });
+      const result = this._fn(get);
+      this._rewire(trackedDeps);
+      if (result === void 0) return;
+      this._emitAutoValue(result);
+    } catch (err) {
+      this._downInternal([[ERROR, err]]);
+    }
+  }
+  _rewire(newDeps) {
+    this._rewiring = true;
+    try {
+      const oldMap = this._depIndexMap;
+      const newMap = /* @__PURE__ */ new Map();
+      const newUnsubs = [];
+      for (let i = 0; i < newDeps.length; i++) {
+        const dep = newDeps[i];
+        newMap.set(dep, i);
+        const oldIdx = oldMap.get(dep);
+        if (oldIdx !== void 0) {
+          newUnsubs.push(this._depUnsubs[oldIdx]);
+          this._depUnsubs[oldIdx] = () => {
+          };
+        } else {
+          const idx = i;
+          const unsub = dep.subscribe((msgs) => this._handleDepMessages(idx, msgs));
+          newUnsubs.push(unsub);
+        }
+      }
+      for (const [dep, oldIdx] of oldMap) {
+        if (!newMap.has(dep)) {
+          this._depUnsubs[oldIdx]();
+        }
+      }
+      this._deps = newDeps;
+      this._depUnsubs = newUnsubs;
+      this._depIndexMap = newMap;
+      this._dirtyBits.clear();
+      this._settledBits.clear();
+      const newCompleteBits = /* @__PURE__ */ new Set();
+      for (const oldIdx of this._completeBits) {
+        const dep = [...oldMap.entries()].find(([, idx]) => idx === oldIdx)?.[0];
+        if (dep && newMap.has(dep)) {
+          newCompleteBits.add(newMap.get(dep));
+        }
+      }
+      this._completeBits = newCompleteBits;
+    } finally {
+      this._rewiring = false;
+    }
+  }
+  _handleDepMessages(index, messages) {
+    if (this._rewiring) return;
+    for (const msg of messages) {
+      this._inspectorHook?.({ kind: "dep_message", depIndex: index, message: msg });
+      const t = msg[0];
+      if (this._onMessage) {
+        try {
+          if (this._onMessage(msg, index, this._actions)) continue;
+        } catch (err) {
+          this._downInternal([[ERROR, err]]);
+          return;
+        }
+      }
+      if (t === DIRTY) {
+        this._dirtyBits.add(index);
+        this._settledBits.delete(index);
+        if (this._dirtyBits.size === 1) {
+          emitWithBatch(this._boundEmitToSinks, [[DIRTY]]);
+        }
+        continue;
+      }
+      if (t === DATA || t === RESOLVED) {
+        if (!this._dirtyBits.has(index)) {
+          this._dirtyBits.add(index);
+          emitWithBatch(this._boundEmitToSinks, [[DIRTY]]);
+        }
+        this._settledBits.add(index);
+        if (this._allDirtySettled()) {
+          this._dirtyBits.clear();
+          this._settledBits.clear();
+          this._runFn();
+        }
+        continue;
+      }
+      if (t === COMPLETE) {
+        this._completeBits.add(index);
+        this._dirtyBits.delete(index);
+        this._settledBits.delete(index);
+        if (this._allDirtySettled()) {
+          this._dirtyBits.clear();
+          this._settledBits.clear();
+          this._runFn();
+        }
+        if (this._autoComplete && this._completeBits.size >= this._deps.length && this._deps.length > 0) {
+          this._downInternal([[COMPLETE]]);
+        }
+        continue;
+      }
+      if (t === ERROR) {
+        this._downInternal([msg]);
+        continue;
+      }
+      if (t === INVALIDATE || t === TEARDOWN || t === PAUSE || t === RESUME) {
+        this._downInternal([msg]);
+        continue;
+      }
+      this._downInternal([msg]);
+    }
+  }
+  _allDirtySettled() {
+    if (this._dirtyBits.size === 0) return false;
+    for (const idx of this._dirtyBits) {
+      if (!this._settledBits.has(idx)) return false;
+    }
+    return true;
+  }
+};
+
+// src/core/meta.ts
+function inferDescribeType(n) {
+  if (n._describeKind != null) return n._describeKind;
+  if (!n._hasDeps) return n._fn != null ? "producer" : "state";
+  if (n._fn == null) return "derived";
+  if (n._manualEmitUsed) return "operator";
+  return "derived";
+}
+function metaSnapshot(node2) {
+  const out = {};
+  for (const [key, child] of Object.entries(node2.meta)) {
+    try {
+      out[key] = child.get();
+    } catch {
+    }
+  }
+  return out;
+}
+function describeNode(node2) {
+  const meta = { ...metaSnapshot(node2) };
+  const guard = node2 instanceof NodeImpl && node2._guard || node2 instanceof DynamicNodeImpl && node2._guard || void 0;
+  if (guard != null && meta.access === void 0) {
+    meta.access = accessHintForGuard(guard);
+  }
+  let type = "state";
+  let deps = [];
+  if (node2 instanceof NodeImpl) {
+    type = inferDescribeType(node2);
+    deps = node2._deps.map((d) => d.name ?? "");
+  } else if (node2 instanceof DynamicNodeImpl) {
+    type = node2._describeKind ?? "derived";
+    deps = [];
+  }
+  const out = {
+    type,
+    status: node2.status,
+    deps,
+    meta
+  };
+  if (node2.name != null) {
+    out.name = node2.name;
+  }
+  try {
+    out.value = node2.get();
+  } catch {
+  }
+  if (node2.v != null) {
+    const vInfo = { id: node2.v.id, version: node2.v.version };
+    if ("cid" in node2.v) {
+      vInfo.cid = node2.v.cid;
+      vInfo.prev = node2.v.prev;
+    }
+    out.v = vInfo;
+  }
+  return out;
+}
+
+// src/graph/graph.ts
+var PATH_SEP = "::";
+var GRAPH_META_SEGMENT = "__meta__";
+var SNAPSHOT_VERSION = 1;
+function parseSnapshotEnvelope(data) {
+  if (data.version !== SNAPSHOT_VERSION) {
+    throw new Error(
+      `unsupported snapshot version ${String(data.version)} (expected ${SNAPSHOT_VERSION})`
+    );
+  }
+  for (const key of ["name", "nodes", "edges", "subgraphs"]) {
+    if (!(key in data)) {
+      throw new Error(`snapshot missing required key "${key}"`);
+    }
+  }
+  if (typeof data.name !== "string") {
+    throw new TypeError(`snapshot 'name' must be a string`);
+  }
+  if (typeof data.nodes !== "object" || data.nodes === null || Array.isArray(data.nodes)) {
+    throw new TypeError(`snapshot 'nodes' must be an object`);
+  }
+  if (!Array.isArray(data.edges)) {
+    throw new TypeError(`snapshot 'edges' must be an array`);
+  }
+  if (!Array.isArray(data.subgraphs)) {
+    throw new TypeError(`snapshot 'subgraphs' must be an array`);
+  }
+}
+function sortJsonValue(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const out = {};
+  for (const k of keys) {
+    out[k] = sortJsonValue(obj[k]);
+  }
+  return out;
+}
+function stableJsonStringify(value) {
+  return `${JSON.stringify(sortJsonValue(value))}
+`;
+}
+function escapeMermaidLabel(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+function escapeD2Label(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+function d2DirectionFromGraphDirection(direction) {
+  if (direction === "TD") return "down";
+  if (direction === "BT") return "up";
+  if (direction === "RL") return "left";
+  return "right";
+}
+function collectDiagramArrows(described) {
+  const seen = /* @__PURE__ */ new Set();
+  const arrows = [];
+  function add(from, to) {
+    const key = `${from}\0${to}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    arrows.push([from, to]);
+  }
+  for (const [path, info] of Object.entries(described.nodes)) {
+    const deps = info.deps;
+    if (deps) {
+      for (const dep of deps) add(dep, path);
+    }
+  }
+  for (const edge of described.edges) add(edge.from, edge.to);
+  return arrows;
+}
+function normalizeDiagramDirection(direction) {
+  if (direction === void 0) return "LR";
+  if (direction === "TD" || direction === "LR" || direction === "BT" || direction === "RL") {
+    return direction;
+  }
+  throw new Error(
+    `invalid diagram direction ${String(direction)}; expected one of: TD, LR, BT, RL`
+  );
+}
+function escapeRegexLiteral(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function globToRegex(pattern) {
+  let re = "^";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      re += ".*";
+      continue;
+    }
+    if (ch === "?") {
+      re += ".";
+      continue;
+    }
+    if (ch === "[") {
+      const end = pattern.indexOf("]", i + 1);
+      if (end <= i + 1) {
+        re += "\\[";
+        continue;
+      }
+      let cls = pattern.slice(i + 1, end);
+      if (cls.startsWith("!")) cls = `^${cls.slice(1)}`;
+      cls = cls.replace(/\\/g, "\\\\");
+      re += `[${cls}]`;
+      i = end;
+      continue;
+    }
+    re += escapeRegexLiteral(ch);
+  }
+  re += "$";
+  return new RegExp(re);
+}
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.buf = new Array(capacity);
+  }
+  buf;
+  head = 0;
+  _size = 0;
+  get size() {
+    return this._size;
+  }
+  push(item) {
+    const idx = (this.head + this._size) % this.capacity;
+    this.buf[idx] = item;
+    if (this._size < this.capacity) this._size++;
+    else this.head = (this.head + 1) % this.capacity;
+  }
+  toArray() {
+    const result = [];
+    for (let i = 0; i < this._size; i++) result.push(this.buf[(this.head + i) % this.capacity]);
+    return result;
+  }
+};
+var SPY_ANSI_THEME = {
+  data: "\x1B[32m",
+  dirty: "\x1B[33m",
+  resolved: "\x1B[36m",
+  complete: "\x1B[34m",
+  error: "\x1B[31m",
+  derived: "\x1B[35m",
+  path: "\x1B[90m",
+  reset: "\x1B[0m"
+};
+var SPY_NO_COLOR_THEME = {
+  data: "",
+  dirty: "",
+  resolved: "",
+  complete: "",
+  error: "",
+  derived: "",
+  path: "",
+  reset: ""
+};
+function describeData(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || value == null)
+    return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function resolveSpyTheme(theme) {
+  if (theme === "none") return SPY_NO_COLOR_THEME;
+  if (theme === "ansi" || theme == null) return SPY_ANSI_THEME;
+  return {
+    data: theme.data ?? "",
+    dirty: theme.dirty ?? "",
+    resolved: theme.resolved ?? "",
+    complete: theme.complete ?? "",
+    error: theme.error ?? "",
+    derived: theme.derived ?? "",
+    path: theme.path ?? "",
+    reset: theme.reset ?? ""
+  };
+}
+function assertLocalName(name, graphName, label) {
+  if (name === "") {
+    throw new Error(`Graph "${graphName}": ${label} name must be non-empty`);
+  }
+}
+function assertNoPathSep(name, graphName, label) {
+  if (name.includes(PATH_SEP)) {
+    throw new Error(
+      `Graph "${graphName}": ${label} "${name}" must not contain '${PATH_SEP}' (path separator)`
+    );
+  }
+}
+function assertNotReservedMetaSegment(name, graphName, label) {
+  if (name === GRAPH_META_SEGMENT) {
+    throw new Error(
+      `Graph "${graphName}": ${label} name "${GRAPH_META_SEGMENT}" is reserved for meta companion paths`
+    );
+  }
+}
+function assertConnectPathNotMeta(path, graphName) {
+  if (path.split(PATH_SEP).includes(GRAPH_META_SEGMENT)) {
+    throw new Error(
+      `Graph "${graphName}": connect/disconnect endpoints must be registered graph nodes, not meta paths (got "${path}")`
+    );
+  }
+}
+function splitPath(path, graphName) {
+  if (path === "") {
+    throw new Error(`Graph "${graphName}": resolve path must be non-empty`);
+  }
+  const segments = path.split(PATH_SEP);
+  for (const s of segments) {
+    if (s === "") {
+      throw new Error(`Graph "${graphName}": resolve path has empty segment`);
+    }
+  }
+  return segments;
+}
+function edgeKey(from, to) {
+  return `${from}	${to}`;
+}
+function parseEdgeKey(key) {
+  const i = key.indexOf("	");
+  return [key.slice(0, i), key.slice(i + 1)];
+}
+var META_FILTERED_TYPES = /* @__PURE__ */ new Set([TEARDOWN, INVALIDATE, COMPLETE, ERROR]);
+function filterMetaMessages(messages) {
+  const kept = messages.filter((m) => !META_FILTERED_TYPES.has(m[0]));
+  return kept;
+}
+function teardownMountedGraph(root) {
+  for (const child of root._mounts.values()) {
+    teardownMountedGraph(child);
+  }
+  for (const n of root._nodes.values()) {
+    n.down([[TEARDOWN]], { internal: true });
+  }
+}
+var Graph = class _Graph {
+  static _factories = [];
+  name;
+  opts;
+  /** @internal — exposed for {@link teardownMountedGraph} and cross-graph helpers. */
+  _nodes = /* @__PURE__ */ new Map();
+  _edges = /* @__PURE__ */ new Set();
+  /** @internal — exposed for {@link teardownMountedGraph}. */
+  _mounts = /* @__PURE__ */ new Map();
+  _autoCheckpointDisposers = /* @__PURE__ */ new Set();
+  _defaultVersioningLevel;
+  static registerFactory(pattern, factory) {
+    if (!pattern) {
+      throw new Error("Graph.registerFactory requires a non-empty pattern");
+    }
+    _Graph.unregisterFactory(pattern);
+    _Graph._factories.push({ pattern, re: globToRegex(pattern), factory });
+  }
+  static unregisterFactory(pattern) {
+    const i = _Graph._factories.findIndex((entry) => entry.pattern === pattern);
+    if (i >= 0) _Graph._factories.splice(i, 1);
+  }
+  /**
+   * @param name - Non-empty graph id (must not contain `::`).
+   * @param opts - Reserved for future hooks; currently unused.
+   */
+  constructor(name, opts) {
+    if (name === "") {
+      throw new Error("Graph name must be non-empty");
+    }
+    if (name.includes(PATH_SEP)) {
+      throw new Error(`Graph name must not contain '${PATH_SEP}' (got "${name}")`);
+    }
+    this.name = name;
+    this.opts = opts ?? {};
+  }
+  static _factoryForPath(path) {
+    for (let i = _Graph._factories.length - 1; i >= 0; i -= 1) {
+      const entry = _Graph._factories[i];
+      if (entry.re.test(path)) return entry.factory;
+    }
+    return void 0;
+  }
+  static _ownerForPath(root, path) {
+    const segments = path.split(PATH_SEP);
+    const local = segments.pop();
+    if (local == null || local.length === 0) {
+      throw new Error(`invalid snapshot path "${path}"`);
+    }
+    let owner = root;
+    for (const seg of segments) {
+      const next = owner._mounts.get(seg);
+      if (!next) throw new Error(`unknown mount "${seg}" in path "${path}"`);
+      owner = next;
+    }
+    return [owner, local];
+  }
+  /**
+   * Graphs reachable from this instance via nested {@link Graph.mount} (includes `this`).
+   */
+  _graphsReachableViaMounts(seen = /* @__PURE__ */ new Set()) {
+    if (seen.has(this)) return seen;
+    seen.add(this);
+    for (const child of this._mounts.values()) {
+      child._graphsReachableViaMounts(seen);
+    }
+    return seen;
+  }
+  /**
+   * Resolve an endpoint: returns `[owningGraph, localName, node]`.
+   * Accepts both local names and `::` qualified paths.
+   */
+  _resolveEndpoint(path) {
+    if (!path.includes(PATH_SEP)) {
+      const n = this._nodes.get(path);
+      if (!n) {
+        throw new Error(`Graph "${this.name}": unknown node "${path}"`);
+      }
+      return [this, path, n];
+    }
+    const segments = splitPath(path, this.name);
+    return this._resolveEndpointFromSegments(segments, path);
+  }
+  _resolveEndpointFromSegments(segments, fullPath) {
+    const head = segments[0];
+    const rest = segments.slice(1);
+    if (rest.length === 0) {
+      const n = this._nodes.get(head);
+      if (n) return [this, head, n];
+      throw new Error(`Graph "${this.name}": unknown node "${head}" (from path "${fullPath}")`);
+    }
+    const localN = this._nodes.get(head);
+    if (localN && rest.length > 0 && rest[0] === GRAPH_META_SEGMENT) {
+      return this._resolveMetaEndpointKeys(localN, head, rest, fullPath);
+    }
+    const child = this._mounts.get(head);
+    if (!child) {
+      if (this._nodes.has(head)) {
+        throw new Error(
+          `Graph "${this.name}": "${head}" is a node; trailing path "${rest.join(PATH_SEP)}" is invalid`
+        );
+      }
+      throw new Error(`Graph "${this.name}": unknown mount or node "${head}"`);
+    }
+    return child._resolveEndpointFromSegments(rest, fullPath);
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Node registry
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Registers a node under a local name. Fails if the name is already used,
+   * reserved by a mount, or the same node instance is already registered.
+   *
+   * @param name - Local key (no `::`).
+   * @param node - Node instance to own.
+   */
+  add(name, node2) {
+    assertLocalName(name, this.name, "add");
+    assertNoPathSep(name, this.name, "add");
+    assertNotReservedMetaSegment(name, this.name, "node");
+    if (this._mounts.has(name)) {
+      throw new Error(`Graph "${this.name}": name "${name}" is already a mount point`);
+    }
+    if (this._nodes.has(name)) {
+      throw new Error(`Graph "${this.name}": node "${name}" already exists`);
+    }
+    for (const [existingName, existing] of this._nodes) {
+      if (existing === node2) {
+        throw new Error(
+          `Graph "${this.name}": node instance already registered as "${existingName}"`
+        );
+      }
+    }
+    this._nodes.set(name, node2);
+    if (node2 instanceof NodeImpl) {
+      node2._assignRegistryName(name);
+      if (this._defaultVersioningLevel != null) {
+        node2._applyVersioning(this._defaultVersioningLevel);
+      }
+    }
+  }
+  /**
+   * Set a default versioning level for all nodes added to this graph (roadmap §6.0).
+   *
+   * Nodes already registered are retroactively upgraded. Nodes added later via
+   * {@link add} will inherit this level unless they already have versioning.
+   *
+   * **Scope:** Does not propagate to mounted subgraphs. Call `setVersioning`
+   * on each child graph separately if needed.
+   *
+   * @param level - `0` for V0, `1` for V1, or `undefined` to clear.
+   */
+  setVersioning(level) {
+    this._defaultVersioningLevel = level;
+    if (level == null) return;
+    for (const n of this._nodes.values()) {
+      if (n instanceof NodeImpl) {
+        n._applyVersioning(level);
+      }
+    }
+  }
+  /**
+   * Unregisters a node or unmounts a subgraph, drops incident edges, and sends
+   * `[[TEARDOWN]]` to the removed node or recursively through the mounted subtree (§3.2).
+   *
+   * @param name - Local mount or node name.
+   */
+  remove(name) {
+    assertLocalName(name, this.name, "remove");
+    assertNoPathSep(name, this.name, "remove");
+    const child = this._mounts.get(name);
+    if (child) {
+      this._mounts.delete(name);
+      const prefix = `${name}${PATH_SEP}`;
+      for (const key of [...this._edges]) {
+        const [from, to] = parseEdgeKey(key);
+        if (from === name || to === name || from.startsWith(prefix) || to.startsWith(prefix)) {
+          this._edges.delete(key);
+        }
+      }
+      teardownMountedGraph(child);
+      return;
+    }
+    const node2 = this._nodes.get(name);
+    if (!node2) {
+      throw new Error(`Graph "${this.name}": unknown node or mount "${name}"`);
+    }
+    this._nodes.delete(name);
+    for (const key of [...this._edges]) {
+      const [from, to] = parseEdgeKey(key);
+      if (from === name || to === name) this._edges.delete(key);
+    }
+    node2.down([[TEARDOWN]], { internal: true });
+  }
+  /**
+   * Returns a node by local name or `::` qualified path.
+   * Local names are looked up directly; paths with `::` delegate to {@link resolve}.
+   *
+   * @param name - Local name or qualified path.
+   */
+  node(name) {
+    if (name === "") {
+      throw new Error(`Graph "${this.name}": node name must be non-empty`);
+    }
+    if (name.includes(PATH_SEP)) {
+      return this.resolve(name);
+    }
+    const n = this._nodes.get(name);
+    if (!n) {
+      throw new Error(`Graph "${this.name}": unknown node "${name}"`);
+    }
+    return n;
+  }
+  /**
+   * Reads `graph.node(name).get()` — accepts `::` qualified paths (§3.2).
+   *
+   * @param name - Local name or qualified path.
+   * @returns Cached value or `undefined`.
+   */
+  get(name) {
+    return this.node(name).get();
+  }
+  /**
+   * Shorthand for `graph.node(name).down([[DATA, value]], { actor })` — accepts `::` qualified paths (§3.2).
+   *
+   * @param name - Local name or qualified path.
+   * @param value - Next `DATA` payload.
+   * @param options - Optional `actor` and `internal` guard bypass.
+   */
+  set(name, value, options) {
+    const internal = options?.internal === true;
+    this.node(name).down([[DATA, value]], {
+      actor: options?.actor,
+      internal,
+      delivery: "write"
+    });
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Edges
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Record a wire from `fromPath` → `toPath` (§3.3). Accepts local names or
+   * `::` qualified paths. The target must be a {@link NodeImpl} whose `_deps`
+   * includes the source node (same reference). Idempotent.
+   *
+   * Same-owner edges are stored on the owning child graph; cross-subgraph edges
+   * are stored on this (parent) graph's registry.
+   *
+   * @param fromPath - Source endpoint (local or qualified).
+   * @param toPath - Target endpoint whose deps already include the source node.
+   */
+  connect(fromPath, toPath) {
+    if (!fromPath || !toPath) {
+      throw new Error(`Graph "${this.name}": connect paths must be non-empty`);
+    }
+    assertConnectPathNotMeta(fromPath, this.name);
+    assertConnectPathNotMeta(toPath, this.name);
+    const [fromGraph, fromLocal, fromNode] = this._resolveEndpoint(fromPath);
+    const [toGraph, toLocal, toNode] = this._resolveEndpoint(toPath);
+    if (fromNode === toNode) {
+      throw new Error(`Graph "${this.name}": cannot connect a node to itself`);
+    }
+    if (!(toNode instanceof NodeImpl)) {
+      throw new Error(
+        `Graph "${this.name}": connect(${fromPath}, ${toPath}) requires the target to be a graphrefly NodeImpl so deps can be validated`
+      );
+    }
+    if (!toNode._deps.includes(fromNode)) {
+      throw new Error(
+        `Graph "${this.name}": connect(${fromPath}, ${toPath}) \u2014 target must include source in its constructor deps (same node reference)`
+      );
+    }
+    if (fromGraph === toGraph) {
+      const key = edgeKey(fromLocal, toLocal);
+      fromGraph._edges.add(key);
+    } else {
+      const key = edgeKey(fromPath, toPath);
+      this._edges.add(key);
+    }
+  }
+  /**
+   * Remove a registered edge (§3.3). Accepts local names or `::` qualified paths.
+   *
+   * **Registry-only (§C resolved):** This drops the edge from the graph's edge
+   * registry only. It does **not** mutate the target node's constructor-time
+   * dependency list, bitmasks, or upstream subscriptions. Message flow follows
+   * constructor-time deps, not the edge registry. For runtime dep rewiring, use
+   * {@link dynamicNode}.
+   *
+   * @param fromPath - Registered edge tail.
+   * @param toPath - Registered edge head.
+   */
+  disconnect(fromPath, toPath) {
+    if (!fromPath || !toPath) {
+      throw new Error(`Graph "${this.name}": disconnect paths must be non-empty`);
+    }
+    assertConnectPathNotMeta(fromPath, this.name);
+    assertConnectPathNotMeta(toPath, this.name);
+    const [fromGraph, fromLocal] = this._resolveEndpoint(fromPath);
+    const [toGraph, toLocal] = this._resolveEndpoint(toPath);
+    if (fromGraph === toGraph) {
+      const key = edgeKey(fromLocal, toLocal);
+      if (!fromGraph._edges.delete(key)) {
+        throw new Error(`Graph "${this.name}": no registered edge ${fromPath} \u2192 ${toPath}`);
+      }
+    } else {
+      const key = edgeKey(fromPath, toPath);
+      if (!this._edges.delete(key)) {
+        throw new Error(`Graph "${this.name}": no registered edge ${fromPath} \u2192 ${toPath}`);
+      }
+    }
+  }
+  /**
+   * Returns registered `[from, to]` edge pairs (read-only snapshot).
+   *
+   * @returns Edge pairs recorded on this graph instance’s local `_edges` set.
+   */
+  edges() {
+    const result = [];
+    for (const key of this._edges) {
+      result.push(parseEdgeKey(key));
+    }
+    return result;
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Composition
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Embed a child graph at a local mount name (§3.4). Child nodes are reachable via
+   * {@link Graph.resolve} using `::` delimited paths (§3.5). Lifecycle
+   * {@link Graph.signal} visits mounted subgraphs recursively.
+   *
+   * Rejects: same name as existing node or mount, self-mount, mount cycles,
+   * and the same child graph instance mounted twice on one parent.
+   *
+   * @param name - Local mount point.
+   * @param child - Nested `Graph` instance.
+   */
+  mount(name, child) {
+    assertLocalName(name, this.name, "mount");
+    assertNoPathSep(name, this.name, "mount");
+    assertNotReservedMetaSegment(name, this.name, "mount");
+    if (this._nodes.has(name)) {
+      throw new Error(
+        `Graph "${this.name}": cannot mount at "${name}" \u2014 node with that name exists`
+      );
+    }
+    if (this._mounts.has(name)) {
+      throw new Error(`Graph "${this.name}": mount "${name}" already exists`);
+    }
+    if (child === this) {
+      throw new Error(`Graph "${this.name}": cannot mount a graph into itself`);
+    }
+    for (const existing of this._mounts.values()) {
+      if (existing === child) {
+        throw new Error(`Graph "${this.name}": this child graph is already mounted on this graph`);
+      }
+    }
+    if (child._graphsReachableViaMounts().has(this)) {
+      throw new Error(`Graph "${this.name}": mount("${name}", \u2026) would create a mount cycle`);
+    }
+    this._mounts.set(name, child);
+  }
+  /**
+   * Look up a node by qualified path (§3.5). Segments are separated by `::`.
+   *
+   * If the first segment equals this graph's {@link Graph.name}, it is stripped
+   * (so `root.resolve("app::a")` works when `root.name === "app"`).
+   *
+   * @param path - Qualified `::` path or local name.
+   * @returns The resolved `Node`.
+   */
+  resolve(path) {
+    let segments = splitPath(path, this.name);
+    if (segments[0] === this.name) {
+      segments = segments.slice(1);
+      if (segments.length === 0) {
+        throw new Error(`Graph "${this.name}": resolve path ends at graph name only`);
+      }
+    }
+    return this._resolveFromSegments(segments);
+  }
+  _resolveFromSegments(segments) {
+    const head = segments[0];
+    const rest = segments.slice(1);
+    if (rest.length === 0) {
+      const n = this._nodes.get(head);
+      if (n) return n;
+      if (this._mounts.has(head)) {
+        throw new Error(
+          `Graph "${this.name}": path ends at subgraph "${head}" \u2014 not a node (GRAPHREFLY-SPEC \xA73.5)`
+        );
+      }
+      throw new Error(`Graph "${this.name}": unknown name "${head}"`);
+    }
+    const localN = this._nodes.get(head);
+    if (localN && rest.length > 0 && rest[0] === GRAPH_META_SEGMENT) {
+      return this._resolveMetaChainFromNode(localN, rest, segments.join(PATH_SEP));
+    }
+    const child = this._mounts.get(head);
+    if (!child) {
+      if (this._nodes.has(head)) {
+        throw new Error(
+          `Graph "${this.name}": "${head}" is a node; trailing path "${rest.join(PATH_SEP)}" is invalid`
+        );
+      }
+      throw new Error(`Graph "${this.name}": unknown mount or node "${head}"`);
+    }
+    return child.resolve(rest.join(PATH_SEP));
+  }
+  /**
+   * Resolve `::__meta__::key` segments from a registered primary node (possibly chained).
+   */
+  _resolveMetaChainFromNode(n, parts, fullPath) {
+    let current = n;
+    let i = 0;
+    const p = [...parts];
+    while (i < p.length) {
+      if (p[i] !== GRAPH_META_SEGMENT) {
+        throw new Error(
+          `Graph "${this.name}": expected ${GRAPH_META_SEGMENT} segment in meta path "${fullPath}"`
+        );
+      }
+      if (i + 1 >= p.length) {
+        throw new Error(
+          `Graph "${this.name}": meta path requires a key after ${GRAPH_META_SEGMENT} in "${fullPath}"`
+        );
+      }
+      const key = p[i + 1];
+      const next = current.meta[key];
+      if (!next) {
+        throw new Error(`Graph "${this.name}": unknown meta "${key}" in path "${fullPath}"`);
+      }
+      current = next;
+      i += 2;
+    }
+    return current;
+  }
+  _resolveMetaEndpointKeys(baseNode, baseLocalKey, parts, fullPath) {
+    let current = baseNode;
+    let localKey = baseLocalKey;
+    let i = 0;
+    const p = [...parts];
+    while (i < p.length) {
+      if (p[i] !== GRAPH_META_SEGMENT) {
+        throw new Error(
+          `Graph "${this.name}": expected ${GRAPH_META_SEGMENT} segment in meta path "${fullPath}"`
+        );
+      }
+      if (i + 1 >= p.length) {
+        throw new Error(
+          `Graph "${this.name}": meta path requires a key after ${GRAPH_META_SEGMENT} in "${fullPath}"`
+        );
+      }
+      const metaKey = p[i + 1];
+      const next = current.meta[metaKey];
+      if (!next) {
+        throw new Error(
+          `Graph "${this.name}": unknown meta "${metaKey}" on node (in "${fullPath}")`
+        );
+      }
+      localKey = `${localKey}${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}${metaKey}`;
+      current = next;
+      i += 2;
+    }
+    return [this, localKey, current];
+  }
+  /**
+   * Deliver a message batch to every registered node in this graph and, recursively,
+   * in mounted child graphs (§3.7). Recurses into mounts first, then delivers to
+   * local nodes (sorted by name). Each {@link Node} receives at most one delivery
+   * per call (deduped by reference).
+   *
+   * Companion `meta` nodes receive the same batch for control-plane types (e.g.
+   * PAUSE) that the primary does not forward. **TEARDOWN-only** batches skip the
+   * extra meta pass — the primary’s `down()` already cascades TEARDOWN to meta.
+   *
+   * @param messages - Batch to deliver to every registered node (and mounts, recursively).
+   * @param options - Optional `actor` / `internal` for transport.
+   */
+  signal(messages, options) {
+    this._signalDeliver(messages, options ?? {}, /* @__PURE__ */ new Set());
+  }
+  _signalDeliver(messages, opts, vis) {
+    for (const sub of this._mounts.values()) {
+      sub._signalDeliver(messages, opts, vis);
+    }
+    const internal = opts.internal === true;
+    const downOpts = internal ? { internal: true } : { actor: opts.actor, delivery: "signal" };
+    const metaMessages = filterMetaMessages(messages);
+    for (const localName of [...this._nodes.keys()].sort()) {
+      const n = this._nodes.get(localName);
+      if (vis.has(n)) continue;
+      vis.add(n);
+      n.down(messages, downOpts);
+      if (metaMessages.length === 0) continue;
+      this._signalMetaSubtree(n, metaMessages, vis, downOpts);
+    }
+  }
+  _signalMetaSubtree(root, messages, vis, downOpts) {
+    for (const mk of Object.keys(root.meta).sort()) {
+      const mnode = root.meta[mk];
+      if (vis.has(mnode)) continue;
+      vis.add(mnode);
+      mnode.down(messages, downOpts);
+      this._signalMetaSubtree(mnode, messages, vis, downOpts);
+    }
+  }
+  /**
+   * Static structure snapshot: qualified node keys, edges, mount names (GRAPHREFLY-SPEC §3.6, Appendix B).
+   *
+   * @param options - Optional `actor` for guard-scoped visibility and/or `filter` for selective output.
+   * @returns JSON-shaped describe payload for this graph tree.
+   *
+   * @example
+   * ```ts
+   * graph.describe()                                         // full snapshot
+   * graph.describe({ actor: llm })                           // guard-scoped
+   * graph.describe({ filter: { status: "errored" } })        // only errored nodes
+   * graph.describe({ filter: (n) => n.type === "state" })    // predicate filter
+   * ```
+   */
+  describe(options) {
+    const actor = options?.actor;
+    const filter = options?.filter;
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    const nodeToPath = /* @__PURE__ */ new Map();
+    for (const [p, n] of targets) {
+      nodeToPath.set(n, p);
+    }
+    const nodes = {};
+    for (const [p, n] of targets) {
+      if (actor != null && !n.allowsObserve(actor)) continue;
+      const raw = describeNode(n);
+      const deps = n instanceof NodeImpl ? n._deps.map((d) => nodeToPath.get(d) ?? d.name ?? "") : [];
+      const { name: _name, ...rest } = raw;
+      const entry = { ...rest, deps };
+      if (filter != null) {
+        if (typeof filter === "function") {
+          const fn = filter;
+          const pass = fn.length >= 2 ? fn(p, entry) : fn(entry);
+          if (!pass) continue;
+        } else {
+          let match = true;
+          for (const [fk, fv] of Object.entries(filter)) {
+            const normalizedKey = fk === "deps_includes" ? "depsIncludes" : fk === "meta_has" ? "metaHas" : fk;
+            if (normalizedKey === "depsIncludes") {
+              if (!entry.deps.includes(String(fv))) {
+                match = false;
+                break;
+              }
+              continue;
+            }
+            if (normalizedKey === "metaHas") {
+              if (!Object.hasOwn(entry.meta, String(fv))) {
+                match = false;
+                break;
+              }
+              continue;
+            }
+            if (entry[normalizedKey] !== fv) {
+              match = false;
+              break;
+            }
+          }
+          if (!match) continue;
+        }
+      }
+      nodes[p] = entry;
+    }
+    const nodeKeys = new Set(Object.keys(nodes));
+    let edges = this._collectAllEdges("");
+    if (actor != null || filter != null) {
+      edges = edges.filter((e) => nodeKeys.has(e.from) && nodeKeys.has(e.to));
+    }
+    edges.sort((a, b) => {
+      if (a.from < b.from) return -1;
+      if (a.from > b.from) return 1;
+      if (a.to < b.to) return -1;
+      if (a.to > b.to) return 1;
+      return 0;
+    });
+    const allSubgraphs = this._collectSubgraphs("");
+    const subgraphs = actor != null || filter != null ? allSubgraphs.filter((sg) => {
+      const prefix = `${sg}${PATH_SEP}`;
+      return [...nodeKeys].some((k) => k === sg || k.startsWith(prefix));
+    }) : allSubgraphs;
+    return {
+      name: this.name,
+      nodes,
+      edges,
+      subgraphs
+    };
+  }
+  _collectSubgraphs(prefix) {
+    const out = [];
+    for (const m of [...this._mounts.keys()].sort()) {
+      const q = prefix === "" ? m : `${prefix}${m}`;
+      out.push(q);
+      out.push(...this._mounts.get(m)._collectSubgraphs(`${q}${PATH_SEP}`));
+    }
+    return out;
+  }
+  _collectAllEdges(prefix) {
+    const out = [];
+    for (const m of [...this._mounts.keys()].sort()) {
+      const p2 = prefix === "" ? m : `${prefix}${PATH_SEP}${m}`;
+      out.push(...this._mounts.get(m)._collectAllEdges(p2));
+    }
+    for (const [f, t] of this.edges()) {
+      out.push({
+        from: this._qualifyEdgeEndpoint(f, prefix),
+        to: this._qualifyEdgeEndpoint(t, prefix)
+      });
+    }
+    return out;
+  }
+  _qualifyEdgeEndpoint(part, prefix) {
+    if (part.includes(PATH_SEP)) return part;
+    return prefix === "" ? part : `${prefix}${PATH_SEP}${part}`;
+  }
+  _collectObserveTargets(prefix, out) {
+    for (const m of [...this._mounts.keys()].sort()) {
+      const p2 = prefix === "" ? m : `${prefix}${PATH_SEP}${m}`;
+      this._mounts.get(m)._collectObserveTargets(p2, out);
+    }
+    for (const loc of [...this._nodes.keys()].sort()) {
+      const n = this._nodes.get(loc);
+      const p = prefix === "" ? loc : `${prefix}${PATH_SEP}${loc}`;
+      out.push([p, n]);
+      this._appendMetaObserveTargets(p, n, out);
+    }
+  }
+  _appendMetaObserveTargets(basePath, n, out) {
+    for (const mk of Object.keys(n.meta).sort()) {
+      const m = n.meta[mk];
+      const mp = `${basePath}${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}${mk}`;
+      out.push([mp, m]);
+      this._appendMetaObserveTargets(mp, m, out);
+    }
+  }
+  observe(pathOrOpts, options) {
+    if (typeof pathOrOpts === "string") {
+      const path = pathOrOpts;
+      const actor2 = options?.actor;
+      const target = this.resolve(path);
+      if (actor2 != null && !target.allowsObserve(actor2)) {
+        throw new GuardDenied({ actor: actor2, action: "observe", nodeName: path });
+      }
+      const wantsStructured2 = options?.structured === true || options?.timeline === true || options?.causal === true || options?.derived === true;
+      if (wantsStructured2 && _Graph.inspectorEnabled) {
+        return this._createObserveResult(path, target, options);
+      }
+      return {
+        subscribe(sink) {
+          return target.subscribe(sink);
+        },
+        up(messages) {
+          try {
+            target.up?.(messages);
+          } catch (err) {
+            if (err instanceof GuardDenied) return;
+            throw err;
+          }
+        }
+      };
+    }
+    const opts = pathOrOpts;
+    const actor = opts?.actor;
+    const wantsStructured = opts?.structured === true || opts?.timeline === true || opts?.causal === true || opts?.derived === true;
+    if (wantsStructured && _Graph.inspectorEnabled) {
+      return this._createObserveResultForAll(opts ?? {});
+    }
+    return {
+      subscribe: (sink) => {
+        const targets = [];
+        this._collectObserveTargets("", targets);
+        targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+        const picked = actor == null ? targets : targets.filter(([, nd]) => nd.allowsObserve(actor));
+        const unsubs = picked.map(
+          ([p, nd]) => nd.subscribe((msgs) => {
+            sink(p, msgs);
+          })
+        );
+        return () => {
+          for (const u of unsubs) u();
+        };
+      },
+      up: (upPath, messages) => {
+        try {
+          const nd = this.resolve(upPath);
+          nd.up?.(messages);
+        } catch (err) {
+          if (err instanceof GuardDenied) return;
+          throw err;
+        }
+      }
+    };
+  }
+  _createObserveResult(path, target, options) {
+    const timeline = options.timeline === true;
+    const causal = options.causal === true;
+    const derived2 = options.derived === true;
+    const result = {
+      values: {},
+      dirtyCount: 0,
+      resolvedCount: 0,
+      events: [],
+      completedCleanly: false,
+      errored: false
+    };
+    let lastTriggerDepIndex;
+    let lastRunDepValues;
+    let detachInspectorHook;
+    if ((causal || derived2) && target instanceof NodeImpl) {
+      detachInspectorHook = target._setInspectorHook((event) => {
+        if (event.kind === "dep_message") {
+          lastTriggerDepIndex = event.depIndex;
+          return;
+        }
+        lastRunDepValues = [...event.depValues];
+        if (derived2) {
+          result.events.push({
+            type: "derived",
+            path,
+            dep_values: [...event.depValues],
+            ...timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {}
+          });
+        }
+      });
+    }
+    const unsub = target.subscribe((msgs) => {
+      for (const m of msgs) {
+        const t = m[0];
+        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+        const withCausal = causal && lastRunDepValues != null ? (() => {
+          const triggerDep = lastTriggerDepIndex != null && lastTriggerDepIndex >= 0 && target instanceof NodeImpl ? target._deps[lastTriggerDepIndex] : void 0;
+          const tv = triggerDep?.v;
+          return {
+            trigger_dep_index: lastTriggerDepIndex,
+            trigger_dep_name: triggerDep?.name,
+            ...tv != null ? { trigger_version: { id: tv.id, version: tv.version } } : {},
+            dep_values: [...lastRunDepValues]
+          };
+        })() : {};
+        if (t === DATA) {
+          result.values[path] = m[1];
+          result.events.push({ type: "data", path, data: m[1], ...base, ...withCausal });
+        } else if (t === DIRTY) {
+          result.dirtyCount++;
+          result.events.push({ type: "dirty", path, ...base });
+        } else if (t === RESOLVED) {
+          result.resolvedCount++;
+          result.events.push({ type: "resolved", path, ...base, ...withCausal });
+        } else if (t === COMPLETE) {
+          if (!result.errored) result.completedCleanly = true;
+          result.events.push({ type: "complete", path, ...base });
+        } else if (t === ERROR) {
+          result.errored = true;
+          result.events.push({ type: "error", path, data: m[1], ...base });
+        }
+      }
+    });
+    return {
+      get values() {
+        return result.values;
+      },
+      get dirtyCount() {
+        return result.dirtyCount;
+      },
+      get resolvedCount() {
+        return result.resolvedCount;
+      },
+      get events() {
+        return result.events;
+      },
+      get completedCleanly() {
+        return result.completedCleanly;
+      },
+      get errored() {
+        return result.errored;
+      },
+      dispose() {
+        unsub();
+        detachInspectorHook?.();
+      }
+    };
+  }
+  _createObserveResultForAll(options) {
+    const timeline = options.timeline === true;
+    const result = {
+      values: {},
+      dirtyCount: 0,
+      resolvedCount: 0,
+      events: [],
+      completedCleanly: false,
+      errored: false
+    };
+    const actor = options.actor;
+    const targets = [];
+    this._collectObserveTargets("", targets);
+    targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const picked = actor == null ? targets : targets.filter(([, nd]) => nd.allowsObserve(actor));
+    const unsubs = picked.map(
+      ([path, nd]) => nd.subscribe((msgs) => {
+        for (const m of msgs) {
+          const t = m[0];
+          const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+          if (t === DATA) {
+            result.values[path] = m[1];
+            result.events.push({ type: "data", path, data: m[1], ...base });
+          } else if (t === DIRTY) {
+            result.dirtyCount++;
+            result.events.push({ type: "dirty", path, ...base });
+          } else if (t === RESOLVED) {
+            result.resolvedCount++;
+            result.events.push({ type: "resolved", path, ...base });
+          } else if (t === COMPLETE) {
+            if (!result.errored) result.completedCleanly = true;
+            result.events.push({ type: "complete", path, ...base });
+          } else if (t === ERROR) {
+            result.errored = true;
+            result.events.push({ type: "error", path, data: m[1], ...base });
+          }
+        }
+      })
+    );
+    return {
+      get values() {
+        return result.values;
+      },
+      get dirtyCount() {
+        return result.dirtyCount;
+      },
+      get resolvedCount() {
+        return result.resolvedCount;
+      },
+      get events() {
+        return result.events;
+      },
+      get completedCleanly() {
+        return result.completedCleanly;
+      },
+      get errored() {
+        return result.errored;
+      },
+      dispose() {
+        for (const u of unsubs) u();
+      }
+    };
+  }
+  /**
+   * Convenience live debugger over {@link Graph.observe}. Logs protocol events as they flow.
+   *
+   * Supports one-node (`path`) and graph-wide modes, event filtering, and JSON/pretty rendering.
+   * Color themes are built in (`ansi` / `none`) to avoid external dependencies.
+   *
+   * @param options - Spy configuration.
+   * @returns Disposable handle plus a structured observation accumulator.
+   */
+  spy(options = {}) {
+    const include = options.includeTypes ? new Set(options.includeTypes) : null;
+    const exclude = options.excludeTypes ? new Set(options.excludeTypes) : null;
+    const theme = resolveSpyTheme(options.theme);
+    const format = options.format ?? "pretty";
+    const logger = options.logger ?? ((line) => console.log(line));
+    const shouldLog = (type) => {
+      if (include?.has(type) === false) return false;
+      if (exclude?.has(type) === true) return false;
+      return true;
+    };
+    const renderEvent = (event) => {
+      if (format === "json") {
+        try {
+          return JSON.stringify(event);
+        } catch {
+          return JSON.stringify({
+            type: event.type,
+            path: event.path,
+            data: "[unserializable]"
+          });
+        }
+      }
+      const color = theme[event.type] ?? "";
+      const pathPart = event.path ? `${theme.path}${event.path}${theme.reset} ` : "";
+      const dataPart = event.data !== void 0 ? ` ${describeData(event.data)}` : "";
+      const triggerPart = event.trigger_dep_name != null ? ` <- ${event.trigger_dep_name}` : event.trigger_dep_index != null ? ` <- #${event.trigger_dep_index}` : "";
+      const batchPart = event.in_batch ? " [batch]" : "";
+      return `${pathPart}${color}${event.type.toUpperCase()}${theme.reset}${dataPart}${triggerPart}${batchPart}`;
+    };
+    if (!_Graph.inspectorEnabled) {
+      const timeline = options.timeline ?? true;
+      const acc = {
+        values: {},
+        dirtyCount: 0,
+        resolvedCount: 0,
+        events: [],
+        completedCleanly: false,
+        errored: false
+      };
+      let stop2 = () => {
+      };
+      const result2 = {
+        get values() {
+          return acc.values;
+        },
+        get dirtyCount() {
+          return acc.dirtyCount;
+        },
+        get resolvedCount() {
+          return acc.resolvedCount;
+        },
+        get events() {
+          return acc.events;
+        },
+        get completedCleanly() {
+          return acc.completedCleanly;
+        },
+        get errored() {
+          return acc.errored;
+        },
+        dispose() {
+          stop2();
+        }
+      };
+      const pushEvent = (path, message) => {
+        const t = message[0];
+        const base = timeline ? { timestamp_ns: monotonicNs(), in_batch: isBatching() } : {};
+        let event;
+        if (t === DATA) {
+          if (path != null) acc.values[path] = message[1];
+          event = { type: "data", ...path != null ? { path } : {}, data: message[1], ...base };
+        } else if (t === DIRTY) {
+          acc.dirtyCount += 1;
+          event = { type: "dirty", ...path != null ? { path } : {}, ...base };
+        } else if (t === RESOLVED) {
+          acc.resolvedCount += 1;
+          event = { type: "resolved", ...path != null ? { path } : {}, ...base };
+        } else if (t === COMPLETE) {
+          if (!acc.errored) acc.completedCleanly = true;
+          event = { type: "complete", ...path != null ? { path } : {}, ...base };
+        } else if (t === ERROR) {
+          acc.errored = true;
+          event = {
+            type: "error",
+            ...path != null ? { path } : {},
+            data: message[1],
+            ...base
+          };
+        }
+        if (!event) return;
+        acc.events.push(event);
+        if (!shouldLog(event.type)) return;
+        logger(renderEvent(event), event);
+      };
+      if (options.path != null) {
+        const stream2 = this.observe(options.path, {
+          actor: options.actor,
+          structured: false
+        });
+        stop2 = stream2.subscribe((messages) => {
+          for (const m of messages) {
+            pushEvent(options.path, m);
+          }
+        });
+      } else {
+        const stream2 = this.observe({ actor: options.actor, structured: false });
+        stop2 = stream2.subscribe((path, messages) => {
+          for (const m of messages) {
+            pushEvent(path, m);
+          }
+        });
+      }
+      return {
+        result: result2,
+        dispose() {
+          result2.dispose();
+        }
+      };
+    }
+    const structuredObserveOptions = {
+      actor: options.actor,
+      structured: true,
+      ...options.timeline !== false ? { timeline: true } : {},
+      ...options.causal ? { causal: true } : {},
+      ...options.derived ? { derived: true } : {}
+    };
+    const result = options.path != null ? this.observe(options.path, structuredObserveOptions) : this.observe(structuredObserveOptions);
+    let cursor = 0;
+    const flushNewEvents = () => {
+      const nextEvents = result.events.slice(cursor);
+      cursor = result.events.length;
+      for (const event of nextEvents) {
+        if (!shouldLog(event.type)) continue;
+        logger(renderEvent(event), event);
+      }
+    };
+    const stream = options.path != null ? this.observe(options.path, { actor: options.actor, structured: false }) : this.observe({ actor: options.actor, structured: false });
+    const stop = options.path != null ? stream.subscribe((messages) => {
+      if (messages.length > 0) {
+        flushNewEvents();
+      }
+    }) : stream.subscribe((_path, messages) => {
+      if (messages.length > 0) {
+        flushNewEvents();
+      }
+    });
+    return {
+      result,
+      dispose() {
+        stop();
+        flushNewEvents();
+        result.dispose();
+      }
+    };
+  }
+  /**
+   * CLI/debug-friendly graph dump built on {@link Graph.describe}.
+   *
+   * @param options - Optional actor/filter/format toggles.
+   * @returns Rendered graph text.
+   */
+  dumpGraph(options = {}) {
+    const described = this.describe({
+      actor: options.actor,
+      filter: options.filter
+    });
+    const includeEdges = options.includeEdges ?? true;
+    const includeSubgraphs = options.includeSubgraphs ?? true;
+    if (options.format === "json") {
+      const payload = {
+        name: described.name,
+        nodes: described.nodes,
+        edges: includeEdges ? described.edges : [],
+        subgraphs: includeSubgraphs ? described.subgraphs : []
+      };
+      const text2 = JSON.stringify(sortJsonValue(payload), null, options.indent ?? 2);
+      options.logger?.(text2);
+      return text2;
+    }
+    const lines = [];
+    lines.push(`Graph ${described.name}`);
+    lines.push("Nodes:");
+    for (const path of Object.keys(described.nodes).sort()) {
+      const n = described.nodes[path];
+      lines.push(`- ${path} (${n.type}/${n.status}): ${describeData(n.value)}`);
+    }
+    if (includeEdges) {
+      lines.push("Edges:");
+      for (const edge of described.edges) {
+        lines.push(`- ${edge.from} -> ${edge.to}`);
+      }
+    }
+    if (includeSubgraphs) {
+      lines.push("Subgraphs:");
+      for (const sg of described.subgraphs) {
+        lines.push(`- ${sg}`);
+      }
+    }
+    const text = lines.join("\n");
+    options.logger?.(text);
+    return text;
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Lifecycle & persistence (§3.7–§3.8)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Sends `[[TEARDOWN]]` to all nodes, then clears registries on this graph and every
+   * mounted subgraph (§3.7). The instance is left empty and may be reused with {@link Graph.add}.
+   */
+  destroy() {
+    this.signal([[TEARDOWN]], { internal: true });
+    for (const dispose of [...this._autoCheckpointDisposers]) {
+      try {
+        dispose();
+      } catch {
+      }
+    }
+    this._autoCheckpointDisposers.clear();
+    for (const child of [...this._mounts.values()]) {
+      child._destroyClearOnly();
+    }
+    this._mounts.clear();
+    this._nodes.clear();
+    this._edges.clear();
+  }
+  /** Clear structure after parent already signaled TEARDOWN through this subtree. */
+  _destroyClearOnly() {
+    for (const child of [...this._mounts.values()]) {
+      child._destroyClearOnly();
+    }
+    this._mounts.clear();
+    this._nodes.clear();
+    this._edges.clear();
+  }
+  /**
+   * Serializes structure and current values to JSON-shaped data (§3.8). Same information
+   * as {@link Graph.describe} plus a `version` field for format evolution.
+   *
+   * @returns Persistable snapshot with sorted keys.
+   */
+  snapshot() {
+    const d = this.describe();
+    const sortedNodes = {};
+    for (const key of Object.keys(d.nodes).sort()) {
+      sortedNodes[key] = d.nodes[key];
+    }
+    const sortedSubgraphs = [...d.subgraphs].sort();
+    return { ...d, version: 1, nodes: sortedNodes, subgraphs: sortedSubgraphs };
+  }
+  /**
+   * Apply persisted values onto an existing graph whose topology matches the snapshot
+   * (§3.8). Only {@link DescribeNodeOutput.type} `state` and `producer` entries with a
+   * `value` field are written; `derived` / `operator` / `effect` are skipped so deps
+   * drive recomputation. Unknown paths are ignored.
+   *
+   * @param data - Snapshot envelope with matching `name` and node slices.
+   * @throws If `data.name` does not equal {@link Graph.name}.
+   */
+  restore(data, options) {
+    parseSnapshotEnvelope(data);
+    if (data.name !== this.name) {
+      throw new Error(
+        `Graph "${this.name}": restore snapshot name "${data.name}" does not match this graph`
+      );
+    }
+    const onlyPatterns = options?.only == null ? null : (Array.isArray(options.only) ? options.only : [options.only]).map((p) => globToRegex(p));
+    for (const path of Object.keys(data.nodes).sort()) {
+      if (onlyPatterns !== null && !onlyPatterns.some((re) => re.test(path))) continue;
+      const slice = data.nodes[path];
+      if (slice === void 0 || slice.value === void 0) continue;
+      if (slice.type === "derived" || slice.type === "operator" || slice.type === "effect") {
+        continue;
+      }
+      try {
+        this.set(path, slice.value);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Creates a graph named from the snapshot, optionally runs `build` to register nodes
+   * and mounts, then {@link Graph.restore} values (§3.8).
+   *
+   * @param data - Snapshot envelope (`version` checked).
+   * @param build - Optional callback to construct topology before values are applied.
+   * @returns Hydrated `Graph` instance.
+   */
+  static fromSnapshot(data, build) {
+    parseSnapshotEnvelope(data);
+    const g = new _Graph(data.name);
+    if (build) {
+      build(g);
+      g.restore(data);
+      return g;
+    }
+    for (const mount of [...data.subgraphs].sort((a, b) => {
+      const da = a.split(PATH_SEP).length;
+      const db = b.split(PATH_SEP).length;
+      if (da !== db) return da - db;
+      if (a < b) return -1;
+      if (a > b) return 1;
+      return 0;
+    })) {
+      const parts = mount.split(PATH_SEP);
+      let target = g;
+      for (const seg of parts) {
+        if (!target._mounts.has(seg)) {
+          target.mount(seg, new _Graph(seg));
+        }
+        target = target._mounts.get(seg);
+      }
+    }
+    const primaryEntries = Object.entries(data.nodes).filter(([path]) => !path.includes(`${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}`)).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const pending = new Map(primaryEntries);
+    const created = /* @__PURE__ */ new Map();
+    let progressed = true;
+    while (pending.size > 0 && progressed) {
+      progressed = false;
+      for (const [path, slice] of [...pending.entries()]) {
+        const deps = slice?.deps ?? [];
+        if (!deps.every((dep) => created.has(dep))) continue;
+        const [owner, localName] = _Graph._ownerForPath(g, path);
+        const meta = { ...slice?.meta ?? {} };
+        const factory = _Graph._factoryForPath(path);
+        let node2;
+        if (slice?.type === "state") {
+          node2 = state(slice.value, { meta });
+        } else {
+          if (factory == null) continue;
+          node2 = factory(localName, {
+            path,
+            type: slice.type,
+            value: slice.value,
+            meta,
+            deps,
+            resolvedDeps: deps.map((dep) => created.get(dep))
+          });
+        }
+        owner.add(localName, node2);
+        created.set(path, node2);
+        pending.delete(path);
+        progressed = true;
+      }
+    }
+    if (pending.size > 0) {
+      const unresolved = [...pending.keys()].sort().join(", ");
+      throw new Error(
+        `Graph.fromSnapshot could not reconstruct nodes without build callback: ${unresolved}. Register matching factories with Graph.registerFactory(pattern, factory).`
+      );
+    }
+    for (const edge of data.edges) {
+      try {
+        g.connect(edge.from, edge.to);
+      } catch {
+      }
+    }
+    g.restore(data);
+    return g;
+  }
+  /**
+   * Plain snapshot with **recursively sorted object keys** for deterministic serialization (§3.8).
+   *
+   * @remarks
+   * ECMAScript `JSON.stringify(graph)` invokes this method; it must return a plain object, not an
+   * already-stringified JSON string (otherwise the graph would be double-encoded).
+   * For a single UTF-8 string with a trailing newline (convenient for git), use {@link Graph.toJSONString}.
+   *
+   * @returns Same object as {@link Graph.snapshot}.
+   */
+  toJSON() {
+    return this.snapshot();
+  }
+  /**
+   * Deterministic JSON **text**: `JSON.stringify` of {@link Graph.toJSON} plus a trailing newline (§3.8).
+   *
+   * @returns Stable string suitable for diffs.
+   */
+  toJSONString() {
+    return stableJsonStringify(this.snapshot());
+  }
+  /**
+   * Debounced persistence wired to graph-wide observe stream (spec §3.8 auto-checkpoint).
+   *
+   * Checkpoint trigger uses {@link messageTier}: only batches containing tier >= 2 messages
+   * schedule a save (`DATA`/`RESOLVED`/terminal/destruction), never pure tier-0/1 control waves.
+   */
+  autoCheckpoint(adapter, options = {}) {
+    const debounceMs = Math.max(0, options.debounceMs ?? 500);
+    const compactEvery = Math.max(1, options.compactEvery ?? 10);
+    let timer;
+    let seq = 0;
+    let pending = false;
+    let lastDescribe;
+    const flush = () => {
+      timer = void 0;
+      if (!pending) return;
+      pending = false;
+      try {
+        const described = this.describe();
+        const snapshot = { ...described, version: SNAPSHOT_VERSION };
+        seq += 1;
+        const shouldCompact = lastDescribe == null || seq % compactEvery === 0;
+        if (shouldCompact) {
+          adapter.save({ mode: "full", snapshot, seq });
+        } else {
+          const previous = lastDescribe;
+          if (previous == null) return;
+          adapter.save({
+            mode: "diff",
+            diff: _Graph.diff(previous, described),
+            snapshot,
+            seq
+          });
+        }
+        lastDescribe = described;
+      } catch (error) {
+        options.onError?.(error);
+      }
+    };
+    const schedule = () => {
+      pending = true;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = setTimeout(flush, debounceMs);
+    };
+    const off = this.observe().subscribe((path, messages) => {
+      const triggeredByTier = messages.some((m) => messageTier(m[0]) >= 2);
+      if (!triggeredByTier) return;
+      if (options.filter) {
+        const described = this.describe().nodes[path];
+        if (described == null || !options.filter(path, described)) return;
+      }
+      schedule();
+    });
+    const dispose = () => {
+      off();
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      this._autoCheckpointDisposers.delete(dispose);
+    };
+    this._autoCheckpointDisposers.add(dispose);
+    return { dispose };
+  }
+  /**
+   * Export the current graph topology as Mermaid flowchart text.
+   *
+   * Renders qualified node paths and registered edges from {@link Graph.describe}.
+   *
+   * @param options - Optional diagram direction (`LR` by default).
+   * @returns Mermaid flowchart source.
+   */
+  toMermaid(options) {
+    const direction = normalizeDiagramDirection(options?.direction);
+    const described = this.describe();
+    const paths = Object.keys(described.nodes).sort();
+    const ids = /* @__PURE__ */ new Map();
+    for (let i = 0; i < paths.length; i += 1) {
+      ids.set(paths[i], `n${i}`);
+    }
+    const lines = [`flowchart ${direction}`];
+    for (const path of paths) {
+      const id = ids.get(path);
+      lines.push(`  ${id}["${escapeMermaidLabel(path)}"]`);
+    }
+    for (const [from, to] of collectDiagramArrows(described)) {
+      const fromId = ids.get(from);
+      const toId = ids.get(to);
+      if (!fromId || !toId) continue;
+      lines.push(`  ${fromId} --> ${toId}`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Export the current graph topology as D2 diagram text.
+   *
+   * Renders qualified node paths, constructor deps, and registered edges from {@link Graph.describe}.
+   *
+   * @param options - Optional diagram direction (`LR` by default).
+   * @returns D2 source text.
+   */
+  toD2(options) {
+    const direction = normalizeDiagramDirection(options?.direction);
+    const described = this.describe();
+    const paths = Object.keys(described.nodes).sort();
+    const ids = /* @__PURE__ */ new Map();
+    for (let i = 0; i < paths.length; i += 1) {
+      ids.set(paths[i], `n${i}`);
+    }
+    const lines = [`direction: ${d2DirectionFromGraphDirection(direction)}`];
+    for (const path of paths) {
+      const id = ids.get(path);
+      lines.push(`${id}: "${escapeD2Label(path)}"`);
+    }
+    for (const [from, to] of collectDiagramArrows(described)) {
+      const fromId = ids.get(from);
+      const toId = ids.get(to);
+      if (!fromId || !toId) continue;
+      lines.push(`${fromId} -> ${toId}`);
+    }
+    return lines.join("\n");
+  }
+  // ——————————————————————————————————————————————————————————————
+  //  Inspector (roadmap 3.3) — reasoning trace, overhead gating
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * When `false`, structured observation options (`causal`, `timeline`),
+   * `annotate()`, and `traceLog()` are no-ops. Raw `observe()` always works.
+   *
+   * Default: `true` outside production (`process.env.NODE_ENV !== "production"`).
+   */
+  static inspectorEnabled = !(typeof process !== "undefined" && process.env?.NODE_ENV === "production");
+  _annotations = /* @__PURE__ */ new Map();
+  _traceRing = new RingBuffer(1e3);
+  /**
+   * Attaches a reasoning annotation to a node — captures *why* an AI agent set a value.
+   *
+   * No-op when {@link Graph.inspectorEnabled} is `false`.
+   *
+   * @param path - Qualified node path.
+   * @param reason - Free-text note stored in the trace ring buffer.
+   */
+  annotate(path, reason) {
+    if (!_Graph.inspectorEnabled) return;
+    this.resolve(path);
+    this._annotations.set(path, reason);
+    this._traceRing.push({ path, reason, timestamp_ns: monotonicNs() });
+  }
+  /**
+   * Returns a chronological log of all reasoning annotations (ring buffer).
+   *
+   * @returns `[]` when {@link Graph.inspectorEnabled} is `false`.
+   */
+  traceLog() {
+    if (!_Graph.inspectorEnabled) return [];
+    return this._traceRing.toArray();
+  }
+  /**
+   * Computes structural + value diff between two {@link Graph.describe} snapshots.
+   *
+   * @param a - Earlier describe output.
+   * @param b - Later describe output.
+   * @returns Added/removed nodes, changed fields, and edge deltas.
+   */
+  static diff(a, b) {
+    const aKeys = new Set(Object.keys(a.nodes));
+    const bKeys = new Set(Object.keys(b.nodes));
+    const nodesAdded = [...bKeys].filter((k) => !aKeys.has(k)).sort();
+    const nodesRemoved = [...aKeys].filter((k) => !bKeys.has(k)).sort();
+    const nodesChanged = [];
+    for (const key of aKeys) {
+      if (!bKeys.has(key)) continue;
+      const na = a.nodes[key];
+      const nb = b.nodes[key];
+      const av = na.v;
+      const bv = nb.v;
+      if (av != null && bv != null && av.id === bv.id && av.version === bv.version) {
+        for (const field of ["type", "status"]) {
+          const va = na[field];
+          const vb = nb[field];
+          if (va !== vb) {
+            nodesChanged.push({ path: key, field, from: va, to: vb });
+          }
+        }
+        continue;
+      }
+      for (const field of ["type", "status", "value"]) {
+        const va = na[field];
+        const vb = nb[field];
+        if (!Object.is(va, vb) && JSON.stringify(va) !== JSON.stringify(vb)) {
+          nodesChanged.push({ path: key, field, from: va, to: vb });
+        }
+      }
+    }
+    const edgeKey2 = (e) => `${e.from}	${e.to}`;
+    const aEdges = new Set(a.edges.map(edgeKey2));
+    const bEdges = new Set(b.edges.map(edgeKey2));
+    const edgesAdded = b.edges.filter((e) => !aEdges.has(edgeKey2(e)));
+    const edgesRemoved = a.edges.filter((e) => !bEdges.has(edgeKey2(e)));
+    const aSubgraphs = new Set(a.subgraphs);
+    const bSubgraphs = new Set(b.subgraphs);
+    const subgraphsAdded = [...bSubgraphs].filter((s) => !aSubgraphs.has(s)).sort();
+    const subgraphsRemoved = [...aSubgraphs].filter((s) => !bSubgraphs.has(s)).sort();
+    return {
+      nodesAdded,
+      nodesRemoved,
+      nodesChanged,
+      edgesAdded,
+      edgesRemoved,
+      subgraphsAdded,
+      subgraphsRemoved
+    };
+  }
+};
+
+// src/extra/reactive-base.ts
+function snapshotEqualsVersion(a, b) {
+  if (typeof a !== "object" || a == null || typeof b !== "object" || b == null) {
+    return Object.is(a, b);
+  }
+  if (!("version" in a) || !("version" in b)) return Object.is(a, b);
+  return a.version === b.version;
+}
+function bumpVersion(current, nextValue, v0) {
+  if (v0 != null) {
+    return { version: current.version + 1, value: nextValue, v0 };
+  }
+  return { version: current.version + 1, value: nextValue };
+}
+
+// src/extra/reactive-log.ts
+function emptySnapshot() {
+  return { version: 0, value: { entries: [] } };
+}
+function keepaliveDerived(n) {
+  return n.subscribe(() => {
+  });
+}
+function reactiveLog(initial, options = {}) {
+  const { name, maxSize } = options;
+  if (maxSize !== void 0 && maxSize < 1) {
+    throw new RangeError("maxSize must be >= 1");
+  }
+  const buf = initial ? [...initial] : [];
+  if (maxSize !== void 0 && buf.length > maxSize) {
+    buf.splice(0, buf.length - maxSize);
+  }
+  let current = buf.length > 0 ? { version: 1, value: { entries: [...buf] } } : emptySnapshot();
+  const entries = state(current, {
+    name,
+    describeKind: "state",
+    equals: snapshotEqualsVersion
+  });
+  function pushSnapshot() {
+    const ev = entries.v;
+    current = bumpVersion(
+      current,
+      { entries: [...buf] },
+      ev ? { id: ev.id, version: ev.version } : void 0
+    );
+    batch(() => {
+      entries.down([[DIRTY]]);
+      entries.down([[DATA, current]]);
+    });
+  }
+  function trimBuf() {
+    if (maxSize !== void 0 && buf.length > maxSize) {
+      buf.splice(0, buf.length - maxSize);
+    }
+  }
+  const bundle = {
+    entries,
+    append(value) {
+      buf.push(value);
+      trimBuf();
+      pushSnapshot();
+    },
+    appendMany(values) {
+      if (values.length === 0) return;
+      buf.push(...values);
+      trimBuf();
+      pushSnapshot();
+    },
+    clear() {
+      if (buf.length === 0) return;
+      buf.length = 0;
+      pushSnapshot();
+    },
+    trimHead(n) {
+      if (n < 0) {
+        throw new RangeError("n must be >= 0");
+      }
+      if (n === 0) return;
+      if (n >= buf.length) {
+        if (buf.length === 0) return;
+        buf.length = 0;
+      } else {
+        buf.splice(0, n);
+      }
+      pushSnapshot();
+    },
+    tail(n) {
+      if (n < 0) {
+        throw new RangeError("n must be >= 0");
+      }
+      const snap = entries.get();
+      const e = snap.value.entries;
+      const init = n === 0 ? [] : e.slice(Math.max(0, e.length - n));
+      const out = derived(
+        [entries],
+        ([s]) => {
+          const list = s.value.entries;
+          return n === 0 ? [] : list.slice(Math.max(0, list.length - n));
+        },
+        { initial: init, describeKind: "derived" }
+      );
+      keepaliveDerived(out);
+      return out;
+    }
+  };
+  return bundle;
+}
+
+// src/patterns/cqrs.ts
+var COMMAND_GUARD = policy((allow, deny) => {
+  allow("write");
+  allow("signal");
+  deny("observe");
+});
+var PROJECTION_GUARD = policy((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+var EVENT_GUARD = policy((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+function cqrsMeta(kind, extra) {
+  return { cqrs: true, cqrs_type: kind, ...extra ?? {} };
+}
+function keepalive(n) {
+  return n.subscribe(() => {
+  });
+}
+var CqrsGraph = class extends Graph {
+  _eventLogs = /* @__PURE__ */ new Map();
+  _commandHandlers = /* @__PURE__ */ new Map();
+  _projections = /* @__PURE__ */ new Set();
+  _sagas = /* @__PURE__ */ new Set();
+  _keepaliveDisposers = [];
+  _eventStore;
+  _seq = 0;
+  constructor(name, opts = {}) {
+    super(name, opts.graph);
+  }
+  destroy() {
+    for (const dispose of this._keepaliveDisposers) dispose();
+    this._keepaliveDisposers.length = 0;
+    super.destroy();
+  }
+  // -- Events ---------------------------------------------------------------
+  /**
+   * Register a named event stream backed by `reactiveLog`.
+   * Guard denies external `write` — only commands append internally.
+   */
+  event(name) {
+    const existing = this._eventLogs.get(name);
+    if (existing) return existing.node;
+    const log = reactiveLog([], { name });
+    const entries = log.entries;
+    const guarded = derived(
+      [entries],
+      ([snapshot]) => snapshot,
+      {
+        name,
+        describeKind: "state",
+        meta: cqrsMeta("event", { event_name: name }),
+        guard: EVENT_GUARD,
+        initial: entries.get()
+      }
+    );
+    this.add(name, guarded);
+    this._keepaliveDisposers.push(keepalive(guarded));
+    this._eventLogs.set(name, { log, node: guarded });
+    return guarded;
+  }
+  /** Internal: append to an event log, auto-registering if needed. */
+  _appendEvent(eventName, payload) {
+    let entry = this._eventLogs.get(eventName);
+    if (!entry) {
+      this.event(eventName);
+      entry = this._eventLogs.get(eventName);
+    }
+    if (entry.node.status === "completed" || entry.node.status === "errored") {
+      throw new Error(
+        `Cannot dispatch to terminated event stream "${eventName}" (status: ${entry.node.status}).`
+      );
+    }
+    const nv = entry.log.entries.v;
+    const evt = {
+      type: eventName,
+      payload,
+      timestampNs: wallClockNs(),
+      seq: ++this._seq,
+      ...nv != null ? { v0: { id: nv.id, version: nv.version } } : {}
+    };
+    entry.log.append(evt);
+    if (this._eventStore) {
+      this._eventStore.persist(evt);
+    }
+  }
+  // -- Commands -------------------------------------------------------------
+  /**
+   * Register a command with its handler. Guard denies `observe` (write-only).
+   * Use `dispatch(name, payload)` to execute.
+   *
+   * The command node carries dynamic `meta.error` — a reactive companion
+   * that holds the last handler error (or `null` on success).
+   */
+  command(name, handler) {
+    const cmdNode = state(void 0, {
+      name,
+      describeKind: "state",
+      meta: {
+        ...cqrsMeta("command", { command_name: name }),
+        error: null
+      },
+      guard: COMMAND_GUARD
+    });
+    this.add(name, cmdNode);
+    this._commandHandlers.set(name, handler);
+    return cmdNode;
+  }
+  /**
+   * Execute a registered command. Wraps the entire dispatch in `batch()` so
+   * the command node DATA and all emitted events settle atomically.
+   *
+   * If the handler throws, `meta.error` on the command node is set to the
+   * error and the exception is re-thrown.
+   */
+  dispatch(commandName, payload) {
+    const handler = this._commandHandlers.get(commandName);
+    if (!handler) {
+      throw new Error(`Unknown command: "${commandName}". Register with .command() first.`);
+    }
+    const cmdNode = this.resolve(commandName);
+    batch(() => {
+      cmdNode.down([[DATA, payload]], { internal: true });
+      try {
+        handler(payload, { emit: (eName, data) => this._appendEvent(eName, data) });
+        cmdNode.meta.error.down([[DATA, null]], { internal: true });
+      } catch (err) {
+        cmdNode.meta.error.down([[DATA, err]], { internal: true });
+        throw err;
+      }
+    });
+  }
+  // -- Projections ----------------------------------------------------------
+  /**
+   * Register a read-only projection derived from event streams.
+   * Guard denies `write` — value is computed from events only.
+   *
+   * **Purity contract:** The `reducer` must be a pure function — it receives
+   * the original `initial` on every invocation (full event-sourcing replay).
+   * Never mutate `initial`; always return a new value.
+   */
+  projection(name, eventNames, reducer, initial) {
+    const eventNodes = eventNames.map((eName) => {
+      if (!this._eventLogs.has(eName)) this.event(eName);
+      return this._eventLogs.get(eName).node;
+    });
+    const projNode = derived(
+      eventNodes,
+      (snapshots) => {
+        const allEvents = [];
+        for (const snapshot of snapshots) {
+          const snap = snapshot;
+          allEvents.push(...snap.value.entries);
+        }
+        allEvents.sort((a, b) => a.timestampNs - b.timestampNs || a.seq - b.seq);
+        return reducer(initial, allEvents);
+      },
+      {
+        name,
+        describeKind: "derived",
+        meta: cqrsMeta("projection", { projection_name: name, source_events: eventNames }),
+        guard: PROJECTION_GUARD,
+        initial
+      }
+    );
+    this.add(name, projNode);
+    for (const eName of eventNames) this.connect(eName, name);
+    this._keepaliveDisposers.push(keepalive(projNode));
+    this._projections.add(name);
+    return projNode;
+  }
+  // -- Sagas ----------------------------------------------------------------
+  /**
+   * Register an event-driven side effect. Runs handler for each **new** event
+   * from the specified streams (tracks last-processed entry count per stream).
+   *
+   * The saga node carries dynamic `meta.error` — a reactive companion that
+   * holds the last handler error (or `null` on success). Handler errors do
+   * not propagate out of the saga run (the event cursor still advances so
+   * the same entry is not delivered twice).
+   */
+  saga(name, eventNames, handler) {
+    const eventNodes = eventNames.map((eName) => {
+      if (!this._eventLogs.has(eName)) this.event(eName);
+      return this._eventLogs.get(eName).node;
+    });
+    const lastCounts = /* @__PURE__ */ new Map();
+    const sagaRef = {};
+    const sagaNode = node(
+      eventNodes,
+      (snapshots) => {
+        const errNode = sagaRef.n.meta.error;
+        for (let i = 0; i < snapshots.length; i++) {
+          const snap = snapshots[i];
+          const eName = eventNames[i];
+          const entries = snap.value.entries;
+          const lastCount = lastCounts.get(eName) ?? 0;
+          if (entries.length > lastCount) {
+            const newEntries = entries.slice(lastCount);
+            for (const entry of newEntries) {
+              try {
+                handler(entry);
+                errNode.down([[DATA, null]], { internal: true });
+              } catch (err) {
+                errNode.down([[DATA, err]], { internal: true });
+              }
+            }
+            lastCounts.set(eName, entries.length);
+          }
+        }
+      },
+      {
+        name,
+        describeKind: "effect",
+        meta: {
+          ...cqrsMeta("saga", { saga_name: name, source_events: eventNames }),
+          error: null
+        }
+      }
+    );
+    sagaRef.n = sagaNode;
+    this.add(name, sagaNode);
+    for (const eName of eventNames) this.connect(eName, name);
+    this._keepaliveDisposers.push(keepalive(sagaNode));
+    this._sagas.add(name);
+    return sagaNode;
+  }
+  // -- Event store ----------------------------------------------------------
+  useEventStore(adapter) {
+    this._eventStore = adapter;
+  }
+  /**
+   * Replay persisted events through a reducer to rebuild a read model.
+   * Requires an event store adapter wired via `useEventStore()`.
+   */
+  async rebuildProjection(eventNames, reducer, initial) {
+    if (!this._eventStore) {
+      throw new Error("No event store wired. Call useEventStore() first.");
+    }
+    const allEvents = [];
+    for (const eName of eventNames) {
+      const result = await this._eventStore.loadEvents(eName);
+      allEvents.push(...result.events);
+    }
+    allEvents.sort((a, b) => a.timestampNs - b.timestampNs || a.seq - b.seq);
+    return reducer(initial, allEvents);
+  }
+};
+function cqrs(name, opts) {
+  return new CqrsGraph(name, opts);
+}
+
+// src/compat/nestjs/module.ts
+var GraphReflyRootLifecycle = class {
+  constructor(graph) {
+    this.graph = graph;
+  }
+  onModuleDestroy() {
+    this.graph.destroy();
+  }
+};
+var GraphReflyRequestLifecycle = class {
+  graph = new Graph("request");
+  onModuleDestroy() {
+    this.graph.destroy();
+  }
+};
+var _GraphReflyModule_decorators, _init;
+_GraphReflyModule_decorators = [(0, import_common2.Module)({})];
+var _GraphReflyModule = class _GraphReflyModule {
+  /**
+   * Register the root `Graph` singleton in the NestJS DI container.
+   *
+   * The root graph is `@Global()` — injectable everywhere without importing
+   * the module again. Use `@InjectGraph()` to inject it.
+   *
+   * Lifecycle:
+   * - **init:** Graph created in factory. If `build` is provided, it runs
+   *   first (registers nodes/mounts). If `snapshot` is provided, values
+   *   are restored via `graph.restore()`.
+   * - **destroy:** Calls `graph.destroy()` — sends `[[TEARDOWN]]` to all
+   *   nodes, including mounted feature subgraphs (cascading teardown).
+   */
+  static forRoot(opts) {
+    const options = opts ?? {};
+    const graphName = options.name ?? "root";
+    const providers = [
+      {
+        provide: GRAPHREFLY_ROOT_GRAPH,
+        useFactory: () => {
+          const g = new Graph(graphName);
+          if (options.build) options.build(g);
+          if (options.snapshot) g.restore(options.snapshot);
+          return g;
+        }
+      },
+      {
+        provide: /* @__PURE__ */ Symbol.for("graphrefly:root-lifecycle"),
+        useFactory: (graph) => new GraphReflyRootLifecycle(graph),
+        inject: [GRAPHREFLY_ROOT_GRAPH]
+      },
+      {
+        provide: GraphReflyEventExplorer,
+        useFactory: (graph, moduleRef) => new GraphReflyEventExplorer(graph, moduleRef),
+        inject: [GRAPHREFLY_ROOT_GRAPH, import_core2.ModuleRef]
+      }
+    ];
+    if (options.nodes) {
+      for (const path of options.nodes) {
+        providers.push({
+          provide: getNodeToken(path),
+          useFactory: (graph) => graph.resolve(path),
+          inject: [GRAPHREFLY_ROOT_GRAPH]
+        });
+      }
+    }
+    if (options.requestScope) {
+      providers.push(
+        {
+          provide: /* @__PURE__ */ Symbol.for("graphrefly:request-lifecycle"),
+          useFactory: () => new GraphReflyRequestLifecycle(),
+          scope: import_common2.Scope.REQUEST
+        },
+        {
+          provide: GRAPHREFLY_REQUEST_GRAPH,
+          useFactory: (lifecycle) => lifecycle.graph,
+          inject: [/* @__PURE__ */ Symbol.for("graphrefly:request-lifecycle")],
+          scope: import_common2.Scope.REQUEST
+        }
+      );
+    }
+    return {
+      module: _GraphReflyModule,
+      global: true,
+      providers,
+      exports: [
+        GRAPHREFLY_ROOT_GRAPH,
+        ...(options.nodes ?? []).map(getNodeToken),
+        ...options.requestScope ? [GRAPHREFLY_REQUEST_GRAPH] : []
+      ]
+    };
+  }
+  /**
+   * Register a feature subgraph that auto-mounts into the root graph.
+   *
+   * The feature graph is created in the factory, built/restored, then
+   * mounted into root via `root.mount(name, featureGraph)`. On app
+   * shutdown, root's `graph.destroy()` cascades TEARDOWN through all
+   * mounted subgraphs (no explicit remove needed).
+   *
+   * Node tokens are auto-qualified as `featureName::path` to prevent
+   * collisions between features declaring nodes with the same local name.
+   *
+   * Injectable via `@InjectGraph(name)`.
+   */
+  static forFeature(opts) {
+    const providers = [
+      {
+        provide: getGraphToken(opts.name),
+        useFactory: (rootGraph) => {
+          const g = new Graph(opts.name);
+          if (opts.build) opts.build(g);
+          if (opts.snapshot) g.restore(opts.snapshot);
+          rootGraph.mount(opts.name, g);
+          return g;
+        },
+        inject: [GRAPHREFLY_ROOT_GRAPH]
+      }
+    ];
+    if (opts.nodes) {
+      for (const path of opts.nodes) {
+        providers.push({
+          provide: getNodeToken(`${opts.name}::${path}`),
+          useFactory: (graph) => graph.resolve(path),
+          inject: [getGraphToken(opts.name)]
+        });
+      }
+    }
+    return {
+      module: _GraphReflyModule,
+      providers,
+      exports: [
+        getGraphToken(opts.name),
+        ...(opts.nodes ?? []).map((p) => getNodeToken(`${opts.name}::${p}`))
+      ]
+    };
+  }
+  /**
+   * Register a CQRS subgraph that auto-mounts into the root graph.
+   *
+   * Creates a `CqrsGraph` via the `cqrs()` factory (roadmap §4.5), mounts it
+   * into the root graph, and exposes it for DI via `@InjectGraph(name)`.
+   *
+   * CQRS decorators (`@CommandHandler`, `@EventHandler`, `@QueryHandler`,
+   * `@SagaHandler`) are discovered by the explorer and wired to this graph
+   * on module init.
+   *
+   * @example
+   * ```ts
+   * GraphReflyModule.forCqrs({
+   *   name: "orders",
+   *   build: (g) => {
+   *     g.event("orderPlaced");
+   *     g.projection("orderCount", ["orderPlaced"], (_s, evts) => evts.length, 0);
+   *   },
+   * })
+   * ```
+   */
+  static forCqrs(opts) {
+    const providers = [
+      {
+        provide: getGraphToken(opts.name),
+        useFactory: (rootGraph) => {
+          const g = cqrs(opts.name, opts.cqrs);
+          if (opts.eventStore) g.useEventStore(opts.eventStore);
+          if (opts.build) opts.build(g);
+          rootGraph.mount(opts.name, g);
+          return g;
+        },
+        inject: [GRAPHREFLY_ROOT_GRAPH]
+      }
+    ];
+    if (opts.nodes) {
+      for (const path of opts.nodes) {
+        providers.push({
+          provide: getNodeToken(`${opts.name}::${path}`),
+          useFactory: (graph) => graph.resolve(path),
+          inject: [getGraphToken(opts.name)]
+        });
+      }
+    }
+    return {
+      module: _GraphReflyModule,
+      providers,
+      exports: [
+        getGraphToken(opts.name),
+        ...(opts.nodes ?? []).map((p) => getNodeToken(`${opts.name}::${p}`))
+      ]
+    };
+  }
+};
+_init = __decoratorStart(null);
+_GraphReflyModule = __decorateElement(_init, 0, "GraphReflyModule", _GraphReflyModule_decorators, _GraphReflyModule);
+__runInitializers(_init, 1, _GraphReflyModule);
+var GraphReflyModule = _GraphReflyModule;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACTOR_KEY,
+  COMMAND_HANDLERS,
+  CQRS_EVENT_HANDLERS,
+  CRON_HANDLERS,
+  CommandHandler,
+  EVENT_HANDLERS,
+  EventHandler,
+  GRAPHREFLY_REQUEST_GRAPH,
+  GRAPHREFLY_ROOT_GRAPH,
+  GraphCron,
+  GraphInterval,
+  GraphReflyEventExplorer,
+  GraphReflyGuard,
+  GraphReflyGuardImpl,
+  GraphReflyModule,
+  INTERVAL_HANDLERS,
+  InjectCqrsGraph,
+  InjectGraph,
+  InjectNode,
+  ObserveGateway,
+  OnGraphEvent,
+  QUERY_HANDLERS,
+  QueryHandler,
+  SAGA_HANDLERS,
+  SagaHandler,
+  fromHeader,
+  fromJwtPayload,
+  getActor,
+  getGraphToken,
+  getNodeToken,
+  observeGraph$,
+  observeNode$,
+  observeSSE,
+  observeSubscription,
+  toMessages$,
+  toObservable
+});
+//# sourceMappingURL=index.cjs.map