@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/chunk-NY2PYHNC.js

@@ -0,0 +1,873 @@
+import {
+  domainMeta
+} from "./chunk-FMPF42Q4.js";
+import {
+  createAuditLog,
+  mutate,
+  registerCursor,
+  registerCursorMap
+} from "./chunk-BXGZFGZ4.js";
+
+// src/utils/cqrs/index.ts
+import {
+  DATA,
+  node,
+  placeholderArgs,
+  policy,
+  wallClockNs
+} from "@graphrefly/pure-ts/core";
+import { reactiveLog } from "@graphrefly/pure-ts/extra";
+import { Graph } from "@graphrefly/pure-ts/graph";
+
+// 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 TeardownError = class extends GraphReFlyError {
+  constructor(kind, method) {
+    super(`${kind}: ${method}() called after teardown`);
+    this.kind = kind;
+    this.method = method;
+  }
+};
+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
+import { keepalive } from "@graphrefly/pure-ts/extra";
+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 domainMeta("cqrs", kind, extra);
+}
+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);
+}
+var cqrsEventKeyOf = (e) => `${e.type}::${e.aggregateId ?? "__default__"}`;
+var dispatchKeyOf = (r) => r.commandName;
+var sagaInvocationKeyOf = (i) => i.eventType;
+var CqrsGraph = class extends 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: 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 = 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(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 = 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 = 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(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 ? deepFreeze(payload) : payload;
+    const evt = {
+      type: eventName,
+      payload: frozenPayload,
+      timestampNs: 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(
+          (batch, i) => batch != null && batch.length > 0 ? batch.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(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] === 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 batch = snapshots[i];
+          if (batch == null || batch.length === 0) continue;
+          const entries = batch.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(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", placeholderArgs(tagArgs));
+  return g;
+}
+
+export {
+  GraphReFlyError,
+  DuplicateRegistrationError,
+  UndeclaredEmitError,
+  OptimisticConcurrencyError,
+  UnknownCommandError,
+  CommandHandlerError,
+  TeardownError,
+  RebuildError,
+  cqrsEventKeyOf,
+  dispatchKeyOf,
+  sagaInvocationKeyOf,
+  CqrsGraph,
+  cqrs
+};
+//# sourceMappingURL=chunk-NY2PYHNC.js.map