@graphrefly/graphrefly 0.22.0 → 0.23.0

package/dist/chunk-JFONSPNF.js

@@ -0,0 +1,391 @@
+import {
+  COMPLETE,
+  DATA,
+  DIRTY,
+  ERROR,
+  PAUSE,
+  RESUME,
+  batch,
+  derived,
+  state
+} from "./chunk-NZMBRXQV.js";
+
+// src/extra/observable.ts
+import { Observable } from "rxjs";
+function toObservable(node, options) {
+  if (options?.raw) {
+    return new Observable((subscriber) => {
+      const unsub = node.subscribe((msgs) => {
+        if (subscriber.closed) return;
+        subscriber.next(msgs);
+        for (const m of msgs) {
+          if (m[0] === ERROR) {
+            subscriber.error(m[1]);
+            return;
+          }
+          if (m[0] === COMPLETE) {
+            subscriber.complete();
+            return;
+          }
+        }
+      });
+      return unsub;
+    });
+  }
+  return new Observable((subscriber) => {
+    const unsub = node.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (subscriber.closed) return;
+        if (m[0] === DATA) {
+          subscriber.next(m[1]);
+        } else if (m[0] === ERROR) {
+          subscriber.error(m[1]);
+          return;
+        } else if (m[0] === COMPLETE) {
+          subscriber.complete();
+          return;
+        }
+      }
+    });
+    return unsub;
+  });
+}
+
+// src/extra/backpressure.ts
+var nextLockId = 0;
+function createWatermarkController(sendUp, opts) {
+  if (opts.highWaterMark < 1) throw new RangeError("highWaterMark must be >= 1");
+  if (opts.lowWaterMark < 0) throw new RangeError("lowWaterMark must be >= 0");
+  if (opts.lowWaterMark >= opts.highWaterMark)
+    throw new RangeError("lowWaterMark must be < highWaterMark");
+  const lockId = /* @__PURE__ */ Symbol(`bp-${++nextLockId}`);
+  let pending = 0;
+  let paused = false;
+  return {
+    onEnqueue() {
+      pending += 1;
+      if (!paused && pending >= opts.highWaterMark) {
+        paused = true;
+        sendUp([[PAUSE, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    onDequeue() {
+      if (pending > 0) pending -= 1;
+      if (paused && pending <= opts.lowWaterMark) {
+        paused = false;
+        sendUp([[RESUME, lockId]]);
+        return true;
+      }
+      return false;
+    },
+    get pending() {
+      return pending;
+    },
+    get paused() {
+      return paused;
+    },
+    dispose() {
+      if (paused) {
+        paused = false;
+        sendUp([[RESUME, lockId]]);
+      }
+    }
+  };
+}
+
+// src/extra/reactive-log.ts
+var NativeLogBackend = class {
+  _version = 0;
+  _maxSize;
+  _buf;
+  _head = 0;
+  _size = 0;
+  constructor(initial, maxSize) {
+    if (maxSize !== void 0 && maxSize < 1) {
+      throw new RangeError("maxSize must be >= 1");
+    }
+    this._maxSize = maxSize;
+    if (maxSize !== void 0) {
+      this._buf = new Array(maxSize);
+      if (initial && initial.length > 0) {
+        const take = Math.min(initial.length, maxSize);
+        const start = initial.length - take;
+        for (let i = 0; i < take; i++) {
+          this._buf[i] = initial[start + i];
+        }
+        this._size = take;
+      }
+    } else {
+      this._buf = initial ? [...initial] : [];
+      this._size = this._buf.length;
+    }
+  }
+  get version() {
+    return this._version;
+  }
+  get size() {
+    return this._size;
+  }
+  at(index) {
+    if (!Number.isInteger(index)) return void 0;
+    const i = index >= 0 ? index : this._size + index;
+    if (i < 0 || i >= this._size) return void 0;
+    if (this._maxSize !== void 0) {
+      return this._buf[(this._head + i) % this._maxSize];
+    }
+    return this._buf[i];
+  }
+  append(value) {
+    this._rawAppend(value);
+    this._version += 1;
+  }
+  appendMany(values) {
+    if (values.length === 0) return;
+    const start = this._maxSize !== void 0 && values.length > this._maxSize ? values.length - this._maxSize : 0;
+    for (let i = start; i < values.length; i++) {
+      this._rawAppend(values[i]);
+    }
+    this._version += 1;
+  }
+  clear() {
+    if (this._size === 0) return 0;
+    const n = this._size;
+    if (this._maxSize === void 0) {
+      this._buf.length = 0;
+    } else {
+      for (let i = 0; i < n; i++) {
+        this._buf[(this._head + i) % this._maxSize] = void 0;
+      }
+    }
+    this._head = 0;
+    this._size = 0;
+    this._version += 1;
+    return n;
+  }
+  trimHead(n) {
+    if (!Number.isInteger(n) || n < 0) {
+      throw new RangeError(`trimHead: n must be a non-negative integer (got ${n})`);
+    }
+    if (n === 0 || this._size === 0) return 0;
+    const removed = Math.min(n, this._size);
+    if (this._maxSize === void 0) {
+      this._buf.splice(0, removed);
+    } else {
+      for (let i = 0; i < removed; i++) {
+        this._buf[(this._head + i) % this._maxSize] = void 0;
+      }
+      this._head = (this._head + removed) % this._maxSize;
+    }
+    this._size -= removed;
+    this._version += 1;
+    return removed;
+  }
+  slice(start, stop) {
+    if (!Number.isInteger(start) || start < 0) {
+      throw new RangeError(`slice: start must be a non-negative integer (got ${start})`);
+    }
+    if (stop !== void 0 && (!Number.isInteger(stop) || stop < 0)) {
+      throw new RangeError(`slice: stop must be a non-negative integer or undefined (got ${stop})`);
+    }
+    const end = stop === void 0 ? this._size : Math.min(Math.max(stop, 0), this._size);
+    const s = Math.min(start, this._size);
+    if (s >= end) return [];
+    const len = end - s;
+    if (this._maxSize === void 0) {
+      return this._buf.slice(s, end);
+    }
+    const out = new Array(len);
+    for (let i = 0; i < len; i++) {
+      out[i] = this._buf[(this._head + s + i) % this._maxSize];
+    }
+    return out;
+  }
+  tail(n) {
+    if (!Number.isInteger(n) || n < 0) {
+      throw new RangeError(`tail: n must be a non-negative integer (got ${n})`);
+    }
+    if (n === 0 || this._size === 0) return [];
+    const take = Math.min(n, this._size);
+    return this.slice(this._size - take, this._size);
+  }
+  toArray() {
+    if (this._maxSize === void 0) {
+      return [...this._buf];
+    }
+    const out = new Array(this._size);
+    for (let i = 0; i < this._size; i++) {
+      out[i] = this._buf[(this._head + i) % this._maxSize];
+    }
+    return out;
+  }
+  /** Internal append without version bump — used by `appendMany`. */
+  _rawAppend(value) {
+    if (this._maxSize === void 0) {
+      this._buf.push(value);
+      this._size = this._buf.length;
+      return;
+    }
+    if (this._size < this._maxSize) {
+      this._buf[(this._head + this._size) % this._maxSize] = value;
+      this._size += 1;
+    } else {
+      this._buf[this._head] = value;
+      this._head = (this._head + 1) % this._maxSize;
+    }
+  }
+};
+function keepaliveDerived(n) {
+  return n.subscribe(() => {
+  });
+}
+var DEFAULT_VIEW_CACHE_MAX = 64;
+function reactiveLog(initial, options = {}) {
+  const { name, maxSize, versioning, backend: userBackend } = options;
+  const backend = userBackend ?? new NativeLogBackend(initial, maxSize);
+  const entries = state(backend.toArray(), {
+    name,
+    describeKind: "state",
+    equals: (a, b) => a === b,
+    ...versioning != null ? { versioning } : {}
+  });
+  function pushSnapshot() {
+    const snapshot = backend.toArray();
+    batch(() => {
+      entries.down([[DIRTY]]);
+      entries.down([[DATA, snapshot]]);
+    });
+  }
+  const tailCache = /* @__PURE__ */ new Map();
+  const sliceCache = /* @__PURE__ */ new Map();
+  function sliceKey(start, stop) {
+    return `${start}:${stop === void 0 ? "END" : stop}`;
+  }
+  function evictOldestIfFull(cache) {
+    if (cache.size < DEFAULT_VIEW_CACHE_MAX) return;
+    const first = cache.keys().next();
+    if (first.done) return;
+    const oldest = cache.get(first.value);
+    if (oldest !== void 0) oldest.dispose();
+    cache.delete(first.value);
+  }
+  function wrapMutation(op) {
+    const prev = backend.version;
+    try {
+      return op();
+    } finally {
+      if (backend.version !== prev) pushSnapshot();
+    }
+  }
+  return {
+    entries,
+    get size() {
+      return backend.size;
+    },
+    at(index) {
+      return backend.at(index);
+    },
+    append(value) {
+      wrapMutation(() => backend.append(value));
+    },
+    appendMany(values) {
+      if (values.length === 0) return;
+      wrapMutation(() => backend.appendMany(values));
+    },
+    clear() {
+      wrapMutation(() => backend.clear());
+    },
+    trimHead(n) {
+      wrapMutation(() => backend.trimHead(n));
+    },
+    tail(n) {
+      if (!Number.isInteger(n) || n < 0) {
+        throw new RangeError(`tail: n must be a non-negative integer (got ${n})`);
+      }
+      const hit = tailCache.get(n);
+      if (hit !== void 0) {
+        tailCache.delete(n);
+        tailCache.set(n, hit);
+        return hit.node;
+      }
+      evictOldestIfFull(tailCache);
+      const node_ = derived(
+        [entries],
+        ([s]) => {
+          const list = s;
+          if (n === 0 || list.length === 0) return [];
+          return list.slice(Math.max(0, list.length - n));
+        },
+        { initial: backend.tail(n), describeKind: "derived" }
+      );
+      const dispose = keepaliveDerived(node_);
+      tailCache.set(n, { node: node_, dispose });
+      return node_;
+    },
+    slice(start, stop) {
+      if (!Number.isInteger(start) || start < 0) {
+        throw new RangeError(`slice: start must be a non-negative integer (got ${start})`);
+      }
+      if (stop !== void 0 && (!Number.isInteger(stop) || stop < 0)) {
+        throw new RangeError(
+          `slice: stop must be a non-negative integer or undefined (got ${stop})`
+        );
+      }
+      const key = sliceKey(start, stop);
+      const hit = sliceCache.get(key);
+      if (hit !== void 0) {
+        sliceCache.delete(key);
+        sliceCache.set(key, hit);
+        return hit.node;
+      }
+      evictOldestIfFull(sliceCache);
+      const node_ = derived(
+        [entries],
+        ([s]) => {
+          const list = s;
+          return stop === void 0 ? list.slice(start) : list.slice(start, stop);
+        },
+        { initial: backend.slice(start, stop), describeKind: "derived" }
+      );
+      const dispose = keepaliveDerived(node_);
+      sliceCache.set(key, { node: node_, dispose });
+      return node_;
+    },
+    disposeTail(n) {
+      const hit = tailCache.get(n);
+      if (hit === void 0) return false;
+      hit.dispose();
+      tailCache.delete(n);
+      return true;
+    },
+    disposeSlice(start, stop) {
+      const key = sliceKey(start, stop);
+      const hit = sliceCache.get(key);
+      if (hit === void 0) return false;
+      hit.dispose();
+      sliceCache.delete(key);
+      return true;
+    },
+    disposeAllViews() {
+      for (const entry of tailCache.values()) entry.dispose();
+      tailCache.clear();
+      for (const entry of sliceCache.values()) entry.dispose();
+      sliceCache.clear();
+    },
+    dispose() {
+      for (const entry of tailCache.values()) entry.dispose();
+      tailCache.clear();
+      for (const entry of sliceCache.values()) entry.dispose();
+      sliceCache.clear();
+    }
+  };
+}
+
+export {
+  toObservable,
+  createWatermarkController,
+  NativeLogBackend,
+  reactiveLog
+};
+//# sourceMappingURL=chunk-JFONSPNF.js.map

package/dist/chunk-JFONSPNF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extra/observable.ts","../src/extra/backpressure.ts","../src/extra/reactive-log.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// RxJS bridge — reactive interop between GraphReFly nodes and RxJS Observables.\n// ---------------------------------------------------------------------------\n// Usage:\n//   import { toObservable } from '@graphrefly/graphrefly-ts/extra';\n//   const values$ = toObservable(myNode);                   // Observable<T>\n//   const msgs$   = toObservable(myNode, { raw: true });    // Observable<Messages>\n// ---------------------------------------------------------------------------\n\nimport { Observable } from \"rxjs\";\nimport { COMPLETE, DATA, ERROR, type Messages } from \"../core/messages.js\";\nimport type { Node } from \"../core/node.js\";\n\n/** Options for {@link toObservable}. */\nexport type ToObservableOptions = {\n\t/**\n\t * When `true`, emit raw `Messages` batches instead of extracted `DATA` values.\n\t * Terminal batches are still emitted as the final `next()` before the\n\t * Observable signal (error/complete).\n\t */\n\traw?: boolean;\n};\n\n/**\n * Bridge a `Node<T>` to an RxJS `Observable`.\n *\n * Default mode emits the node's value on each `DATA` message. Maps `ERROR` to\n * `subscriber.error()` and `COMPLETE` to `subscriber.complete()`.\n * Protocol-internal signals (DIRTY, RESOLVED, PAUSE, etc.) are skipped.\n *\n * With `{ raw: true }`, emits full `[[Type, Data?], ...]` message batches.\n * The Observable terminates on ERROR or COMPLETE (the terminal batch is still\n * emitted as the final `next()` before the Observable signal).\n *\n * For graph-level observation, use `toObservable(graph.resolve(path))` or\n * subscribe to `graph.observe()` directly.\n *\n * Unsubscribing the Observable unsubscribes the node.\n */\nexport function toObservable<T>(\n\tnode: Node<T>,\n\toptions?: ToObservableOptions & { raw?: false },\n): Observable<T>;\nexport function toObservable<T>(\n\tnode: Node<T>,\n\toptions: ToObservableOptions & { raw: true },\n): Observable<Messages>;\nexport function toObservable<T>(\n\tnode: Node<T>,\n\toptions?: ToObservableOptions,\n): Observable<T | Messages> {\n\tif (options?.raw) {\n\t\treturn new Observable<Messages>((subscriber) => {\n\t\t\tconst unsub = node.subscribe((msgs) => {\n\t\t\t\tif (subscriber.closed) return;\n\t\t\t\tsubscriber.next(msgs);\n\t\t\t\tfor (const m of msgs) {\n\t\t\t\t\tif (m[0] === ERROR) {\n\t\t\t\t\t\tsubscriber.error(m[1]);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tif (m[0] === COMPLETE) {\n\t\t\t\t\t\tsubscriber.complete();\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t\treturn unsub;\n\t\t});\n\t}\n\n\treturn new Observable<T>((subscriber) => {\n\t\tconst unsub = node.subscribe((msgs) => {\n\t\t\tfor (const m of msgs) {\n\t\t\t\tif (subscriber.closed) return;\n\t\t\t\tif (m[0] === DATA) {\n\t\t\t\t\tsubscriber.next(m[1] as T);\n\t\t\t\t} else if (m[0] === ERROR) {\n\t\t\t\t\tsubscriber.error(m[1]);\n\t\t\t\t\treturn;\n\t\t\t\t} else if (m[0] === COMPLETE) {\n\t\t\t\t\tsubscriber.complete();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t});\n\t\treturn unsub;\n\t});\n}\n","/**\n * Watermark-based backpressure controller — reactive PAUSE/RESUME flow control.\n *\n * Purely synchronous, event-driven. No timers, no polling, no Promises.\n * Each controller instance uses a unique lockId so multiple controllers\n * on the same upstream node do not collide.\n *\n * @module\n */\n\nimport { type Messages, PAUSE, RESUME } from \"../core/messages.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type WatermarkOptions = {\n\t/** Pending count at which PAUSE is sent upstream. */\n\thighWaterMark: number;\n\t/** Pending count at which RESUME is sent upstream (after being paused). */\n\tlowWaterMark: number;\n};\n\nexport type WatermarkController = {\n\t/** Call when a DATA message is buffered/enqueued. Returns `true` if PAUSE was just sent. */\n\tonEnqueue(): boolean;\n\t/** Call when a buffered item is consumed. Returns `true` if RESUME was just sent. */\n\tonDequeue(): boolean;\n\t/** Current un-consumed item count. */\n\treadonly pending: number;\n\t/** Whether upstream is currently paused by this controller. */\n\treadonly paused: boolean;\n\t/** Dispose: if paused, sends RESUME to unblock upstream. */\n\tdispose(): void;\n};\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\nlet nextLockId = 0;\n\n/**\n * Creates a watermark-based backpressure controller.\n *\n * @param sendUp - Callback that delivers messages upstream (typically `handle.up`).\n * @param opts - High/low watermark thresholds (item counts).\n * @returns A {@link WatermarkController}.\n *\n * @example\n * ```ts\n * const handle = graph.observe(\"fast-source\");\n * const wm = createWatermarkController(\n *   (msgs) => handle.up(msgs),\n *   { highWaterMark: 64, lowWaterMark: 16 },\n * );\n *\n * // In sink callback:\n * handle.subscribe((msgs) => {\n *   for (const msg of msgs) {\n *     if (msg[0] === DATA) {\n *       buffer.push(msg[1]);\n *       wm.onEnqueue();\n *     }\n *   }\n * });\n *\n * // When consumer drains:\n * const item = buffer.shift();\n * wm.onDequeue();\n * ```\n *\n * @category extra\n */\nexport function createWatermarkController(\n\tsendUp: (messages: Messages) => void,\n\topts: WatermarkOptions,\n): WatermarkController {\n\tif (opts.highWaterMark < 1) throw new RangeError(\"highWaterMark must be >= 1\");\n\tif (opts.lowWaterMark < 0) throw new RangeError(\"lowWaterMark must be >= 0\");\n\tif (opts.lowWaterMark >= opts.highWaterMark)\n\t\tthrow new RangeError(\"lowWaterMark must be < highWaterMark\");\n\tconst lockId = Symbol(`bp-${++nextLockId}`);\n\tlet pending = 0;\n\tlet paused = false;\n\n\treturn {\n\t\tonEnqueue(): boolean {\n\t\t\tpending += 1;\n\t\t\tif (!paused && pending >= opts.highWaterMark) {\n\t\t\t\tpaused = true;\n\t\t\t\tsendUp([[PAUSE, lockId]]);\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\treturn false;\n\t\t},\n\t\tonDequeue(): boolean {\n\t\t\tif (pending > 0) pending -= 1;\n\t\t\tif (paused && pending <= opts.lowWaterMark) {\n\t\t\t\tpaused = false;\n\t\t\t\tsendUp([[RESUME, lockId]]);\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\treturn false;\n\t\t},\n\t\tget pending() {\n\t\t\treturn pending;\n\t\t},\n\t\tget paused() {\n\t\t\treturn paused;\n\t\t},\n\t\tdispose() {\n\t\t\tif (paused) {\n\t\t\t\tpaused = false;\n\t\t\t\tsendUp([[RESUME, lockId]]);\n\t\t\t}\n\t\t},\n\t};\n}\n","/**\n * Reactive append-only log (roadmap §3.2) — emits `readonly T[]` snapshots directly.\n *\n * Internal version counter drives efficient equality without leaking `Versioned`\n * into the public API (spec §5.12).\n *\n * **Wave 4 refactor (2026-04-15):** Introduces the `LogBackend<T>` pluggable-backend\n * interface. The default `NativeLogBackend` uses a ring buffer when `maxSize` is set\n * (O(1) append + trim) and a flat array otherwise. `tail(n)` and `slice(start, stop)`\n * are memoized — repeat calls with identical arguments return the same derived node,\n * bounding the keepalive-subscription footprint. The standalone `logSlice` factory\n * has been removed; use `log.slice(start, stop)` instead.\n */\nimport { batch } from \"../core/batch.js\";\nimport { DATA, DIRTY } from \"../core/messages.js\";\nimport type { Node } from \"../core/node.js\";\nimport { derived, state } from \"../core/sugar.js\";\nimport type { VersioningLevel } from \"../core/versioning.js\";\n\nexport type ReactiveLogOptions<T> = {\n\tname?: string;\n\tmaxSize?: number;\n\t/**\n\t * Optional versioning level for the underlying `entries` state node. Set\n\t * at construction time; cannot be changed later. Pass `0` for V0 identity\n\t * + monotonic version counter, or `1` for V1 + content-addressed cid.\n\t */\n\tversioning?: VersioningLevel;\n\t/**\n\t * Storage backend. Defaults to `NativeLogBackend` (ring buffer if `maxSize` is set,\n\t * flat array otherwise). Users can plug in persistent / RRB-tree backends via\n\t * the {@link LogBackend} interface.\n\t */\n\tbackend?: LogBackend<T>;\n};\n\nexport type ReactiveLogBundle<T> = {\n\t/** Emits `readonly T[]` on each append/clear/trim (two-phase). */\n\treadonly entries: Node<readonly T[]>;\n\t/** Current entry count (O(1)). */\n\treadonly size: number;\n\t/** Positional access (O(1)); returns `undefined` on out-of-range. Supports negative indices (Python-style). */\n\tat: (index: number) => T | undefined;\n\tappend: (value: T) => void;\n\t/**\n\t * Push all values, emit one snapshot. No-op if `values` is empty.\n\t * **Iterable consumption:** `values` is a `readonly T[]` — safe to pass arrays.\n\t */\n\tappendMany: (values: readonly T[]) => void;\n\tclear: () => void;\n\t/** Remove the first `n` entries (clamped to `size`). Throws on non-integer or negative `n`. */\n\ttrimHead: (n: number) => void;\n\t/**\n\t * Last `n` entries (or fewer) as a derived reactive view. Memoized with\n\t * an LRU cache (default cap 64) — repeat calls with the same `n` return\n\t * the same node. Throws on non-integer or negative `n`.\n\t *\n\t * **LRU eviction contract (D3(b)):** when a 65th distinct `n` is passed,\n\t * the least-recently-used cached view is evicted and its keepalive is\n\t * disposed. External holders of the evicted node will NOT receive further\n\t * updates — re-call `tail(n)` for a fresh node, or dispose proactively\n\t * via {@link disposeTail} / {@link disposeAllViews}. To avoid surprise:\n\t * resolve `tail(n)` at the point of use rather than caching the returned\n\t * node across many distinct `n`s.\n\t */\n\ttail: (n: number) => Node<readonly T[]>;\n\t/**\n\t * Reactive view of `entries.slice(start, stop)` — non-negative integer\n\t * `start`, non-negative integer `stop` (exclusive) or `undefined` (to end).\n\t * Memoized with an LRU cache (default cap 64) — repeat calls with the\n\t * same `(start, stop)` return the same node.\n\t *\n\t * Throws on non-integer `start`, negative `start`, non-integer `stop`, or\n\t * negative `stop` (P4 — the backend cannot cheaply honor JS-style\n\t * negative `stop` without scanning length; disallowed for a consistent\n\t * contract between backend, derived recomputation, and cached initial).\n\t *\n\t * **LRU eviction contract (D3(b)):** same as {@link tail} — past 64\n\t * distinct `(start, stop)` pairs, the oldest cached view is evicted and\n\t * its keepalive disposed. External holders stop receiving updates.\n\t */\n\tslice: (start: number, stop?: number) => Node<readonly T[]>;\n\t/**\n\t * Releases the cached `tail(n)` view if present (disposes its keepalive\n\t * subscription). Subsequent `tail(n)` calls create a fresh node. No-op if\n\t * `n` was not cached. Returns `true` if a view was disposed.\n\t */\n\tdisposeTail: (n: number) => boolean;\n\t/**\n\t * Releases the cached `slice(start, stop?)` view if present. No-op if not cached.\n\t */\n\tdisposeSlice: (start: number, stop?: number) => boolean;\n\t/** Releases all cached tail/slice views and their keepalive subscriptions. */\n\tdisposeAllViews: () => void;\n\t/**\n\t * Releases all internal keepalive subscriptions so the bundle can be\n\t * GC'd — currently equivalent to {@link disposeAllViews}, but exposed as\n\t * a uniform API across all reactive data structures for lifecycle\n\t * symmetry (mirrors `reactiveMap.dispose` / `reactiveList.dispose` /\n\t * `reactiveIndex.dispose`). Idempotent. D6(a).\n\t */\n\tdispose: () => void;\n};\n\n// ── Backend interface ─────────────────────────────────────────────────────\n\n/**\n * Storage contract for {@link reactiveLog}. Implementations own the mutable state and\n * expose a monotonic `version` counter that increments on every structural change.\n *\n * The reactive layer reads `version` to decide when to emit; it does not inspect\n * internal representation. Users can plug in persistent / ring-buffer / skip-list\n * backends without touching the reactive emission logic.\n *\n * @remarks Post-1.0 op-log changesets will extend this interface with a\n * `changesSince(version: number): Iterable<Change>` method. Current consumers\n * should treat all methods here as stable.\n *\n * @category extra\n */\nexport interface LogBackend<T> {\n\t/** Monotonic mutation counter; increments on every append/trim/clear that changes state. */\n\treadonly version: number;\n\t/** Number of entries currently stored. */\n\treadonly size: number;\n\t/** O(1) positional access; returns `undefined` on out-of-range. */\n\tat(index: number): T | undefined;\n\t/** Append a value. Applies `maxSize` head-drop if configured. Advances `version`. */\n\tappend(value: T): void;\n\t/** Append a batch; advances `version` once. No-op if `values.length === 0`. */\n\tappendMany(values: readonly T[]): void;\n\t/** Remove all entries. Returns count removed. Advances `version` only if non-zero. */\n\tclear(): number;\n\t/** Remove the first `n` entries (clamped). Returns count removed. Throws on negative `n`. */\n\ttrimHead(n: number): number;\n\t/** Fresh snapshot array for `[start, stop)`. Throws on negative `start`. */\n\tslice(start: number, stop?: number): readonly T[];\n\t/** Last `n` entries as a fresh array. Throws on negative `n`. */\n\ttail(n: number): readonly T[];\n\t/** Full snapshot as a fresh array. */\n\ttoArray(): readonly T[];\n}\n\n/**\n * Default append-only log backend.\n *\n * - When `maxSize` is set: uses a **ring buffer** with `_head` index and circular\n *   modular arithmetic. Append and trim become O(1); snapshot is O(size) unrolling.\n * - When `maxSize` is unset: uses a flat array with standard push/splice.\n *\n * `appendMany` pre-trims oversize input: if `values.length > maxSize`, only the\n * tail of `values` is pushed (the rest would be immediately evicted).\n *\n * @category extra\n */\nexport class NativeLogBackend<T> implements LogBackend<T> {\n\tprivate _version = 0;\n\tprivate readonly _maxSize?: number;\n\tprivate readonly _buf: T[];\n\tprivate _head = 0;\n\tprivate _size = 0;\n\n\tconstructor(initial?: readonly T[], maxSize?: number) {\n\t\tif (maxSize !== undefined && maxSize < 1) {\n\t\t\tthrow new RangeError(\"maxSize must be >= 1\");\n\t\t}\n\t\tthis._maxSize = maxSize;\n\t\tif (maxSize !== undefined) {\n\t\t\t// Ring buffer mode — pre-allocate fixed size\n\t\t\tthis._buf = new Array(maxSize);\n\t\t\tif (initial && initial.length > 0) {\n\t\t\t\tconst take = Math.min(initial.length, maxSize);\n\t\t\t\tconst start = initial.length - take;\n\t\t\t\tfor (let i = 0; i < take; i++) {\n\t\t\t\t\tthis._buf[i] = initial[start + i]!;\n\t\t\t\t}\n\t\t\t\tthis._size = take;\n\t\t\t}\n\t\t} else {\n\t\t\t// Unbounded mode — dynamic array\n\t\t\tthis._buf = initial ? [...initial] : [];\n\t\t\tthis._size = this._buf.length;\n\t\t}\n\t}\n\n\tget version(): number {\n\t\treturn this._version;\n\t}\n\n\tget size(): number {\n\t\treturn this._size;\n\t}\n\n\tat(index: number): T | undefined {\n\t\tif (!Number.isInteger(index)) return undefined;\n\t\t// P5: Python-style negative index — `-1` returns the last entry.\n\t\tconst i = index >= 0 ? index : this._size + index;\n\t\tif (i < 0 || i >= this._size) return undefined;\n\t\tif (this._maxSize !== undefined) {\n\t\t\treturn this._buf[(this._head + i) % this._maxSize];\n\t\t}\n\t\treturn this._buf[i];\n\t}\n\n\tappend(value: T): void {\n\t\tthis._rawAppend(value);\n\t\tthis._version += 1;\n\t}\n\n\tappendMany(values: readonly T[]): void {\n\t\tif (values.length === 0) return;\n\t\t// Pre-trim oversize input in ring mode — skip values that would be\n\t\t// immediately evicted. Iterate with a start index instead of\n\t\t// allocating an intermediate slice. F2.\n\t\tconst start =\n\t\t\tthis._maxSize !== undefined && values.length > this._maxSize\n\t\t\t\t? values.length - this._maxSize\n\t\t\t\t: 0;\n\t\tfor (let i = start; i < values.length; i++) {\n\t\t\tthis._rawAppend(values[i] as T);\n\t\t}\n\t\tthis._version += 1;\n\t}\n\n\tclear(): number {\n\t\tif (this._size === 0) return 0;\n\t\tconst n = this._size;\n\t\tif (this._maxSize === undefined) {\n\t\t\tthis._buf.length = 0;\n\t\t} else {\n\t\t\t// Ring buffer: only null the currently-live window so the GC can\n\t\t\t// reclaim ref-typed `T`. Iterating the full capacity would be O(cap)\n\t\t\t// even when only a few slots are in use (P6). Non-live slots are\n\t\t\t// already `undefined` (pre-allocation state) or whatever a prior\n\t\t\t// trim/clear left — they hold no live refs.\n\t\t\tfor (let i = 0; i < n; i++) {\n\t\t\t\tthis._buf[(this._head + i) % this._maxSize] = undefined as unknown as T;\n\t\t\t}\n\t\t}\n\t\tthis._head = 0;\n\t\tthis._size = 0;\n\t\tthis._version += 1;\n\t\treturn n;\n\t}\n\n\ttrimHead(n: number): number {\n\t\tif (!Number.isInteger(n) || n < 0) {\n\t\t\tthrow new RangeError(`trimHead: n must be a non-negative integer (got ${n})`);\n\t\t}\n\t\tif (n === 0 || this._size === 0) return 0;\n\t\tconst removed = Math.min(n, this._size);\n\t\tif (this._maxSize === undefined) {\n\t\t\tthis._buf.splice(0, removed);\n\t\t} else {\n\t\t\t// Null trimmed slots so the GC can reclaim ref-typed T (P4 extension).\n\t\t\tfor (let i = 0; i < removed; i++) {\n\t\t\t\tthis._buf[(this._head + i) % this._maxSize] = undefined as unknown as T;\n\t\t\t}\n\t\t\tthis._head = (this._head + removed) % this._maxSize;\n\t\t}\n\t\tthis._size -= removed;\n\t\tthis._version += 1;\n\t\treturn removed;\n\t}\n\n\tslice(start: number, stop?: number): readonly T[] {\n\t\tif (!Number.isInteger(start) || start < 0) {\n\t\t\tthrow new RangeError(`slice: start must be a non-negative integer (got ${start})`);\n\t\t}\n\t\t// P4: reject negative `stop` explicitly so the bundle / backend / derived\n\t\t// contract stays consistent. Previously stop was silently clamped to 0,\n\t\t// producing `[]` in the backend but a different value under JS semantics\n\t\t// in the derived recomputation — a latent bug for negative inputs.\n\t\tif (stop !== undefined && (!Number.isInteger(stop) || stop < 0)) {\n\t\t\tthrow new RangeError(`slice: stop must be a non-negative integer or undefined (got ${stop})`);\n\t\t}\n\t\tconst end = stop === undefined ? this._size : Math.min(Math.max(stop, 0), this._size);\n\t\tconst s = Math.min(start, this._size);\n\t\tif (s >= end) return [];\n\t\tconst len = end - s;\n\t\tif (this._maxSize === undefined) {\n\t\t\treturn this._buf.slice(s, end);\n\t\t}\n\t\tconst out: T[] = new Array(len);\n\t\tfor (let i = 0; i < len; i++) {\n\t\t\tout[i] = this._buf[(this._head + s + i) % this._maxSize]!;\n\t\t}\n\t\treturn out;\n\t}\n\n\ttail(n: number): readonly T[] {\n\t\tif (!Number.isInteger(n) || n < 0) {\n\t\t\tthrow new RangeError(`tail: n must be a non-negative integer (got ${n})`);\n\t\t}\n\t\tif (n === 0 || this._size === 0) return [];\n\t\tconst take = Math.min(n, this._size);\n\t\treturn this.slice(this._size - take, this._size);\n\t}\n\n\ttoArray(): readonly T[] {\n\t\tif (this._maxSize === undefined) {\n\t\t\treturn [...this._buf];\n\t\t}\n\t\tconst out: T[] = new Array(this._size);\n\t\tfor (let i = 0; i < this._size; i++) {\n\t\t\tout[i] = this._buf[(this._head + i) % this._maxSize]!;\n\t\t}\n\t\treturn out;\n\t}\n\n\t/** Internal append without version bump — used by `appendMany`. */\n\tprivate _rawAppend(value: T): void {\n\t\tif (this._maxSize === undefined) {\n\t\t\tthis._buf.push(value);\n\t\t\tthis._size = this._buf.length;\n\t\t\treturn;\n\t\t}\n\t\tif (this._size < this._maxSize) {\n\t\t\tthis._buf[(this._head + this._size) % this._maxSize] = value;\n\t\t\tthis._size += 1;\n\t\t} else {\n\t\t\t// Overwrite slot at head, advance head.\n\t\t\tthis._buf[this._head] = value;\n\t\t\tthis._head = (this._head + 1) % this._maxSize;\n\t\t}\n\t}\n}\n\n// ── Reactive wrapper ──────────────────────────────────────────────────────\n\n/** Installs a keepalive subscription; returns the disposer so callers can release it. */\nfunction keepaliveDerived(n: Node<unknown>): () => void {\n\treturn n.subscribe(() => {});\n}\n\n/** Default cap on the LRU view cache for `tail(n)` / `slice(start, stop?)`. D2(c). */\nconst DEFAULT_VIEW_CACHE_MAX = 64;\n\n/**\n * Creates an append-only reactive log with immutable array snapshots.\n *\n * @param initial - Optional seed entries (copied; pre-trimmed to `maxSize` if set).\n * @param options - `name`, `maxSize`, and optional pluggable `backend`.\n * @returns Bundle with `entries` (state node), `append`/`appendMany`/`clear`/`trimHead`,\n *   `size` / `at`, and memoized derived views `tail(n)` / `slice(start, stop?)`.\n *\n * @remarks\n * **Backend:** The default {@link NativeLogBackend} uses a ring buffer when `maxSize`\n * is set (O(1) append + trim) and a flat array otherwise. For persistent/structural-\n * sharing semantics plug in a custom {@link LogBackend}.\n *\n * **`initial` + custom `backend` (F5):** When you supply `options.backend`, the\n * `initial` argument is IGNORED — seed the backend yourself before passing it in.\n * The `initial` seed only applies to the default `NativeLogBackend`.\n *\n * **Memoized views:** {@link ReactiveLogBundle.tail} and {@link ReactiveLogBundle.slice}\n * cache derived nodes per-argument. Repeat calls with the same `n` / `(start, stop)`\n * return the same node, bounding keepalive-subscription count to one per unique argument.\n *\n * @example\n * ```ts\n * import { reactiveLog } from \"@graphrefly/graphrefly-ts\";\n *\n * const lg = reactiveLog<number>([1, 2], { name: \"audit\", maxSize: 100 });\n * lg.append(3);\n * lg.entries.subscribe((msgs) => console.log(msgs));\n * const last5 = lg.tail(5);          // derived node\n * const window = lg.slice(10, 20);   // derived node\n * ```\n *\n * @category extra\n */\nexport function reactiveLog<T>(\n\tinitial?: readonly T[],\n\toptions: ReactiveLogOptions<T> = {},\n): ReactiveLogBundle<T> {\n\tconst { name, maxSize, versioning, backend: userBackend } = options;\n\tconst backend: LogBackend<T> = userBackend ?? new NativeLogBackend<T>(initial, maxSize);\n\n\tconst entries = state<readonly T[]>(backend.toArray(), {\n\t\tname,\n\t\tdescribeKind: \"state\",\n\t\tequals: (a, b) => a === b,\n\t\t...(versioning != null ? { versioning } : {}),\n\t});\n\n\tfunction pushSnapshot(): void {\n\t\tconst snapshot = backend.toArray();\n\t\tbatch(() => {\n\t\t\tentries.down([[DIRTY]]);\n\t\t\tentries.down([[DATA, snapshot]]);\n\t\t});\n\t}\n\n\t// Memoization caches for derived views (D2(c)). Each cache is an LRU keyed by\n\t// the unique view argument, bounded by `DEFAULT_VIEW_CACHE_MAX`. On cache miss\n\t// past the cap, the least-recently-used entry is evicted and its keepalive\n\t// disposer is called so the underlying derived node can be GC'd. Callers can\n\t// also release views proactively via `disposeTail` / `disposeSlice` /\n\t// `disposeAllViews`. Iteration order of `Map` is insertion order, so moving\n\t// an entry to the end on hit is the LRU \"touch\".\n\ttype ViewEntry = { node: Node<readonly T[]>; dispose: () => void };\n\tconst tailCache = new Map<number, ViewEntry>();\n\tconst sliceCache = new Map<string, ViewEntry>();\n\n\tfunction sliceKey(start: number, stop?: number): string {\n\t\treturn `${start}:${stop === undefined ? \"END\" : stop}`;\n\t}\n\n\tfunction evictOldestIfFull<K>(cache: Map<K, ViewEntry>): void {\n\t\tif (cache.size < DEFAULT_VIEW_CACHE_MAX) return;\n\t\tconst first = cache.keys().next();\n\t\tif (first.done) return;\n\t\tconst oldest = cache.get(first.value);\n\t\tif (oldest !== undefined) oldest.dispose();\n\t\tcache.delete(first.value);\n\t}\n\n\t/**\n\t * D4(a): try/finally defense-in-depth — if a custom backend op throws\n\t * mid-mutation, surface the partial state via pushSnapshot so subscribers\n\t * don't see a stale cache. Matches the pattern in reactive-map and\n\t * reactive-index. Native ops are atomic by contract; this only matters\n\t * for user-supplied backends.\n\t */\n\tfunction wrapMutation<R>(op: () => R): R {\n\t\tconst prev = backend.version;\n\t\ttry {\n\t\t\treturn op();\n\t\t} finally {\n\t\t\tif (backend.version !== prev) pushSnapshot();\n\t\t}\n\t}\n\n\treturn {\n\t\tentries,\n\n\t\tget size(): number {\n\t\t\treturn backend.size;\n\t\t},\n\n\t\tat(index: number): T | undefined {\n\t\t\treturn backend.at(index);\n\t\t},\n\n\t\tappend(value: T): void {\n\t\t\twrapMutation(() => backend.append(value));\n\t\t},\n\n\t\tappendMany(values: readonly T[]): void {\n\t\t\tif (values.length === 0) return;\n\t\t\twrapMutation(() => backend.appendMany(values));\n\t\t},\n\n\t\tclear(): void {\n\t\t\twrapMutation(() => backend.clear());\n\t\t\t// NOTE: cached tail/slice derived views are intentionally NOT\n\t\t\t// disposed here. Disposing would kill the keepalive on any node\n\t\t\t// a caller already holds externally, silently stopping their\n\t\t\t// updates. The derived nodes recompute from the new empty\n\t\t\t// snapshot when `entries` emits post-clear, so `.cache` on an\n\t\t\t// outstanding view settles to `[]` without any manual\n\t\t\t// reset. (Initial snapshots, if inspected before the next wave,\n\t\t\t// may be stale — callers who care can `disposeTail` / `slice`\n\t\t\t// explicitly.)\n\t\t},\n\n\t\ttrimHead(n: number): void {\n\t\t\twrapMutation(() => backend.trimHead(n));\n\t\t},\n\n\t\ttail(n: number): Node<readonly T[]> {\n\t\t\tif (!Number.isInteger(n) || n < 0) {\n\t\t\t\tthrow new RangeError(`tail: n must be a non-negative integer (got ${n})`);\n\t\t\t}\n\t\t\tconst hit = tailCache.get(n);\n\t\t\tif (hit !== undefined) {\n\t\t\t\t// LRU touch: move to end of insertion order.\n\t\t\t\ttailCache.delete(n);\n\t\t\t\ttailCache.set(n, hit);\n\t\t\t\treturn hit.node;\n\t\t\t}\n\t\t\tevictOldestIfFull(tailCache);\n\t\t\tconst node_ = derived(\n\t\t\t\t[entries],\n\t\t\t\t([s]) => {\n\t\t\t\t\tconst list = s as readonly T[];\n\t\t\t\t\tif (n === 0 || list.length === 0) return [];\n\t\t\t\t\treturn list.slice(Math.max(0, list.length - n));\n\t\t\t\t},\n\t\t\t\t{ initial: backend.tail(n), describeKind: \"derived\" },\n\t\t\t);\n\t\t\tconst dispose = keepaliveDerived(node_);\n\t\t\ttailCache.set(n, { node: node_, dispose });\n\t\t\treturn node_;\n\t\t},\n\n\t\tslice(start: number, stop?: number): Node<readonly T[]> {\n\t\t\tif (!Number.isInteger(start) || start < 0) {\n\t\t\t\tthrow new RangeError(`slice: start must be a non-negative integer (got ${start})`);\n\t\t\t}\n\t\t\t// P4: reject negative stop explicitly to keep bundle / backend / derived\n\t\t\t// consistent (JS `Array.prototype.slice` supports negative stop, but the\n\t\t\t// backend can't cheaply honor it without scanning length, so we disallow).\n\t\t\tif (stop !== undefined && (!Number.isInteger(stop) || stop < 0)) {\n\t\t\t\tthrow new RangeError(\n\t\t\t\t\t`slice: stop must be a non-negative integer or undefined (got ${stop})`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst key = sliceKey(start, stop);\n\t\t\tconst hit = sliceCache.get(key);\n\t\t\tif (hit !== undefined) {\n\t\t\t\tsliceCache.delete(key);\n\t\t\t\tsliceCache.set(key, hit);\n\t\t\t\treturn hit.node;\n\t\t\t}\n\t\t\tevictOldestIfFull(sliceCache);\n\t\t\tconst node_ = derived(\n\t\t\t\t[entries],\n\t\t\t\t([s]) => {\n\t\t\t\t\tconst list = s as readonly T[];\n\t\t\t\t\treturn stop === undefined ? list.slice(start) : list.slice(start, stop);\n\t\t\t\t},\n\t\t\t\t{ initial: backend.slice(start, stop), describeKind: \"derived\" },\n\t\t\t);\n\t\t\tconst dispose = keepaliveDerived(node_);\n\t\t\tsliceCache.set(key, { node: node_, dispose });\n\t\t\treturn node_;\n\t\t},\n\n\t\tdisposeTail(n: number): boolean {\n\t\t\tconst hit = tailCache.get(n);\n\t\t\tif (hit === undefined) return false;\n\t\t\thit.dispose();\n\t\t\ttailCache.delete(n);\n\t\t\treturn true;\n\t\t},\n\n\t\tdisposeSlice(start: number, stop?: number): boolean {\n\t\t\tconst key = sliceKey(start, stop);\n\t\t\tconst hit = sliceCache.get(key);\n\t\t\tif (hit === undefined) return false;\n\t\t\thit.dispose();\n\t\t\tsliceCache.delete(key);\n\t\t\treturn true;\n\t\t},\n\n\t\tdisposeAllViews(): void {\n\t\t\tfor (const entry of tailCache.values()) entry.dispose();\n\t\t\ttailCache.clear();\n\t\t\tfor (const entry of sliceCache.values()) entry.dispose();\n\t\t\tsliceCache.clear();\n\t\t},\n\n\t\tdispose(): void {\n\t\t\t// D6(a): currently identical to disposeAllViews. Exposed as a\n\t\t\t// uniform lifecycle API across all 4 reactive data structures.\n\t\t\tfor (const entry of tailCache.values()) entry.dispose();\n\t\t\ttailCache.clear();\n\t\t\tfor (const entry of sliceCache.values()) entry.dispose();\n\t\t\tsliceCache.clear();\n\t\t},\n\t};\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-QA3RP5NH.js → chunk-NZMBRXQV.js}

@@ -240,9 +240,20 @@ var flushInProgress = false;
 var drainPhase2 = [];
 var drainPhase3 = [];
 var drainPhase4 = [];
+var flushHooks = [];
 function isBatching() {
   return batchDepth > 0 || flushInProgress;
 }
+function isExplicitlyBatching() {
+  return batchDepth > 0;
+}
+function registerBatchFlushHook(hook) {
+  if (batchDepth > 0) {
+    flushHooks.push(hook);
+  } else {
+    hook();
+  }
+}
 function batch(fn) {
   batchDepth += 1;
   let threw = false;
@@ -256,6 +267,13 @@ function batch(fn) {
     if (batchDepth === 0) {
       if (threw) {
         if (!flushInProgress) {
+          const hooks = flushHooks.splice(0);
+          for (const h of hooks) {
+            try {
+              h();
+            } catch {
+            }
+          }
           drainPhase2.length = 0;
           drainPhase3.length = 0;
           drainPhase4.length = 0;
@@ -272,7 +290,18 @@ function drainPending() {
   const errors = [];
   let iterations = 0;
   try {
-    while (drainPhase2.length > 0 || drainPhase3.length > 0 || drainPhase4.length > 0) {
+    while (drainPhase2.length > 0 || drainPhase3.length > 0 || drainPhase4.length > 0 || ownsFlush && flushHooks.length > 0) {
+      if (ownsFlush && flushHooks.length > 0) {
+        const hooks = flushHooks.splice(0);
+        for (const h of hooks) {
+          try {
+            h();
+          } catch (e) {
+            errors.push(e);
+          }
+        }
+        continue;
+      }
       iterations += 1;
       if (iterations > MAX_DRAIN_ITERATIONS) {
         drainPhase2.length = 0;
@@ -962,6 +991,22 @@ var NodeImpl = class _NodeImpl {
    * treats `0` as "wave settled" — O(1) check for full dep settlement.
    */
   _dirtyDepCount = 0;
+  // --- Per-batch emit accumulator (Bug 2: K+1 fan-in fix) ---
+  /**
+   * Inside an explicit `batch(() => ...)` scope, every `_emit` accumulates
+   * its already-framed messages here instead of dispatching synchronously.
+   * At batch end, `_flushBatchPending` runs (registered via
+   * `registerBatchFlushHook`) and delivers the whole accumulated batch as
+   * one `downWithBatch` call — collapsing what would otherwise be K
+   * separate sink invocations into one. This is the fix for the diamond
+   * fan-in K+1 over-fire.
+   *
+   * `null` outside batch (or after flush). Only ever appended to within
+   * a single explicit batch lifetime; reset to `null` on flush. State
+   * updates (cache, version, status) still happen per-emit via
+   * `_updateState` — only the downstream delivery is coalesced.
+   */
+  _batchPendingMessages = null;
   // --- PAUSE/RESUME lock tracking (C0) ---
   /**
    * Set of active pause locks held against this node. Every `[PAUSE, lockId]`
@@ -1339,7 +1384,10 @@ var NodeImpl = class _NodeImpl {
         dep.unsub = noopUnsub;
         dep.unsub = dep.node.subscribe((msgs) => {
           if (dep.unsub === null) return;
+          const tierOf = this._config.tierOf;
+          let sawSettlement = false;
           for (const m of msgs) {
+            if (tierOf(m[0]) >= 3) sawSettlement = true;
             this._config.onMessage(
               this,
               m,
@@ -1347,6 +1395,7 @@ var NodeImpl = class _NodeImpl {
               this._actions
             );
           }
+          if (sawSettlement) this._maybeRunFnOnSettlement();
         });
         subscribedCount++;
       }
@@ -1401,7 +1450,10 @@ var NodeImpl = class _NodeImpl {
     try {
       record.unsub = depNode.subscribe((msgs) => {
         if (record.unsub === null) return;
+        const tierOf = this._config.tierOf;
+        let sawSettlement = false;
         for (const m of msgs) {
+          if (tierOf(m[0]) >= 3) sawSettlement = true;
           this._config.onMessage(
             this,
             m,
@@ -1409,6 +1461,7 @@ var NodeImpl = class _NodeImpl {
             this._actions
           );
         }
+        if (sawSettlement) this._maybeRunFnOnSettlement();
       });
     } catch (err) {
       record.unsub = null;
@@ -1530,7 +1583,6 @@ var NodeImpl = class _NodeImpl {
       }
       return;
     }
-    this._maybeRunFnOnSettlement();
   }
   // --- Centralized dep-state transitions (A3 settlement counters) ---
   //
@@ -1902,10 +1954,10 @@ var NodeImpl = class _NodeImpl {
           }
         }
         if (immediate.length > 0) {
-          downWithBatch(this._deliverToSinks, immediate, tierOf);
+          this._dispatchOrAccumulate(immediate);
         }
       } else {
-        downWithBatch(this._deliverToSinks, finalMessages, this._config.tierOf);
+        this._dispatchOrAccumulate(finalMessages);
       }
     }
     if (equalsError != null) {
@@ -2028,6 +2080,50 @@ var NodeImpl = class _NodeImpl {
     const snapshot = [...this._sinks];
     for (const sink of snapshot) sink(messages);
   };
+  /**
+   * @internal Dispatch entry point that respects the per-batch emit
+   * accumulator (Bug 2). Inside an explicit `batch()` scope, append to
+   * `_batchPendingMessages` and register a flush hook on first append.
+   * Outside batch — or during a drain (where `flushInProgress` is true
+   * but `batchDepth` is 0) — dispatch synchronously through `downWithBatch`.
+   *
+   * Per-emit state updates (`_frameBatch`, `_updateState`) have already
+   * happened by the time we reach here; only the **downstream delivery**
+   * is coalesced. Cache, version, and status are visible mid-batch on
+   * the emitting node itself.
+   */
+  _dispatchOrAccumulate(messages) {
+    if (isExplicitlyBatching()) {
+      if (this._batchPendingMessages === null) {
+        this._batchPendingMessages = [];
+        registerBatchFlushHook(() => this._flushBatchPending());
+      }
+      for (const m of messages) this._batchPendingMessages.push(m);
+      return;
+    }
+    downWithBatch(this._deliverToSinks, messages, this._config.tierOf);
+  }
+  /**
+   * @internal Flushes the accumulated batch through `downWithBatch` and
+   * clears the pending state. Idempotent — safe to call when pending is
+   * already null or empty (e.g. on a `batch()` throw, where the hook
+   * fires for cleanup but the drainPhase queues are wiped after).
+   *
+   * Critical: the accumulated batch is interleaved per-emit framings like
+   * `[DIRTY, DATA(1), DIRTY, DATA(2)]` — non-monotone tier order. We must
+   * re-frame to sort by tier before handing to `downWithBatch`, which
+   * assumes pre-sorted input. `_frameBatch` also handles the synthetic
+   * DIRTY prepend rule (no-op here — `hasDirty` is true since each
+   * accumulated emit already carries its own DIRTY prefix).
+   */
+  _flushBatchPending() {
+    const pending = this._batchPendingMessages;
+    if (pending === null) return;
+    this._batchPendingMessages = null;
+    if (pending.length === 0) return;
+    const framed = this._frameBatch(pending);
+    downWithBatch(this._deliverToSinks, framed, this._config.tierOf);
+  }
 };
 var isNodeArray = (value) => Array.isArray(value);
 var isNodeOptionsObject = (value) => typeof value === "object" && value != null && !Array.isArray(value);
@@ -2231,4 +2327,4 @@ export {
   autoTrackNode,
   pipe
 };
-//# sourceMappingURL=chunk-QA3RP5NH.js.map
+//# sourceMappingURL=chunk-NZMBRXQV.js.map