@rotorsoft/act 0.45.0 → 0.46.0

package/dist/index.cjs

@@ -1235,6 +1235,425 @@ process.once("unhandledRejection", async (arg) => {
 // src/act.ts
 var import_node_events = __toESM(require("events"), 1);
 
+// src/internal/event-versions.ts
+var VERSION_SUFFIX = /^(.+?)_v(\d+)$/;
+function parse(name) {
+  const m = name.match(VERSION_SUFFIX);
+  if (m) {
+    const v = Number.parseInt(m[2], 10);
+    if (v >= 2) return { base: m[1], version: v };
+  }
+  return { base: name, version: 1 };
+}
+function deprecatedEventNames(names) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const { base, version } = parse(name);
+    const list = groups.get(base);
+    if (list) list.push({ version, name });
+    else groups.set(base, [{ version, name }]);
+  }
+  const deprecated = /* @__PURE__ */ new Set();
+  for (const list of groups.values()) {
+    if (list.length < 2) continue;
+    list.sort((a, b) => b.version - a.version);
+    for (let i = 1; i < list.length; i++) deprecated.add(list[i].name);
+  }
+  return deprecated;
+}
+function currentVersionOf(deprecatedName, allNames) {
+  const target = parse(deprecatedName);
+  let highest;
+  for (const name of allNames) {
+    const { base, version } = parse(name);
+    if (base !== target.base) continue;
+    if (!highest || version > highest.version) highest = { version, name };
+  }
+  return highest && highest.version > target.version ? highest.name : void 0;
+}
+
+// src/internal/audit.ts
+var DEFAULTS = {
+  idle_days: 90,
+  restart_min: 1e4,
+  stuck_minutes: 30,
+  deprecated_min: 0.1,
+  drift_min: 500,
+  near_block: 3
+};
+var ALL_CATEGORIES = [
+  "schema",
+  "close-candidate",
+  "restart-candidate",
+  "deprecated-load",
+  "reaction-health",
+  "snapshot-drift",
+  "routing-health",
+  "correlation-gaps",
+  "clock-anomalies"
+];
+async function* audit(deps, categories, options = {}) {
+  const requested = new Set(categories ?? [...ALL_CATEGORIES]);
+  const orderedCategories = ALL_CATEGORIES.filter((c) => requested.has(c));
+  const passes = orderedCategories.map(
+    (c) => PASS_FACTORIES[c](deps, options)
+  );
+  const needStats = passes.some((p) => p.onStat !== void 0);
+  const needStreams = passes.some((p) => p.onStream !== void 0);
+  const needEvents = passes.some((p) => p.onEvent !== void 0);
+  if (needStats) {
+    const stats = await deps.store().query_stats({}, { count: true, names: true });
+    for (const [stream, s] of stats) {
+      for (const p of passes) p.onStat?.(stream, s);
+    }
+  }
+  if (needStreams) {
+    await deps.store().query_streams((pos) => {
+      for (const p of passes) p.onStream?.(pos);
+    });
+  }
+  if (needEvents) {
+    await deps.store().query((event) => {
+      for (const p of passes) p.onEvent?.(event);
+    }, options.query);
+  }
+  for (const p of passes) await p.finalize?.(deps);
+  for (const p of passes) {
+    for (const f of p.drain()) yield f;
+  }
+}
+var makeSchemaPass = (deps) => {
+  const findings = [];
+  return {
+    category: "schema",
+    onEvent(event) {
+      const name = String(event.name);
+      const state2 = deps.event_to_state.get(name);
+      if (!state2) {
+        if (name.startsWith("__")) return;
+        findings.push({
+          category: "schema",
+          stream: event.stream,
+          event_id: event.id,
+          name,
+          reason: "unknown_event_name"
+        });
+        return;
+      }
+      const schema = state2.events[name];
+      const parsed = schema.safeParse(event.data);
+      if (!parsed.success) {
+        findings.push({
+          category: "schema",
+          stream: event.stream,
+          event_id: event.id,
+          name,
+          reason: "schema_validation_failed",
+          zod_error: parsed.error
+        });
+      }
+    },
+    drain: () => findings
+  };
+};
+var makeDeprecatedLoadPass = (deps, options) => {
+  const share_min = options.thresholds?.deprecated_min ?? DEFAULTS.deprecated_min;
+  const totals = /* @__PURE__ */ new Map();
+  const perStream = /* @__PURE__ */ new Map();
+  return {
+    category: "deprecated-load",
+    onStat(stream, { names }) {
+      for (const [name, count] of Object.entries(names)) {
+        totals.set(name, (totals.get(name) ?? 0) + count);
+        let m = perStream.get(name);
+        if (!m) {
+          m = /* @__PURE__ */ new Map();
+          perStream.set(name, m);
+        }
+        m.set(stream, count);
+      }
+    },
+    drain() {
+      const findings = [];
+      const grand = [...totals.values()].reduce((s, n) => s + n, 0);
+      if (grand === 0) return findings;
+      const deprecated = deprecatedEventNames(deps.known_events);
+      const sorted = [...deprecated].map((name) => ({ name, count: totals.get(name) ?? 0 })).sort((a, b) => b.count - a.count);
+      for (const { name, count } of sorted) {
+        if (count === 0) continue;
+        if (count / grand < share_min) continue;
+        const currentVersion = currentVersionOf(name, deps.known_events);
+        const topStreams = [...perStream.get(name).entries()].map(([stream, c]) => ({ stream, count: c })).sort((a, b) => b.count - a.count).slice(0, 10);
+        findings.push({
+          category: "deprecated-load",
+          name,
+          current_version: currentVersion,
+          total: count,
+          top_streams: topStreams
+        });
+      }
+      return findings;
+    }
+  };
+};
+var makeCloseCandidatePass = (deps, options) => {
+  const idle_days = options.thresholds?.idle_days ?? DEFAULTS.idle_days;
+  const terminal_events = new Set(options.thresholds?.terminal_events ?? []);
+  const idle_cutoff = Date.now() - idle_days * 24 * 60 * 60 * 1e3;
+  const findings = [];
+  return {
+    category: "close-candidate",
+    onStat(stream, { head }) {
+      const head_name = String(head.name);
+      if (head_name.startsWith("__")) return;
+      const head_time = head.created.getTime();
+      const is_idle = head_time < idle_cutoff;
+      const is_terminal = terminal_events.has(head_name);
+      if (!is_idle && !is_terminal) return;
+      findings.push({
+        category: "close-candidate",
+        stream,
+        last_event_at: head.created.toISOString(),
+        reason: is_terminal ? "terminal" : "idle",
+        idle_days: is_idle ? Math.floor((Date.now() - head_time) / (24 * 60 * 60 * 1e3)) : void 0,
+        restart_supported: restartIsSupported(deps, head_name)
+      });
+    },
+    drain: () => findings
+  };
+};
+var makeRestartCandidatePass = (deps, options) => {
+  const threshold = options.thresholds?.restart_min ?? DEFAULTS.restart_min;
+  const findings = [];
+  return {
+    category: "restart-candidate",
+    onStat(stream, { head, count, names }) {
+      if (count < threshold) return;
+      const head_name = String(head.name);
+      if (head_name.startsWith("__")) return;
+      if (!restartIsSupported(deps, head_name)) return;
+      findings.push({
+        category: "restart-candidate",
+        stream,
+        count,
+        // names map is sparse — `__snapshot__` key absent when the
+        // stream has never been snapshotted (a common case for the
+        // restart-candidate signal).
+        snaps: names["__snapshot__"] ?? 0
+      });
+    },
+    drain: () => findings
+  };
+};
+var makeReactionHealthPass = (_deps, options) => {
+  const near_block = options.thresholds?.near_block ?? DEFAULTS.near_block;
+  const stuck_minutes = options.thresholds?.stuck_minutes ?? DEFAULTS.stuck_minutes;
+  const stuck_cutoff = Date.now() - stuck_minutes * 60 * 1e3;
+  const findings = [];
+  return {
+    category: "reaction-health",
+    onStream(p) {
+      if (p.blocked) {
+        findings.push({
+          category: "reaction-health",
+          stream: p.stream,
+          status: "blocked",
+          retry: p.retry,
+          reason: p.error || "blocked without recorded error"
+        });
+        return;
+      }
+      if (p.retry >= near_block) {
+        findings.push({
+          category: "reaction-health",
+          stream: p.stream,
+          status: "near-block",
+          retry: p.retry,
+          reason: `retry ${p.retry} \u2265 near-block threshold ${near_block}`
+        });
+        return;
+      }
+      if (p.leased_by && p.leased_until && p.leased_until.getTime() < stuck_cutoff) {
+        const minutes = Math.floor(
+          (Date.now() - p.leased_until.getTime()) / (60 * 1e3)
+        );
+        findings.push({
+          category: "reaction-health",
+          stream: p.stream,
+          status: "stuck-backoff",
+          retry: p.retry,
+          reason: `lease expired ${minutes}m ago without release`
+        });
+      }
+    },
+    drain: () => findings
+  };
+};
+var makeSnapshotDriftPass = (deps, options) => {
+  const drift_min = options.thresholds?.drift_min ?? DEFAULTS.drift_min;
+  const candidates = [];
+  const findings = [];
+  return {
+    category: "snapshot-drift",
+    onStat(stream, { head, count, names }) {
+      if (!restartIsSupported(deps, String(head.name))) return;
+      if (count < drift_min) return;
+      candidates.push({
+        stream,
+        total: count,
+        snaps: names["__snapshot__"] ?? 0
+      });
+    },
+    async finalize(deps2) {
+      for (const { stream, total, snaps } of candidates) {
+        let events_since_snap = total;
+        let snap_at;
+        if (snaps > 0) {
+          const collected = [];
+          await deps2.store().query(
+            (e) => {
+              collected.push({ id: e.id });
+            },
+            {
+              stream,
+              stream_exact: true,
+              names: ["__snapshot__"],
+              backward: true,
+              limit: 1,
+              with_snaps: true
+            }
+          );
+          snap_at = collected[0].id;
+          let after = 0;
+          await deps2.store().query(
+            () => {
+              after++;
+            },
+            { stream, stream_exact: true, after: snap_at }
+          );
+          events_since_snap = after;
+        }
+        if (events_since_snap < drift_min) continue;
+        findings.push({
+          category: "snapshot-drift",
+          stream,
+          events_since_snap,
+          snap_at
+        });
+      }
+    },
+    drain: () => findings
+  };
+};
+var makeRoutingHealthPass = (deps) => {
+  const findings = [];
+  const seenEventNames = /* @__PURE__ */ new Set();
+  return {
+    category: "routing-health",
+    onStream(p) {
+      if (!p.lane) return;
+      if (deps.declared_lanes.has(p.lane)) return;
+      findings.push({
+        category: "routing-health",
+        stream: p.stream,
+        reason: "unknown-lane",
+        lane: p.lane
+      });
+    },
+    onStat(_stream, { names }) {
+      for (const name of Object.keys(names)) {
+        seenEventNames.add(name);
+      }
+    },
+    finalize() {
+      for (const name of seenEventNames) {
+        if (name.startsWith("__")) continue;
+        if (deps.routed_events.has(name)) continue;
+        findings.push({
+          category: "routing-health",
+          stream: "*",
+          reason: "unrouted"
+        });
+      }
+      return Promise.resolve();
+    },
+    drain: () => findings
+  };
+};
+var makeCorrelationGapsPass = () => {
+  const seenIds = /* @__PURE__ */ new Set();
+  const checks = [];
+  return {
+    category: "correlation-gaps",
+    onEvent(e) {
+      seenIds.add(e.id);
+      const causation = e.meta?.causation;
+      const parentId = causation?.event?.id;
+      if (parentId !== void 0) {
+        checks.push({ stream: e.stream, id: e.id, parentId });
+      }
+    },
+    drain() {
+      const findings = [];
+      for (const { stream, id, parentId } of checks) {
+        if (!seenIds.has(parentId)) {
+          findings.push({
+            category: "correlation-gaps",
+            stream,
+            event_id: id,
+            reason: "orphan-parent"
+          });
+        }
+      }
+      return findings;
+    }
+  };
+};
+var makeClockAnomaliesPass = () => {
+  const findings = [];
+  const lastPerStream = /* @__PURE__ */ new Map();
+  return {
+    category: "clock-anomalies",
+    onEvent(e) {
+      const created = e.created.getTime();
+      if (created > Date.now()) {
+        findings.push({
+          category: "clock-anomalies",
+          stream: e.stream,
+          event_id: e.id,
+          reason: "future-created"
+        });
+      }
+      const prev = lastPerStream.get(e.stream);
+      if (prev !== void 0 && created < prev) {
+        findings.push({
+          category: "clock-anomalies",
+          stream: e.stream,
+          event_id: e.id,
+          reason: "out-of-order"
+        });
+      }
+      lastPerStream.set(e.stream, created);
+    },
+    drain: () => findings
+  };
+};
+function restartIsSupported(deps, headEventName) {
+  const state2 = deps.event_to_state.get(headEventName);
+  return state2?.snap !== void 0;
+}
+var PASS_FACTORIES = {
+  schema: makeSchemaPass,
+  "deprecated-load": makeDeprecatedLoadPass,
+  "close-candidate": makeCloseCandidatePass,
+  "restart-candidate": makeRestartCandidatePass,
+  "reaction-health": makeReactionHealthPass,
+  "snapshot-drift": makeSnapshotDriftPass,
+  "routing-health": makeRoutingHealthPass,
+  "correlation-gaps": makeCorrelationGapsPass,
+  "clock-anomalies": makeClockAnomaliesPass
+};
+
 // src/internal/build-classify.ts
 var ALL_LANES = /* @__PURE__ */ Symbol("act-1103/all-lanes");
 function classifyRegistry(registry, states) {
@@ -2210,43 +2629,6 @@ var DrainController = class {
   }
 };
 
