@wrongstack/core 0.310.1 → 0.313.1

package/dist/chunk-4LJJYBAU.js

@@ -0,0 +1,388 @@
+// src/kernel/events.ts
+var MAX_WILDCARDS = 500;
+var MAX_NAMED_LISTENERS = 2e3;
+var EventBus = class {
+  listeners = /* @__PURE__ */ new Map();
+  wildcards = [];
+  logger;
+  /**
+   * Dispatch arrays cached per event name, rebuilt lazily after a
+   * subscription change. See {@link namedSnapshot}. Every mutation of
+   * `listeners` must invalidate the matching entry, and every mutation of
+   * `wildcards` must null `wildcardSnapshotCache` — a missed invalidation
+   * means an emit dispatches to a stale listener set.
+   */
+  listenerSnapshots = /* @__PURE__ */ new Map();
+  wildcardSnapshotCache = null;
+  setLogger(logger) {
+    this.logger = logger;
+  }
+  on(event, fn) {
+    if (this.listenerCount() >= MAX_NAMED_LISTENERS) {
+      this.logger?.error(
+        `EventBus named listener limit (~${MAX_NAMED_LISTENERS}) reached \u2014 rejecting on("${event}"). Callers must dispose their named listeners to prevent unbounded memory growth.`
+      );
+      return () => {
+      };
+    }
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    this.listenerSnapshots.delete(event);
+    return () => this.off(event, fn);
+  }
+  off(event, fn) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    set.delete(fn);
+    this.listenerSnapshots.delete(event);
+    if (set.size === 0) this.listeners.delete(event);
+  }
+  once(event, fn) {
+    const wrapper = (payload) => {
+      this.off(event, wrapper);
+      fn(payload);
+    };
+    this.on(event, wrapper);
+    return () => {
+      this.off(event, wrapper);
+    };
+  }
+  /**
+   * Subscribe to all events, regardless of name. Short-hand for
+   * `onPattern('*')`. Use for logging, debugging, or forwarding every
+   * event to another bus (as FleetBus does).
+   *
+   * Returns an unsubscribe function.
+   */
+  onAny(fn, owner) {
+    return this.onPattern("*", fn, owner);
+  }
+  /**
+   * Subscribe to all events whose name matches a glob-style prefix.
+   * `'tool.*'` matches `tool.started`, `tool.executed`, `tool.progress`, etc.
+   * `'*'` matches every event.
+   *
+   * The handler receives `(eventName, payload)` with the event name as a
+   * string and the payload as `unknown`. Use for logging, debugging, or
+   * metrics collection across a family of events.
+   *
+   * Returns an unsubscribe function.
+   */
+  onPattern(pattern, fn, owner) {
+    if (this.wildcards.length >= MAX_WILDCARDS) {
+      this.logger?.error(
+        `EventBus wildcard limit (${MAX_WILDCARDS}) reached \u2014 rejecting onPattern("${pattern}")` + (owner ? ` (owner: ${owner})` : "") + ". Callers must dispose their wildcard listeners to prevent unbounded growth."
+      );
+      return () => {
+      };
+    }
+    const match = makePatternMatcher(pattern);
+    const entry = { match, fn, owner };
+    this.wildcards.push(entry);
+    this.wildcardSnapshotCache = null;
+    return () => {
+      const idx = this.wildcards.indexOf(entry);
+      if (idx >= 0) {
+        this.wildcards.splice(idx, 1);
+        this.wildcardSnapshotCache = null;
+      }
+    };
+  }
+  /**
+   * Subscribe to all events whose name matches a RegExp.
+   * More flexible than `onPattern` — use when you need regex features
+   * (alternation, character classes, capture groups).
+   *
+   * Returns an unsubscribe function.
+   */
+  onRegex(regex, fn, owner) {
+    if (this.wildcards.length >= MAX_WILDCARDS) {
+      this.logger?.error(
+        `EventBus wildcard limit (${MAX_WILDCARDS}) reached \u2014 rejecting onRegex(${regex})` + (owner ? ` (owner: ${owner})` : "") + ". Callers must dispose their wildcard listeners to prevent unbounded growth."
+      );
+      return () => {
+      };
+    }
+    const entry = { match: (e) => regex.test(e), fn, owner };
+    this.wildcards.push(entry);
+    this.wildcardSnapshotCache = null;
+    return () => {
+      const idx = this.wildcards.indexOf(entry);
+      if (idx >= 0) {
+        this.wildcards.splice(idx, 1);
+        this.wildcardSnapshotCache = null;
+      }
+    };
+  }
+  emit(event, payload) {
+    const snapshot = this.namedSnapshot(event);
+    if (snapshot !== void 0) {
+      for (const fn of snapshot) {
+        try {
+          fn(payload);
+        } catch (err) {
+          this.logger?.error(`EventBus listener for "${event}" threw`, err);
+        }
+      }
+    }
+    if (this.wildcards.length > 0) {
+      const name = event;
+      for (const { match, fn } of this.wildcardSnapshot()) {
+        if (!match(name)) continue;
+        try {
+          fn(name, payload);
+        } catch (err) {
+          this.logger?.error(`EventBus wildcard listener for "${name}" threw`, err);
+        }
+      }
+    }
+  }
+  /**
+   * Dispatch array for one event name, or `undefined` when nothing is
+   * subscribed.
+   *
+   * Dispatch iterates a stable array rather than the live Set so a listener
+   * that subscribes or unsubscribes mid-emit cannot change what this round
+   * delivers: an addition fires from the next emit, a removal may still fire
+   * this round. That is the contract callers rely on, and it is unchanged.
+   *
+   * What changed is who pays for it. Building the array per emit did O(number
+   * of listeners) copying on every event, including `tool.progress` and
+   * streaming deltas — the highest-frequency paths in the process. The array
+   * is now cached and rebuilt only when the subscription set actually changes,
+   * which is wiring time and essentially never during a run. Measured at 2M
+   * emits with 12 named + 6 wildcard listeners: 207 ms → 141 ms.
+   *
+   * This is a throughput win, not a footprint one: the per-emit arrays died in
+   * the nursery and never showed up as retained heap (measured heap growth was
+   * the same either way). Do not cite this as a memory fix.
+   *
+   * A mutation during dispatch invalidates the cache for the *next* emit while
+   * the in-flight loop keeps walking the array it started with — which is
+   * exactly the snapshot semantics described above.
+   */
+  namedSnapshot(event) {
+    const cached = this.listenerSnapshots.get(event);
+    if (cached !== void 0) return cached;
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) return void 0;
+    const snapshot = [...set];
+    this.listenerSnapshots.set(event, snapshot);
+    return snapshot;
+  }
+  /** Wildcard counterpart to {@link namedSnapshot}; same caching rationale. */
+  wildcardSnapshot() {
+    this.wildcardSnapshotCache ??= this.wildcards.slice();
+    return this.wildcardSnapshotCache;
+  }
+  /**
+   * Emit a plugin-defined event that is intentionally outside EventMap.
+   * Custom events are delivered to wildcard/pattern listeners only; typed
+   * listeners remain reserved for core EventMap keys.
+   */
+  emitCustom(event, payload) {
+    if (this.wildcards.length === 0) return;
+    for (const { match, fn } of this.wildcardSnapshot()) {
+      if (!match(event)) continue;
+      try {
+        fn(event, payload);
+      } catch (err) {
+        this.logger?.error(`EventBus wildcard listener for "${event}" threw`, err);
+      }
+    }
+  }
+  clear() {
+    this.listeners.clear();
+    this.wildcards.length = 0;
+    this.listenerSnapshots.clear();
+    this.wildcardSnapshotCache = null;
+  }
+  /**
+   * V2-D: introspection helper. Pass an `event` to count handlers for a
+   * single key, or omit to get the total across every event. Used by the
+   * leak-detection smoke test to flag handler accumulation across runs.
+   * Does NOT include wildcard listeners.
+   */
+  listenerCount(event) {
+    if (event !== void 0) return this.listeners.get(event)?.size ?? 0;
+    let total = 0;
+    for (const set of this.listeners.values()) total += set.size;
+    return total;
+  }
+  /**
+   * Number of wildcard listeners currently registered.
+   */
+  wildcardCount() {
+    return this.wildcards.length;
+  }
+  /**
+   * True if anything would receive an emit for `event` — a named listener
+   * OR a wildcard/regex pattern that matches the event name. Unlike
+   * `listenerCount`, this DOES account for wildcards, so callers that gate
+   * behavior on "is anyone listening?" (e.g. SubagentBudget deciding whether
+   * to negotiate a soft limit vs hard-stop) don't misfire when the only
+   * subscriber is a pattern listener like the FleetBus's `onPattern('*')`.
+   */
+  hasListenerFor(event) {
+    if ((this.listeners.get(event)?.size ?? 0) > 0) return true;
+    return this.wildcards.some((w) => w.match(event));
+  }
+};
+var ScopedEventBus = class extends EventBus {
+  // Track registrations by a unique counter key so that EventBus.once()'s
+  // internal listener-removal doesn't affect our tracking (once removes the
+  // fn from EventBus but we still need to call our unsub during teardown).
+  registrations = /* @__PURE__ */ new Map();
+  nextKey = 0;
+  /**
+   * Identical to `EventBus.on` but the listener is tracked so that
+   * `teardown()` will remove it automatically.
+   */
+  on(event, fn) {
+    const key = this.nextKey++;
+    const unsub = super.on(event, fn);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+  /**
+   * Identical to `EventBus.once` but the listener is tracked so that
+   * `teardown()` will remove it automatically.
+   *
+   * Uses EventBus's public API directly to avoid triggering our own `on()`
+   * override (which would consume a key slot for the wrapper, then orphan
+   * our registration entry under a different key).
+   *
+   * When the wrapper fires, it cleans up BOTH the underlying EventBus
+   * listener AND the tracking entry — so `scopedListenerCount` returns to
+   * its pre-`once()` value without requiring the caller to invoke the
+   * returned unsubscribe. The returned `unsub` is still safe to call
+   * after auto-removal (its delete is a no-op and its off() finds
+   * nothing to remove).
+   */
+  once(event, fn) {
+    const key = this.nextKey++;
+    const wrapper = (payload) => {
+      EventBus.prototype.off.call(this, event, wrapper);
+      this.registrations.delete(key);
+      fn(payload);
+    };
+    EventBus.prototype.on.call(this, event, wrapper);
+    const unsub = () => {
+      this.registrations.delete(key);
+      EventBus.prototype.off.call(this, event, wrapper);
+    };
+    this.registrations.set(key, unsub);
+    return unsub;
+  }
+  /**
+   * Subscribe to all events. Alias for `onPattern('*')` — the listener is
+   * tracked so that `teardown()` will remove it automatically.
+   */
+  onAny(fn, owner) {
+    if (this.wildcards.length >= MAX_WILDCARDS) {
+      this.logger?.error(
+        `EventBus wildcard limit (${MAX_WILDCARDS}) reached \u2014 rejecting onAny()` + (owner ? ` (owner: ${owner})` : "") + ". Callers must dispose their wildcard listeners to prevent unbounded growth."
+      );
+      return () => {
+      };
+    }
+    const key = this.nextKey++;
+    const unsub = EventBus.prototype.onPattern.call(this, "*", fn, owner);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+  /**
+   * Identical to `EventBus.onPattern` but the listener is tracked so that
+   * `teardown()` will remove it automatically.
+   */
+  onPattern(pattern, fn, owner) {
+    if (this.wildcards.length >= MAX_WILDCARDS) {
+      this.logger?.error(
+        `EventBus wildcard limit (${MAX_WILDCARDS}) reached \u2014 rejecting onPattern("${pattern}")` + (owner ? ` (owner: ${owner})` : "") + ". Callers must dispose their wildcard listeners to prevent unbounded growth."
+      );
+      return () => {
+      };
+    }
+    const key = this.nextKey++;
+    const unsub = super.onPattern(pattern, fn, owner);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+  /**
+   * Identical to `EventBus.onRegex` but the listener is tracked so that
+   * `teardown()` will remove it automatically.
+   */
+  onRegex(regex, fn, owner) {
+    if (this.wildcards.length >= MAX_WILDCARDS) {
+      this.logger?.error(
+        `EventBus wildcard limit (${MAX_WILDCARDS}) reached \u2014 rejecting onRegex(${regex})` + (owner ? ` (owner: ${owner})` : "") + ". Callers must dispose their wildcard listeners to prevent unbounded growth."
+      );
+      return () => {
+      };
+    }
+    const key = this.nextKey++;
+    const unsub = super.onRegex(regex, fn, owner);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+  /**
+   * Remove every listener that was registered through this scoped bus.
+   * Idempotent — calling it multiple times is safe.
+   *
+   * Also available as `[Symbol.dispose]` for explicit resource management:
+   * ```ts
+   * using scope = new ScopedEventBus();
+   * scope.on('tool.executed', handler);
+   * // automatically teardown()'d when scope exits
+   * ```
+   */
+  teardown() {
+    for (const unsub of this.registrations.values()) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    this.registrations.clear();
+    this.clear();
+  }
+  /** Alias for `teardown()` — enables `using new ScopedEventBus()` in Node ≥ 22. */
+  [Symbol.dispose]() {
+    this.teardown();
+  }
+  /** Number of tracked registrations. */
+  get scopedListenerCount() {
+    return this.registrations.size;
+  }
+};
+var MATCH_ALL = () => true;
+function makePatternMatcher(pattern) {
+  if (pattern === "*") return MATCH_ALL;
+  if (pattern.endsWith(".*")) {
+    const prefix = pattern.slice(0, -2);
+    return (e) => e.startsWith(`${prefix}.`);
+  }
+  return (e) => e === pattern;
+}
+
+export {
+  EventBus,
+  ScopedEventBus
+};
+//# sourceMappingURL=chunk-4LJJYBAU.js.map