@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/compat/nestjs/index.cjs

@@ -1,8 +1,19 @@
 "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))
@@ -11,11 +22,2222 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 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,
+  observeSSE: () => observeSSE,
+  observeSubscription: () => observeSubscription,
+  toObservable: () => toObservable
+});
 module.exports = __toCommonJS(nestjs_exports);
-__reExport(nestjs_exports, require("@graphrefly/pure-ts/compat/nestjs"), module.exports);
+
+// src/base/composition/observable.ts
+var import_core = require("@graphrefly/pure-ts/core");
+var import_rxjs = require("rxjs");
+function toObservable(node4, options) {
+  if (options?.raw) {
+    return new import_rxjs.Observable((subscriber) => {
+      const unsub = node4.subscribe((msgs) => {
+        if (subscriber.closed) return;
+        subscriber.next(msgs);
+        for (const m of msgs) {
+          if (m[0] === import_core.ERROR) {
+            subscriber.error(m[1]);
+            return;
+          }
+          if (m[0] === import_core.COMPLETE) {
+            subscriber.complete();
+            return;
+          }
+        }
+      });
+      return unsub;
+    });
+  }
+  return new import_rxjs.Observable((subscriber) => {
+    const unsub = node4.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (subscriber.closed) return;
+        if (m[0] === import_core.DATA) {
+          subscriber.next(m[1]);
+        } else if (m[0] === import_core.ERROR) {
+          subscriber.error(m[1]);
+          return;
+        } else if (m[0] === import_core.COMPLETE) {
+          subscriber.complete();
+          return;
+        }
+      }
+    });
+    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/compat/nestjs/explorer.ts
+var import_core3 = require("@graphrefly/pure-ts/core");
+var import_extra = require("@graphrefly/pure-ts/extra");
+
+// src/base/sources/event/cron.ts
+var import_core2 = require("@graphrefly/pure-ts/core");
+function sourceOpts(opts) {
+  return { describeKind: "producer", ...opts };
+}
+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());
+}
+function fromCron(expr, opts) {
+  const schedule = parseCron(expr);
+  const { tickMs: tickOpt, output, ...rest } = opts ?? {};
+  const tickMs = tickOpt ?? 6e4;
+  const emitDate = output === "date";
+  return (0, import_core2.node)(
+    (_data, 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 : (0, import_core2.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] === import_core3.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 = (0, import_extra.fromTimer)(meta.ms, { period: meta.ms, name: nodeName });
+    this.graph.add(timerNode);
+    this.scheduleNodeNames.push(nodeName);
+    const handle = this.observeNode(nodeName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === import_core3.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(cronNode);
+    this.scheduleNodeNames.push(nodeName);
+    const handle = this.observeNode(nodeName);
+    const unsub = handle.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] === import_core3.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 existingEntries = eventNode.cache;
+    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] === import_core3.DATA) {
+          const entries = m[1];
+          for (const entry of 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] === import_core3.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/compat/nestjs/gateway.ts
+var import_core5 = require("@graphrefly/pure-ts/core");
+
+// src/base/composition/backpressure.ts
+var import_core4 = require("@graphrefly/pure-ts/core");
+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([[import_core4.PAUSE, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    onDequeue() {
+      if (pending > 0) pending -= 1;
+      if (paused && pending <= opts.lowWaterMark) {
+        paused = false;
+        sendUp([[import_core4.RESUME, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    get pending() {
+      return pending;
+    },
+    get paused() {
+      return paused;
+    },
+    dispose() {
+      if (paused) {
+        paused = false;
+        sendUp([[import_core4.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 === import_core5.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 === import_core5.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 === import_core5.COMPLETE || t === import_core5.TEARDOWN) {
+            if (t === import_core5.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 === import_core5.DATA) {
+        const value = msg[1];
+        if (filter && !filter(value)) continue;
+        push({ done: false, value });
+      } else if (t === import_core5.ERROR) {
+        const err = msg[1] instanceof Error ? msg[1] : new Error(String(msg[1]));
+        push({ done: true, error: err });
+        dispose();
+        return;
+      } else if (t === import_core5.COMPLETE || t === import_core5.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 === import_core5.DATA) {
+          wm?.onEnqueue();
+          trySend(send, { type: "data", path, value: msg[1] });
+        } else if (t === import_core5.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 === import_core5.COMPLETE || t === import_core5.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 import_core6 = require("@graphrefly/pure-ts/core");
+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 ? (0, import_core6.normalizeActor)(actor) : import_core6.DEFAULT_ACTOR;
+}
+var GraphReflyGuardImpl = class {
+  constructor(extractor) {
+    this.extractor = extractor;
+  }
+  canActivate(context) {
+    const actor = (0, import_core6.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_graph3 = require("@graphrefly/pure-ts/graph");
+var import_common2 = require("@nestjs/common");
+var import_core9 = require("@nestjs/core");
+
+// src/utils/cqrs/index.ts
+var import_core8 = require("@graphrefly/pure-ts/core");
+var import_extra3 = require("@graphrefly/pure-ts/extra");
+var import_graph2 = require("@graphrefly/pure-ts/graph");
+
+// src/base/mutation/index.ts
+var import_core7 = require("@graphrefly/pure-ts/core");
+var import_extra2 = require("@graphrefly/pure-ts/extra");
+var import_graph = require("@graphrefly/pure-ts/graph");
+var DEFAULT_AUDIT_GUARD = (0, import_core7.policy)((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+function createAuditLog(opts) {
+  const log = (0, import_extra2.reactiveLog)([], {
+    name: opts.name,
+    maxSize: opts.retainedLimit ?? 1024,
+    guard: opts.guard ?? DEFAULT_AUDIT_GUARD,
+    ...opts.versioning != null ? { versioning: opts.versioning } : {}
+  });
+  log.withLatest();
+  if (opts.graph) {
+    opts.graph.add(log.entries, { name: opts.name });
+  }
+  return log;
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const k of Object.keys(value)) {
+    deepFreeze(value[k]);
+  }
+  return Object.freeze(value);
+}
+function mutate(act, opts) {
+  const { up, down } = typeof act === "function" ? { up: act, down: void 0 } : act;
+  const freeze = opts.freeze ?? true;
+  if (opts.frame === "inline") {
+    return function wrapped(...args) {
+      const sealed = freeze ? args.map(deepFreeze) : args;
+      const t_ns = (0, import_core7.wallClockNs)();
+      const seq = opts.seq ? bumpCursor(opts.seq) : void 0;
+      try {
+        const result = up(...sealed);
+        if (opts.log && opts.onSuccessRecord) {
+          appendAudit(
+            opts.log,
+            opts.onSuccessRecord,
+            sealed,
+            result,
+            { t_ns, seq },
+            opts.handlerVersion
+          );
+        }
+        return result;
+      } catch (err) {
+        if (opts.log && opts.onFailureRecord) {
+          const errorType = err instanceof Error ? err.name : typeof err;
+          appendAudit(
+            opts.log,
+            opts.onFailureRecord,
+            sealed,
+            err,
+            { t_ns, seq, errorType },
+            opts.handlerVersion
+          );
+        }
+        throw err;
+      }
+    };
+  }
+  return function wrapped(...args) {
+    const sealed = freeze ? args.map(deepFreeze) : args;
+    const t_ns = (0, import_core7.wallClockNs)();
+    let result;
+    let captured;
+    let captureSet = false;
+    let seq;
+    try {
+      (0, import_core7.batch)(() => {
+        if (opts.seq) seq = bumpCursor(opts.seq);
+        try {
+          result = up(...sealed);
+          if (opts.log && opts.onSuccessRecord) {
+            appendAudit(
+              opts.log,
+              opts.onSuccessRecord,
+              sealed,
+              result,
+              { t_ns, seq },
+              opts.handlerVersion
+            );
+          }
+        } catch (err) {
+          captured = err;
+          captureSet = true;
+          throw err;
+        }
+      });
+    } catch (outerErr) {
+      if (captureSet && down) {
+        try {
+          down(...sealed);
+        } catch (downErr) {
+          console.error(
+            `mutate: down hook threw \u2014 original action error preserved (${captured instanceof Error ? captured.name : typeof captured}). Down error:`,
+            downErr
+          );
+        }
+      }
+      if (captureSet && opts.log && opts.onFailureRecord) {
+        const errorType = captured instanceof Error ? captured.name : typeof captured;
+        appendAudit(
+          opts.log,
+          opts.onFailureRecord,
+          sealed,
+          captured,
+          { t_ns, seq, errorType },
+          opts.handlerVersion
+        );
+      }
+      throw captureSet ? captured : outerErr;
+    }
+    return result;
+  };
+}
+var _bumpCursorWarned = /* @__PURE__ */ new WeakSet();
+function bumpCursor(seq) {
+  const raw = seq.cache;
+  const valid = typeof raw === "number" && Number.isFinite(raw);
+  if (!valid && raw !== void 0 && !_bumpCursorWarned.has(seq)) {
+    _bumpCursorWarned.add(seq);
+    console.warn(
+      `bumpCursor: cursor cache held a non-numeric value (${String(raw)}); resetting to 0. Causes include: a snapshot codec round-tripping the cursor as a string / null / NaN, OR a malformed initial seed (e.g. state<number>(NaN)). Audit consumers may see colliding seq values after this point.`
+    );
+  }
+  const cur = valid ? raw : 0;
+  const next = cur + 1;
+  seq.down([[import_core7.DIRTY], [import_core7.DATA, next]]);
+  return next;
+}
+function appendAudit(audit, builder, args, value, meta, handlerVersion) {
+  const record = builder(args, value, meta);
+  if (record === void 0) return;
+  const stamped = handlerVersion != null ? { ...record, handlerVersion } : record;
+  audit.append(stamped);
+}
+function registerCursor(graph, name, initial = 0) {
+  const cursor = (0, import_core7.node)([], { initial, name, describeKind: "state" });
+  graph.add(cursor, { name });
+  return cursor;
+}
+function registerCursorMap(graph, name, keys, initial = 0) {
+  const out = {};
+  const sub = new import_graph.Graph(name);
+  for (const k of keys) {
+    const cursor = (0, import_core7.node)([], {
+      initial,
+      name: k,
+      describeKind: "state"
+    });
+    sub.add(cursor, { name: k });
+    out[k] = cursor;
+  }
+  graph.mount(name, sub);
+  return out;
+}
+
+// src/utils/_errors/index.ts
+var GraphReFlyError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+};
+var DuplicateRegistrationError = class extends GraphReFlyError {
+  constructor(kind, registrationName) {
+    super(`Duplicate ${kind} registration: "${registrationName}"`);
+    this.kind = kind;
+    this.registrationName = registrationName;
+  }
+};
+var UndeclaredEmitError = class extends GraphReFlyError {
+  constructor(commandName, eventName, declaredEmits) {
+    super(
+      `Command "${commandName}" emitted undeclared event "${eventName}". Declared emits: [${declaredEmits.join(", ")}]`
+    );
+    this.commandName = commandName;
+    this.eventName = eventName;
+    this.declaredEmits = declaredEmits;
+  }
+};
+var OptimisticConcurrencyError = class extends GraphReFlyError {
+  constructor(aggregateId, expected, actual) {
+    super(
+      `Optimistic concurrency conflict on aggregate "${aggregateId}": expected version ${expected}, got ${actual}`
+    );
+    this.aggregateId = aggregateId;
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
+var UnknownCommandError = class extends GraphReFlyError {
+  constructor(commandName) {
+    super(`Unknown command: "${commandName}". Register with command() first.`);
+    this.commandName = commandName;
+  }
+};
+var CommandHandlerError = class extends GraphReFlyError {
+  constructor(commandName, cause) {
+    super(
+      `Command handler "${commandName}" threw: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.commandName = commandName;
+  }
+};
+var RebuildError = class extends GraphReFlyError {
+  constructor(projectionName, cause) {
+    super(
+      `Projection "${projectionName}" rebuild failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.projectionName = projectionName;
+  }
+};
+
+// src/utils/cqrs/index.ts
+var import_extra4 = require("@graphrefly/pure-ts/extra");
+
+// src/base/meta/domain-meta.ts
+function domainMeta(domain, kind, extra) {
+  return {
+    [domain]: true,
+    [`${domain}_type`]: kind,
+    ...extra ?? {}
+  };
+}
+
+// src/utils/cqrs/index.ts
+var COMMAND_GUARD = (0, import_core8.policy)((allow, deny) => {
+  allow("write");
+  allow("signal");
+  deny("observe");
+});
+var PROJECTION_GUARD = (0, import_core8.policy)((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+var EVENT_GUARD = (0, import_core8.policy)((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+function cqrsMeta(kind, extra) {
+  return domainMeta("cqrs", kind, extra);
+}
+function deepFreeze2(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const k of Object.keys(value)) {
+    deepFreeze2(value[k]);
+  }
+  return Object.freeze(value);
+}
+var CqrsGraph = class extends import_graph2.Graph {
+  /** Fan-in event streams (one per type, all aggregates merged). */
+  _eventLogs = /* @__PURE__ */ new Map();
+  /**
+   * Per-aggregate event streams: type → aggregateId → entry. Used for
+   * `event(type, aggregateId)` dual-form access and per-aggregate version
+   * tracking. Only populated when an event with `aggregateId` is emitted.
+   */
+  _eventLogsByAggregate = /* @__PURE__ */ new Map();
+  /** Per-aggregate version counters: `${type}::${aggregateId}` → current version. */
+  _aggregateVersions = /* @__PURE__ */ new Map();
+  /**
+   * LRU access order for `${type}::${aggregateId}`. Map insertion order
+   * tracks recency — `delete` + `set` on access moves to the end.
+   */
+  _aggregateLru = /* @__PURE__ */ new Map();
+  _commandRegs = /* @__PURE__ */ new Map();
+  _projections = /* @__PURE__ */ new Set();
+  _sagas = /* @__PURE__ */ new Set();
+  _seq = 0;
+  _retainedLimit;
+  _freezeCommandPayload;
+  _freezeEventPayload;
+  _maxAggregates;
+  _dispatchSeqCursor;
+  /** Audit log of every command dispatch (Audit 2). */
+  dispatches;
+  /** Alias for {@link CqrsGraph.dispatches} (Audit 2 `.audit` duplication). */
+  audit;
+  /** Per-aggregate LRU eviction observability; secondary log to `dispatches`. */
+  aggregateEvictions;
+  constructor(name, opts = {}) {
+    super(name, opts.graph);
+    this._retainedLimit = opts.retainedLimit ?? 1024;
+    this._freezeCommandPayload = opts.freezeCommandPayload ?? true;
+    this._freezeEventPayload = opts.freezeEventPayload ?? true;
+    this._maxAggregates = opts.maxAggregates ?? 1e4;
+    this.dispatches = createAuditLog({
+      name: "dispatches",
+      retainedLimit: this._retainedLimit,
+      graph: this
+    });
+    this.audit = this.dispatches;
+    this.aggregateEvictions = createAuditLog({
+      name: "aggregateEvictions",
+      retainedLimit: this._retainedLimit,
+      graph: this
+    });
+    this._dispatchSeqCursor = registerCursor(this, "dispatch_seq", 0);
+  }
+  /**
+   * Read the current per-aggregate version (last emitted `aggregateVersion`
+   * for that `(type, aggregateId)` pair). Returns `0` if no events have been
+   * emitted yet for this aggregate. Useful for callers preparing
+   * {@link DispatchOptions.expectedAggregateVersion}.
+   */
+  aggregateVersion(type, aggregateId) {
+    return this._aggregateVersions.get(`${type}::${aggregateId}`) ?? 0;
+  }
+  /** LRU touch — moves the key to the end of the access order. */
+  _touchAggregate(key) {
+    this._aggregateLru.delete(key);
+    this._aggregateLru.set(key, true);
+  }
+  /**
+   * Evict the oldest aggregate streams (least-recently-touched) until the
+   * aggregate count is back within `_maxAggregates`. Emits one
+   * `AggregateEvictionRecord` per eviction. The fan-in stream is NOT touched
+   * — events stay in the type-level log; only the per-aggregate stream and
+   * version counter are removed.
+   */
+  _enforceAggregateLru() {
+    while (this._aggregateLru.size > this._maxAggregates) {
+      const oldest = this._aggregateLru.keys().next();
+      if (oldest.done) break;
+      const key = oldest.value;
+      this._aggregateLru.delete(key);
+      const sep = key.indexOf("::");
+      if (sep < 0) continue;
+      const type = key.slice(0, sep);
+      const aggregateId = key.slice(sep + 2);
+      const lastVersion = this._aggregateVersions.get(key) ?? 0;
+      this._aggregateVersions.delete(key);
+      const byType = this._eventLogsByAggregate.get(type);
+      if (byType) {
+        byType.delete(aggregateId);
+        if (byType.size === 0) this._eventLogsByAggregate.delete(type);
+      }
+      this.aggregateEvictions.append({
+        aggregateId,
+        type,
+        lastVersion,
+        t_ns: (0, import_core8.wallClockNs)()
+      });
+    }
+  }
+  /** Tiers attached via {@link attachEventStorage}; auto-wired into future event streams. */
+  _attachedEventTiers = [];
+  _attachedTierDisposers = /* @__PURE__ */ new Map();
+  /**
+   * Wire append-log storage tiers for ALL CQRS event streams — both currently
+   * registered AND any future streams created via `event(name)` /
+   * `event(name, aggregateId)` / handler emit. (M4 fix.)
+   *
+   * Returns a disposer that releases all storage subscriptions wired by this
+   * call (including those for streams that were created after the call).
+   */
+  attachEventStorage(tiers) {
+    this._attachedEventTiers.push(tiers);
+    for (const [name, entry] of this._eventLogs) {
+      const dispose = entry.log.attachStorage(tiers);
+      let arr = this._attachedTierDisposers.get(name);
+      if (!arr) {
+        arr = [];
+        this._attachedTierDisposers.set(name, arr);
+      }
+      arr.push(dispose);
+    }
+    for (const [type, byAgg] of this._eventLogsByAggregate) {
+      for (const [aggId, entry] of byAgg) {
+        const key = `${type}::${aggId}`;
+        const dispose = entry.log.attachStorage(tiers);
+        let arr = this._attachedTierDisposers.get(key);
+        if (!arr) {
+          arr = [];
+          this._attachedTierDisposers.set(key, arr);
+        }
+        arr.push(dispose);
+      }
+    }
+    return () => {
+      const idx = this._attachedEventTiers.indexOf(tiers);
+      if (idx >= 0) this._attachedEventTiers.splice(idx, 1);
+    };
+  }
+  /** Wire newly-created event stream into all currently-attached tier sets. */
+  _autoWireStreamStorage(key, log) {
+    if (this._attachedEventTiers.length === 0) return;
+    let arr = this._attachedTierDisposers.get(key);
+    if (!arr) {
+      arr = [];
+      this._attachedTierDisposers.set(key, arr);
+    }
+    for (const tiers of this._attachedEventTiers) {
+      arr.push(log.attachStorage(tiers));
+    }
+  }
+  event(name, aggregateId) {
+    if (aggregateId !== void 0) {
+      return this._ensureAggregateStream(name, aggregateId).node;
+    }
+    const existing = this._eventLogs.get(name);
+    if (existing) return existing.node;
+    const log = (0, import_extra3.reactiveLog)([], {
+      name,
+      versioning: 0,
+      maxSize: this._retainedLimit
+    });
+    log.withLatest();
+    const entries = log.entries;
+    const guarded = this.derived(
+      name,
+      [entries],
+      (batchData, ctx) => {
+        const latest = batchData[0] != null && batchData[0].length > 0 ? batchData[0].at(-1) : ctx.prevData[0];
+        return [latest];
+      },
+      {
+        meta: cqrsMeta("event", { event_name: name }),
+        guard: EVENT_GUARD,
+        initial: entries.cache
+      }
+    );
+    this.addDisposer((0, import_extra4.keepalive)(guarded));
+    this._eventLogs.set(name, { log, node: guarded });
+    this._autoWireStreamStorage(name, log);
+    return guarded;
+  }
+  /**
+   * Get-or-create the per-aggregate event stream for `(type, aggregateId)`.
+   * Mounts the stream as a sibling node named `<type>_<aggregateId>` so it
+   * appears in `describe()`. LRU access is touched on every call.
+   */
+  _ensureAggregateStream(type, aggregateId) {
+    if (!this._eventLogs.has(type)) this.event(type);
+    let byType = this._eventLogsByAggregate.get(type);
+    if (!byType) {
+      byType = /* @__PURE__ */ new Map();
+      this._eventLogsByAggregate.set(type, byType);
+    }
+    const lruKey = `${type}::${aggregateId}`;
+    this._touchAggregate(lruKey);
+    const existing = byType.get(aggregateId);
+    if (existing) return existing;
+    const nodeName = `${type}_${aggregateId.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+    const log = (0, import_extra3.reactiveLog)([], {
+      name: nodeName,
+      versioning: 0,
+      maxSize: this._retainedLimit
+    });
+    log.withLatest();
+    const entries = log.entries;
+    let mountName = nodeName;
+    let collisionIdx = 0;
+    while (this.resolveOptional(mountName) !== void 0) {
+      collisionIdx += 1;
+      mountName = `${nodeName}_${collisionIdx}`;
+    }
+    let guarded;
+    try {
+      guarded = this.derived(
+        mountName,
+        [entries],
+        (batchData, ctx) => {
+          const latest = batchData[0] != null && batchData[0].length > 0 ? batchData[0].at(-1) : ctx.prevData[0];
+          return [latest];
+        },
+        {
+          meta: cqrsMeta("event_aggregate", {
+            event_name: type,
+            aggregate_id: aggregateId
+          }),
+          guard: EVENT_GUARD,
+          initial: entries.cache
+        }
+      );
+    } catch {
+      guarded = (0, import_core8.node)(
+        [entries],
+        (batchData, actions, ctx) => {
+          const latest = batchData[0] != null && batchData[0].length > 0 ? batchData[0].at(-1) : ctx.prevData[0];
+          actions.emit(latest);
+        },
+        {
+          name: nodeName,
+          describeKind: "derived",
+          meta: cqrsMeta("event_aggregate", {
+            event_name: type,
+            aggregate_id: aggregateId
+          }),
+          guard: EVENT_GUARD,
+          initial: entries.cache
+        }
+      );
+    }
+    this.addDisposer((0, import_extra4.keepalive)(guarded));
+    const entry = { log, node: guarded };
+    byType.set(aggregateId, entry);
+    this._autoWireStreamStorage(`${type}::${aggregateId}`, log);
+    this._enforceAggregateLru();
+    return entry;
+  }
+  /** Try `resolve(path)`; return `undefined` instead of throwing on missing. */
+  resolveOptional(path) {
+    try {
+      return this.resolve(path);
+    } catch {
+      return void 0;
+    }
+  }
+  /** Internal: append to an event log, auto-registering if needed. */
+  _appendEvent(eventName, payload, extra) {
+    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}).`
+      );
+    }
+    let aggregateVersion;
+    let aggregateEntry;
+    if (extra?.aggregateId !== void 0) {
+      const lruKey = `${eventName}::${extra.aggregateId}`;
+      aggregateVersion = (this._aggregateVersions.get(lruKey) ?? 0) + 1;
+      this._aggregateVersions.set(lruKey, aggregateVersion);
+      aggregateEntry = this._ensureAggregateStream(eventName, extra.aggregateId);
+    }
+    const nv = entry.log.entries.v;
+    const frozenPayload = this._freezeEventPayload ? deepFreeze2(payload) : payload;
+    const evt = {
+      type: eventName,
+      payload: frozenPayload,
+      timestampNs: (0, import_core8.wallClockNs)(),
+      seq: ++this._seq,
+      ...extra?.aggregateId !== void 0 ? { aggregateId: extra.aggregateId } : {},
+      ...aggregateVersion !== void 0 ? { aggregateVersion } : {},
+      ...extra?.correlationId !== void 0 ? { correlationId: extra.correlationId } : {},
+      ...extra?.causationId !== void 0 ? { causationId: extra.causationId } : {},
+      ...extra?.metadata !== void 0 ? { metadata: Object.freeze({ ...extra.metadata }) } : {},
+      ...extra?.handlerVersion !== void 0 ? { handlerVersion: extra.handlerVersion } : {},
+      ...nv != null ? { v0: { id: nv.id, version: nv.version } } : {}
+    };
+    entry.log.append(evt);
+    if (aggregateEntry) {
+      aggregateEntry.log.append(evt);
+    }
+    return 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, handlerOrReg) {
+    if (this._commandRegs.has(name)) {
+      throw new DuplicateRegistrationError("command", name);
+    }
+    const reg = typeof handlerOrReg === "function" ? { handler: handlerOrReg } : handlerOrReg;
+    const cmdNode = this.state(name, void 0, {
+      meta: {
+        ...cqrsMeta("command", { command_name: name }),
+        error: null
+      },
+      guard: COMMAND_GUARD
+    });
+    this._commandRegs.set(name, {
+      handler: reg.handler,
+      ...reg.emits !== void 0 ? { emits: reg.emits } : {},
+      ...reg.handlerVersion !== void 0 ? { handlerVersion: reg.handlerVersion } : {}
+    });
+    if (reg.emits) {
+      for (const e of reg.emits) {
+        if (!this._eventLogs.has(e)) this.event(e);
+      }
+    }
+    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.
+   *
+   * **Tier 8 / COMPOSITION-GUIDE §35:** dispatch routes through the shared
+   * {@link mutate} framework so freeze / rollback-on-throw / seq-cursor
+   * advance / audit-record stamping flow through one centralized helper.
+   * Failure records emit OUTSIDE the rolled-back batch (M5 / C4 invariants
+   * preserved by the framework).
+   */
+  dispatch(commandName, payload, opts) {
+    const reg = this._commandRegs.get(commandName);
+    if (!reg) throw new UnknownCommandError(commandName);
+    if (opts?.aggregateId !== void 0 && opts.expectedAggregateVersion !== void 0 && reg.emits !== void 0) {
+      let observedVersion = 0;
+      for (const t of reg.emits) {
+        const v = this._aggregateVersions.get(`${t}::${opts.aggregateId}`);
+        if (v !== void 0 && v > observedVersion) observedVersion = v;
+      }
+      if (observedVersion !== opts.expectedAggregateVersion) {
+        throw new OptimisticConcurrencyError(
+          opts.aggregateId,
+          opts.expectedAggregateVersion,
+          observedVersion
+        );
+      }
+    }
+    const cmdNode = this.resolve(commandName);
+    const emittedEvents = [];
+    let actionThrew = false;
+    const action = (sealed) => {
+      cmdNode.emit(sealed, { internal: true });
+      try {
+        reg.handler(sealed, {
+          emit: (eName, data) => {
+            if (reg.emits !== void 0 && !reg.emits.includes(eName)) {
+              throw new UndeclaredEmitError(commandName, eName, reg.emits);
+            }
+            emittedEvents.push(eName);
+            this._appendEvent(eName, data, {
+              // D1: thread the dispatch's aggregateId through so events
+              // participate in per-aggregate versioning. Handlers can
+              // override per-emit by passing their own through a richer
+              // emit signature (future extension).
+              ...opts?.aggregateId !== void 0 ? { aggregateId: opts.aggregateId } : {},
+              ...opts?.correlationId !== void 0 ? { correlationId: opts.correlationId } : {},
+              ...opts?.causationId !== void 0 ? { causationId: opts.causationId } : {},
+              ...opts?.metadata !== void 0 ? { metadata: Object.freeze({ ...opts.metadata }) } : {},
+              ...reg.handlerVersion !== void 0 ? { handlerVersion: reg.handlerVersion } : {}
+            });
+          }
+        });
+        cmdNode.meta.error.emit(null, { internal: true });
+      } catch (err) {
+        actionThrew = true;
+        throw err;
+      }
+    };
+    try {
+      mutate(action, {
+        frame: "transactional",
+        log: this.dispatches,
+        seq: this._dispatchSeqCursor,
+        freeze: this._freezeCommandPayload,
+        onSuccessRecord: ([sealed], _result, { t_ns, seq }) => ({
+          commandName,
+          payload: sealed,
+          outcome: "success",
+          emittedEvents: [...emittedEvents],
+          t_ns,
+          seq: seq ?? 0,
+          ...reg.handlerVersion !== void 0 ? { handlerVersion: reg.handlerVersion } : {}
+        }),
+        onFailureRecord: ([sealed], err, { t_ns, seq, errorType }) => {
+          const wrapped = err instanceof CommandHandlerError ? err : new CommandHandlerError(commandName, err);
+          return {
+            commandName,
+            payload: sealed,
+            outcome: "failure",
+            error: wrapped,
+            errorType,
+            emittedEvents: [...emittedEvents],
+            t_ns,
+            seq: seq ?? 0,
+            ...reg.handlerVersion !== void 0 ? { handlerVersion: reg.handlerVersion } : {}
+          };
+        }
+      })(payload);
+    } catch (outerErr) {
+      if (actionThrew) {
+        cmdNode.meta.error.emit(outerErr, { internal: true });
+      }
+      throw outerErr;
+    }
+  }
+  // -- Projections ----------------------------------------------------------
+  /**
+   * Register a read-only projection derived from event streams.
+   * Guard denies `write` — value is computed from events only.
+   *
+   * **Wave C.3 Unit 21 (locked 2026-04-24):**
+   * - Object-bag signature replaces the positional `(name, events, reducer, initial)` form.
+   * - `mode: "scan"` (default) — incremental fold; `"replay"` — full replay each wave.
+   * - `snapshot` integration for cold-start load + auto-checkpoint save.
+   * - `freezeInputs` (default `true`) — freeze the event array before passing to reducer.
+   * - Returns `ProjectionController<TState>` with `.node`, `.rebuild()`, `.reset()`.
+   *
+   * Fan-in across `events` is implemented by depending on all event-type fan-in
+   * nodes directly, which preserves `describe()` edges (e.g. `orderPlaced →
+   * orderCount`). Events are sorted by `(timestampNs, seq, aggregateId)` before
+   * passing to the reducer (Option-3 cross-aggregate ordering, C.3).
+   */
+  projection(opts) {
+    const { name, events: eventNames, reducer, initial } = opts;
+    const mode = opts.mode ?? "scan";
+    const freezeInputs = opts.freezeInputs ?? true;
+    const snapshotOpts = opts.snapshot;
+    const eventNodes = eventNames.map((eName) => {
+      if (!this._eventLogs.has(eName)) this.event(eName);
+      return this._eventLogs.get(eName).node;
+    });
+    function sortEvents(evts) {
+      evts.sort(
+        (a, b) => a.timestampNs - b.timestampNs || a.seq - b.seq || (a.aggregateId ?? "").localeCompare(b.aggregateId ?? "")
+      );
+    }
+    function collectAllEvents(snapshots) {
+      const evts = [];
+      for (const snap of snapshots) evts.push(...snap);
+      sortEvents(evts);
+      return evts;
+    }
+    const seedSnapshots = eventNodes.map(
+      (n) => n.cache ?? []
+    );
+    const sortedSeed = collectAllEvents(seedSnapshots);
+    const frozenSeed = freezeInputs ? Object.freeze(sortedSeed) : sortedSeed;
+    let lastProcessedCount = 0;
+    let scanState = initial;
+    if (mode === "scan" && sortedSeed.length > 0) {
+      scanState = reducer(initial, frozenSeed);
+      lastProcessedCount = sortedSeed.length;
+    }
+    const seedState = mode === "replay" ? reducer(initial, frozenSeed) : scanState;
+    const saveDebounceMs = snapshotOpts?.saveDebounceMs ?? 1e3;
+    const saveEvery = snapshotOpts?.saveEvery ?? 1e3;
+    let saveTimer;
+    let savesSinceLastFlush = 0;
+    function scheduleSave(currentState) {
+      if (!snapshotOpts?.save) return;
+      savesSinceLastFlush += 1;
+      if (savesSinceLastFlush >= saveEvery) {
+        savesSinceLastFlush = 0;
+        if (saveTimer !== void 0) {
+          clearTimeout(saveTimer);
+          saveTimer = void 0;
+        }
+        const result = snapshotOpts.save(currentState);
+        if (result instanceof Promise) result.catch(() => void 0);
+        return;
+      }
+      if (saveTimer !== void 0) clearTimeout(saveTimer);
+      saveTimer = setTimeout(() => {
+        saveTimer = void 0;
+        savesSinceLastFlush = 0;
+        const result = snapshotOpts.save(currentState);
+        if (result instanceof Promise) result.catch(() => void 0);
+      }, saveDebounceMs);
+    }
+    const projNode = this.derived(
+      name,
+      eventNames,
+      (batchData, ctx) => {
+        const snapshots = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        const allEvents = collectAllEvents(snapshots);
+        let newState;
+        if (mode === "replay") {
+          const frozen = freezeInputs ? Object.freeze(allEvents) : allEvents;
+          newState = reducer(initial, frozen);
+        } else {
+          const newOnly = allEvents.slice(lastProcessedCount);
+          lastProcessedCount = allEvents.length;
+          const frozenNew = freezeInputs ? Object.freeze(newOnly) : newOnly;
+          newState = reducer(scanState, frozenNew);
+          scanState = newState;
+        }
+        scheduleSave(newState);
+        return [newState];
+      },
+      {
+        meta: cqrsMeta("projection", { projection_name: name, source_events: eventNames }),
+        guard: PROJECTION_GUARD,
+        initial: seedState
+      }
+    );
+    this.addDisposer((0, import_extra4.keepalive)(projNode));
+    this.addDisposer(() => {
+      if (saveTimer !== void 0) {
+        clearTimeout(saveTimer);
+        saveTimer = void 0;
+      }
+    });
+    this._projections.add(name);
+    const rebuild = async (rebuildOpts) => {
+      try {
+        const pageSize = rebuildOpts?.pageSize ?? 1e3;
+        const tier = rebuildOpts?.fromTier ?? this._attachedEventTiers[0]?.[0];
+        const preBuildCount = collectAllEvents(
+          eventNodes.map((n) => n.cache ?? [])
+        ).length;
+        let rebuildState = initial;
+        if (snapshotOpts?.load) {
+          const loaded = await snapshotOpts.load();
+          if (loaded !== void 0) rebuildState = loaded;
+        }
+        if (!tier || !tier.loadEntries) {
+          const inMemory = collectAllEvents(
+            eventNodes.map((n) => n.cache ?? [])
+          );
+          const frozen = freezeInputs ? Object.freeze(inMemory) : inMemory;
+          rebuildState = reducer(rebuildState, frozen);
+        } else {
+          const watchedEvents = new Set(eventNames);
+          let cursor;
+          let done = false;
+          while (!done) {
+            const result = await tier.loadEntries({ cursor, pageSize });
+            const page = [...result.entries].filter((e) => watchedEvents.has(e.type));
+            sortEvents(page);
+            const frozenPage = freezeInputs ? Object.freeze(page) : page;
+            rebuildState = reducer(rebuildState, frozenPage);
+            cursor = result.cursor;
+            done = !cursor || result.entries.length === 0;
+          }
+        }
+        if (mode === "scan") {
+          const allInMemory = collectAllEvents(
+            eventNodes.map((n) => n.cache ?? [])
+          );
+          const pendingEvents = allInMemory.slice(preBuildCount);
+          if (pendingEvents.length > 0) {
+            const frozenPending = freezeInputs ? Object.freeze(pendingEvents) : pendingEvents;
+            rebuildState = reducer(rebuildState, frozenPending);
+          }
+          scanState = rebuildState;
+          lastProcessedCount = allInMemory.length;
+        }
+        projNode.emit(rebuildState, { internal: true });
+        return rebuildState;
+      } catch (err) {
+        throw new RebuildError(name, err);
+      }
+    };
+    const reset = async () => {
+      try {
+        let baseState = initial;
+        if (snapshotOpts?.load) {
+          const loaded = await snapshotOpts.load();
+          if (loaded !== void 0) baseState = loaded;
+        }
+        const inMemory = collectAllEvents(
+          eventNodes.map((n) => n.cache ?? [])
+        );
+        const frozen = freezeInputs ? Object.freeze(inMemory) : inMemory;
+        const newState = reducer(baseState, frozen);
+        if (mode === "scan") {
+          scanState = newState;
+          lastProcessedCount = inMemory.length;
+        }
+        projNode.emit(newState, { internal: true });
+        return newState;
+      } catch (err) {
+        throw new RebuildError(name, err);
+      }
+    };
+    return { node: projNode, rebuild, reset };
+  }
+  // -- 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, opts = {}) {
+    const _eventNodes = eventNames.map((eName) => {
+      if (!this._eventLogs.has(eName)) this.event(eName);
+      return this._eventLogs.get(eName).node;
+    });
+    const cursors = registerCursorMap(this, `${name}_cursor`, eventNames, 0);
+    const invocations = createAuditLog({
+      name: `${name}_invocations`,
+      retainedLimit: this._retainedLimit,
+      graph: this
+    });
+    const aggregateFilter = opts.aggregateId;
+    const errorPolicy = opts.errorPolicy ?? "advance";
+    const latestCursors = /* @__PURE__ */ new Map();
+    for (const eName of eventNames) {
+      const cursor = cursors[eName];
+      latestCursors.set(eName, cursor.cache ?? 0);
+      const sub = cursor.subscribe((msgs) => {
+        for (const m of msgs) if (m[0] === import_core8.DATA) latestCursors.set(eName, m[1]);
+      });
+      this.addDisposer(sub);
+    }
+    const auditedHandler = mutate(
+      (ev, _eName) => {
+        handler(ev);
+      },
+      {
+        frame: "inline",
+        log: invocations,
+        freeze: false,
+        ...opts.handlerVersion !== void 0 ? { handlerVersion: opts.handlerVersion } : {},
+        // D5 (qa lock): always include the `aggregateId` key (even when
+        // undefined) for parity with the pre-Tier-8 saga record shape.
+        // Consumers using `Object.hasOwn(record, "aggregateId")` or JSON
+        // serialization shape would observe a pre-1.0 break otherwise.
+        onSuccessRecord: ([ev, eName], _r, { t_ns }) => ({
+          eventType: eName,
+          outcome: "success",
+          aggregateId: ev.aggregateId,
+          event: ev,
+          t_ns
+        }),
+        onFailureRecord: ([ev, eName], err, { t_ns, errorType }) => ({
+          eventType: eName,
+          outcome: "failure",
+          error: err,
+          errorType,
+          aggregateId: ev.aggregateId,
+          event: ev,
+          t_ns
+        })
+      }
+    );
+    const sagaRef = {};
+    const sagaNode = this.effect(
+      name,
+      eventNames,
+      (snapshots, _up) => {
+        const errNode = sagaRef.n.meta.error;
+        for (let i = 0; i < snapshots.length; i++) {
+          const batch2 = snapshots[i];
+          if (batch2 == null || batch2.length === 0) continue;
+          const entries = batch2.at(-1);
+          if (!entries) continue;
+          const eName = eventNames[i];
+          const cursor = cursors[eName];
+          const lastCount = latestCursors.get(eName) ?? 0;
+          if (entries.length > lastCount) {
+            const newEntries = entries.slice(lastCount);
+            let advancedTo = lastCount;
+            for (const entry of newEntries) {
+              const ev = entry;
+              if (aggregateFilter !== void 0 && ev.aggregateId !== aggregateFilter) {
+                advancedTo += 1;
+                continue;
+              }
+              try {
+                auditedHandler(ev, eName);
+                errNode.emit(null, { internal: true });
+                advancedTo += 1;
+              } catch (err) {
+                errNode.emit(err, { internal: true });
+                if (errorPolicy === "hold") break;
+                advancedTo += 1;
+              }
+            }
+            cursor.emit(advancedTo);
+          }
+        }
+      },
+      {
+        meta: {
+          ...cqrsMeta("saga", { saga_name: name, source_events: eventNames }),
+          error: null
+        }
+      }
+    );
+    sagaRef.n = sagaNode;
+    this.addDisposer((0, import_extra4.keepalive)(sagaNode));
+    this._sagas.add(name);
+    return {
+      node: sagaNode,
+      invocations,
+      audit: invocations,
+      cursors
+    };
+  }
+};
+function cqrs(name, opts) {
+  const g = new CqrsGraph(name, opts);
+  const { factory: _f, factoryArgs: _fa, ...tagArgs } = opts ?? {};
+  g.tagFactory("cqrs", (0, import_core8.placeholderArgs)(tagArgs));
+  return g;
+}
+
+// src/compat/nestjs/module.ts
+var GraphReflyRootLifecycle = class {
+  constructor(graph) {
+    this.graph = graph;
+  }
+  onModuleDestroy() {
+    this.graph.destroy();
+  }
+};
+var GraphReflyRequestLifecycle = class {
+  graph = new import_graph3.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 import_graph3.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_core9.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 import_graph3.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({ name: "orderCount", events: ["orderPlaced"], reducer: (_s, evts) => evts.length, initial: 0 });
+   *   },
+   * })
+   * ```
+   */
+  static forCqrs(opts) {
+    const providers = [
+      {
+        provide: getGraphToken(opts.name),
+        useFactory: (rootGraph) => {
+          const g = cqrs(opts.name, opts.cqrs);
+          if (opts.eventStorage) g.attachEventStorage(opts.eventStorage);
+          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;
 //# sourceMappingURL=index.cjs.map