-// src/internal/event-versions.ts
-var VERSION_SUFFIX = /^(.+?)_v(\d+)$/;
-function parse(name) {
-  const m = name.match(VERSION_SUFFIX);
-  if (m) {
-    const v = Number.parseInt(m[2], 10);
-    if (v >= 2) return { base: m[1], version: v };
-  }
-  return { base: name, version: 1 };
-}
-function deprecatedEventNames(names) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const name of names) {
-    const { base, version } = parse(name);
-    const list = groups.get(base);
-    if (list) list.push({ version, name });
-    else groups.set(base, [{ version, name }]);
-  }
-  const deprecated = /* @__PURE__ */ new Set();
-  for (const list of groups.values()) {
-    if (list.length < 2) continue;
-    list.sort((a, b) => b.version - a.version);
-    for (let i = 1; i < list.length; i++) deprecated.add(list[i].name);
-  }
-  return deprecated;
-}
-function currentVersionOf(deprecatedName, allNames) {
-  const target = parse(deprecatedName);
-  let highest;
-  for (const name of allNames) {
-    const { base, version } = parse(name);
-    if (base !== target.base) continue;
-    if (!highest || version > highest.version) highest = { version, name };
-  }
-  return highest && highest.version > target.version ? highest.name : void 0;
-}
-
 // src/internal/merge.ts
 var import_zod4 = require("zod");
 function baseTypeName(zodType) {
@@ -2636,6 +3018,15 @@ var Act = class {
       if (cfg?.cycleMs !== void 0) controller.start(cfg.cycleMs);
       this._drain_controllers.set(name, controller);
     }
+    this._audit_deps = {
+      store: store2,
+      logger: this._logger,
+      event_to_state: eventToState,
+      states: this._states,
+      known_events: new Set(eventToState.keys()),
+      declared_lanes: new Set(this._drain_controllers.keys()),
+      routed_events: new Set(eventToLanes.keys())
+    };
     this._correlate = new CorrelateCycle(
       this.registry,
       staticTargets,
@@ -2727,6 +3118,14 @@ var Act = class {
    * reactions target.
    */
   _event_to_lanes;
+  /**
+   * Audit dependency bag (#723). Built once at construction; held as
+   * an immutable snapshot of the registry state the audit module
+   * needs. Lives in `internal/audit.ts` — this orchestrator never
+   * carries audit logic, only the deps + a one-liner that hands them
+   * over.
+   */
+  _audit_deps;
   /** Logger resolved at construction time (after user port configuration) */
   _logger = log();
   /** Wraps a public-method body so internal `store()`/`cache()` resolve to the
@@ -3343,6 +3742,50 @@ var Act = class {
       return positions;
     });
   }
+  /**
+   * Operator-driven store audit (#723).
+   *
+   * Walks the connected store and yields per-category findings —
+   * each tagged with the remediation it suggests. Same operator-
+   * driven category as `app.close()` / `app.reset()` /
+   * `app.unblock()` / `app.blocked_streams()`: never auto-invoked by
+   * the framework; the operator decides when to run it (CI gate,
+   * scheduled job, ad-hoc forensics) and what to do with the
+   * findings.
+   *
+   * Categories are independent — pass a subset to scope the work,
+   * or omit to run everything:
+   *
+   * ```typescript
+   * // Targeted: schema drift + deprecated-event load only
+   * for await (const f of app.audit(["schema", "deprecated-load"], {
+   *   query: { created_after: lastScan },
+   *   thresholds: { deprecatedLoadShareMin: 0.10 },
+   * })) {
+   *   await escalate(f);
+   * }
+   *
+   * // Full audit, default thresholds
+   * for await (const f of app.audit()) console.log(f);
+   * ```
+   *
+   * Returns an `AsyncIterable` so callers can `break` early — the
+   * underlying store paginations respect the iterator protocol and
+   * stop cleanly. Each finding is emitted independently, so
+   * pipelining into Slack / persistence / further analysis works
+   * without buffering the full report in memory.
+   *
+   * Findings shape — see {@link AuditFinding}. The discriminated
+   * union carries enough context for the operator to act on each
+   * finding directly: stream id, event id, recommendation hints.
+   *
+   * @param categories - Subset of categories to run (default: all).
+   * @param options - Query window + per-category thresholds.
+   * @returns Async iterable of {@link AuditFinding}.
+   */
+  audit(categories, options) {
+    return audit(this._audit_deps, categories, options);
+  }
   /**
    * Bulk-update scheduling priority for streams matching `filter`.
    *