@rotorsoft/act 0.37.0 → 0.39.0

package/dist/index.cjs

@@ -55,7 +55,7 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   ZodEmpty: () => ZodEmpty,
   act: () => act,
-  cache: () => cache,
+  cache: () => cache2,
   config: () => config,
   dispose: () => dispose,
   disposeAndExit: () => disposeAndExit,
@@ -63,14 +63,18 @@ __export(index_exports, {
   log: () => log,
   port: () => port,
   projection: () => projection,
+  scoped: () => scoped,
   sleep: () => sleep,
   slice: () => slice,
   state: () => state,
-  store: () => store,
+  store: () => store2,
   validate: () => validate
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/ports.ts
+var import_node_async_hooks = require("async_hooks");
+
 // src/adapters/console-logger.ts
 var LEVEL_VALUES = {
   fatal: 60,
@@ -971,6 +975,7 @@ var InMemoryStore = class {
 };
 
 // src/ports.ts
+var scoped = new import_node_async_hooks.AsyncLocalStorage();
 var ExitCodes = ["ERROR", "EXIT"];
 var adapters = /* @__PURE__ */ new Map();
 function port(injector) {
@@ -990,11 +995,17 @@ var log = port(function log2(adapter) {
     pretty: cfg.env !== "production"
   });
 });
-var store = port(function store2(adapter) {
-  return adapter || new InMemoryStore();
+var _store = port(function store(adapter) {
+  return adapter ?? new InMemoryStore();
+});
+var store2 = ((adapter) => {
+  return scoped.getStore()?.store ?? _store(adapter);
 });
-var cache = port(function cache2(adapter) {
-  return adapter || new InMemoryCache();
+var _cache = port(function cache(adapter) {
+  return adapter ?? new InMemoryCache();
+});
+var cache2 = ((adapter) => {
+  return scoped.getStore()?.cache ?? _cache(adapter);
 });
 var disposers = [];
 async function disposeAndExit(code = "EXIT") {
@@ -1124,7 +1135,7 @@ async function scanStreamHeads(streams) {
       let maxId = -1;
       let version = -1;
       let lastEventName = "";
-      await store().query(
+      await store2().query(
         (e) => {
           if (e.name === TOMBSTONE_EVENT || maxId !== -1) return;
           maxId = e.id;
@@ -1141,7 +1152,7 @@ async function scanStreamHeads(streams) {
 async function partitionBySafety(streamInfo, reactiveEventsSize, skipped) {
   if (reactiveEventsSize === 0) return [...streamInfo.keys()];
   const pendingSet = /* @__PURE__ */ new Set();
-  await store().query_streams((position) => {
+  await store2().query_streams((position) => {
     const sourceRe = position.source ? RegExp(position.source) : void 0;
     for (const [stream, info] of streamInfo) {
       if ((!sourceRe || sourceRe.test(stream)) && position.at < info.maxId) {
@@ -1212,13 +1223,13 @@ async function truncateAndWarmCache(guarded, seedStates, guardEvents, correlatio
       }
     };
   });
-  const truncated = await store().truncate(truncTargets);
+  const truncated = await store2().truncate(truncTargets);
   await Promise.all(
     guarded.map(async (stream) => {
       const entry = truncated.get(stream);
       const state2 = seedStates.get(stream);
       if (state2 && entry) {
-        await cache().set(stream, {
+        await cache2().set(stream, {
           state: state2,
           version: entry.committed.version,
           event_id: entry.committed.id,
@@ -1226,7 +1237,7 @@ async function truncateAndWarmCache(guarded, seedStates, guardEvents, correlatio
           snaps: 1
         });
       } else {
-        await cache().invalidate(stream);
+        await cache2().invalidate(stream);
       }
     })
   );
@@ -1261,7 +1272,7 @@ var CorrelateCycle = class {
   async init() {
     if (this._initialized) return;
     this._initialized = true;
-    const { watermark } = await store().subscribe([...this.staticTargets]);
+    const { watermark } = await store2().subscribe([...this.staticTargets]);
     this._checkpoint = watermark;
     this.onInit?.();
     for (const { stream } of this.staticTargets) {
@@ -1280,7 +1291,7 @@ var CorrelateCycle = class {
     const after = Math.max(this._checkpoint, query.after || -1);
     const correlated = /* @__PURE__ */ new Map();
     let last_id = after;
-    await store().query(
+    await store2().query(
       (event) => {
         last_id = event.id;
         const register = this.registry.events[event.name];
@@ -1800,12 +1811,12 @@ var SettleLoop = class {
 };
 
 // src/internal/drain.ts
-var claim = (lagging, leading, by, millis) => store().claim(lagging, leading, by, millis);
+var claim = (lagging, leading, by, millis) => store2().claim(lagging, leading, by, millis);
 async function fetch(leased, eventLimit) {
   return Promise.all(
     leased.map(async ({ stream, source, at, lagging }) => {
       const events = [];
-      await store().query((e) => events.push(e), {
+      await store2().query((e) => events.push(e), {
         stream: source,
         after: at,
         limit: eventLimit
@@ -1814,9 +1825,9 @@ async function fetch(leased, eventLimit) {
     })
   );
 }
-var ack = (leases) => store().ack(leases);
-var block = (leases) => store().block(leases);
-var subscribe = (streams) => store().subscribe(streams);
+var ack = (leases) => store2().ack(leases);
+var block = (leases) => store2().block(leases);
+var subscribe = (streams) => store2().subscribe(streams);
 
 // src/internal/event-sourcing.ts
 var import_node_crypto3 = require("crypto");
@@ -1824,7 +1835,7 @@ var import_act_patch = require("@rotorsoft/act-patch");
 async function snap(snapshot) {
   try {
     const { id, stream, name, meta, version } = snapshot.event;
-    await store().commit(
+    await store2().commit(
       stream,
       [{ name: SNAP_EVENT, data: snapshot.state }],
       {
@@ -1840,7 +1851,7 @@ async function snap(snapshot) {
 }
 async function tombstone(stream, expectedVersion, correlation) {
   try {
-    const [committed] = await store().commit(
+    const [committed] = await store2().commit(
       stream,
       [{ name: TOMBSTONE_EVENT, data: {} }],
       { correlation, causation: {} },
@@ -1854,7 +1865,7 @@ async function tombstone(stream, expectedVersion, correlation) {
 }
 async function load(me, stream, callback, asOf) {
   const timeTravel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
-  const cached = timeTravel ? void 0 : await cache().get(stream);
+  const cached = timeTravel ? void 0 : await cache2().get(stream);
   const cache_hit = !!cached;
   let state2 = cached?.state ?? (me.init ? me.init() : {});
   let patches = cached?.patches ?? 0;
@@ -1862,7 +1873,7 @@ async function load(me, stream, callback, asOf) {
   let version = cached?.version ?? -1;
   let replayed = 0;
   let event;
-  await store().query(
+  await store2().query(
     (e) => {
       event = e;
       version = e.version;
@@ -1897,7 +1908,7 @@ async function load(me, stream, callback, asOf) {
     }
   );
   if (replayed > 0 && !timeTravel && event) {
-    await cache().set(stream, {
+    await cache2().set(stream, {
       state: state2,
       version,
       event_id: event.id,
@@ -1970,7 +1981,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
   };
   let committed;
   try {
-    committed = await store().commit(
+    committed = await store2().commit(
       stream,
       emitted,
       meta,
@@ -1982,7 +1993,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     );
   } catch (error) {
     if (error instanceof ConcurrencyError) {
-      await cache().invalidate(stream);
+      await cache2().invalidate(stream);
     }
     throw error;
   }
@@ -2004,7 +2015,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
   });
   const last = snapshots.at(-1);
   const snapped = me.snap?.(last);
-  cache().set(stream, {
+  cache2().set(stream, {
     state: last.state,
     version: last.event.version,
     event_id: last.event.id,
@@ -2199,6 +2210,7 @@ var Act = class {
     this.registry = registry;
     this._states = _states;
     this._batch_handlers = batchHandlers;
+    this._scoped = options.scoped ? (fn) => scoped.run(options.scoped, fn) : (fn) => fn();
     this._es = buildEs(this._logger);
     this._cd = buildDrain(this._logger);
     this._handle = buildHandle({
@@ -2244,14 +2256,8 @@ var Act = class {
       },
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
-    this._notify_disposer = this._wireNotify();
-    dispose(async () => {
-      this._emitter.removeAllListeners();
-      this.stop_correlations();
-      this.stop_settling();
-      const disposer = await this._notify_disposer;
-      if (disposer) await disposer();
-    });
+    this._notify_disposer = this._wireNotify(options.scoped?.store ?? store2());
+    dispose(() => this.shutdown());
   }
   _emitter = new import_node_events.default();
   /** Event names with at least one registered reaction (computed at build time) */
@@ -2313,6 +2319,11 @@ var Act = class {
   _event_to_state;
   /** Logger resolved at construction time (after user port configuration) */
   _logger = log();
+  /** Wraps a public-method body so internal `store()`/`cache()` resolve to the
+   * per-Act ports (ACT-501). No-op when the Act is unscoped — so the singleton
+   * path keeps reading fresh `store()`/`cache()` per call, which matters for
+   * tests that dispose and re-seed mid-suite. */
+  _scoped;
   /** Pre-bound IAct methods reused across drain cycles. Only `do` varies per
    * payload (it captures the triggering event for reactingTo auto-inject). */
   _bound_do = this.do.bind(this);
@@ -2322,15 +2333,38 @@ var Act = class {
   /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
   _handle;
   _handle_batch;
+  /** True after the first `shutdown()` call. Guards idempotency. */
+  _shutdown_promise;
+  /**
+   * Per-instance teardown: remove lifecycle listeners, stop the
+   * correlation worker, cancel any pending settle cycle, and tear
+   * down the cross-process notify subscription.
+   *
+   * Idempotent — repeated calls return the same promise. Registered
+   * automatically with the global `dispose()` registry at construction,
+   * so process-wide `dispose()()` covers it; test helpers (or operators
+   * that mint short-lived Acts) call it explicitly for prompt cleanup.
+   */
+  shutdown() {
+    if (!this._shutdown_promise) {
+      this._shutdown_promise = (async () => {
+        this._emitter.removeAllListeners();
+        this.stop_correlations();
+        this.stop_settling();
+        const disposer = await this._notify_disposer;
+        if (disposer) await disposer();
+      })();
+    }
+    return this._shutdown_promise;
+  }
   /**
    * Subscribe to {@link Store.notify} when both the store and the
    * registry support it. Returns the disposer (or `undefined` when no
    * subscription was made). Errors during subscription are logged but
    * never thrown — `notify` is a hint, not a contract.
    */
-  async _wireNotify() {
+  async _wireNotify(s) {
     if (this._reactive_events.size === 0) return void 0;
-    const s = store();
     if (!s.notify) return void 0;
     try {
       return await s.notify((notification) => {
@@ -2434,35 +2468,39 @@ var Act = class {
    * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
    */
   async do(action2, target, payload, reactingTo, skipValidation = false) {
-    const snapshots = await this._es.action(
-      this.registry.actions[action2],
-      action2,
-      target,
-      payload,
-      reactingTo,
-      skipValidation
-    );
-    if (this._reactive_events.size > 0) {
-      for (const snap2 of snapshots) {
-        if (snap2.event?.name && this._reactive_events.has(snap2.event.name)) {
-          this._drain.arm();
-          break;
+    return this._scoped(async () => {
+      const snapshots = await this._es.action(
+        this.registry.actions[action2],
+        action2,
+        target,
+        payload,
+        reactingTo,
+        skipValidation
+      );
+      if (this._reactive_events.size > 0) {
+        for (const snap2 of snapshots) {
+          if (snap2.event?.name && this._reactive_events.has(snap2.event.name)) {
+            this._drain.arm();
+            break;
+          }
         }
       }
-    }
-    this.emit("committed", snapshots);
-    return snapshots;
+      this.emit("committed", snapshots);
+      return snapshots;
+    });
   }
   async load(stateOrName, stream, callback, asOf) {
-    let merged;
-    if (typeof stateOrName === "string") {
-      const found = this._states.get(stateOrName);
-      if (!found) throw new Error(`State "${stateOrName}" not found`);
-      merged = found;
-    } else {
-      merged = this._states.get(stateOrName.name) || stateOrName;
-    }
-    return await this._es.load(merged, stream, callback, asOf);
+    return this._scoped(async () => {
+      let merged;
+      if (typeof stateOrName === "string") {
+        const found = this._states.get(stateOrName);
+        if (!found) throw new Error(`State "${stateOrName}" not found`);
+        merged = found;
+      } else {
+        merged = this._states.get(stateOrName.name) || stateOrName;
+      }
+      return await this._es.load(merged, stream, callback, asOf);
+    });
   }
   /**
    * Queries the event store for events matching a filter.
@@ -2511,14 +2549,16 @@ var Act = class {
    * @see {@link query_array} for loading events into memory
    */
   async query(query, callback) {
-    let first;
-    let last;
-    const count = await store().query((e) => {
-      if (!first) first = e;
-      last = e;
-      callback?.(e);
-    }, query);
-    return { first, last, count };
+    return this._scoped(async () => {
+      let first;
+      let last;
+      const count = await store2().query((e) => {
+        if (!first) first = e;
+        last = e;
+        callback?.(e);
+      }, query);
+      return { first, last, count };
+    });
   }
   /**
    * Queries the event store and returns all matching events in memory.
@@ -2547,9 +2587,11 @@ var Act = class {
    * @see {@link query} for large result sets
    */
   async query_array(query) {
-    const events = [];
-    await store().query((e) => events.push(e), query);
-    return events;
+    return this._scoped(async () => {
+      const events = [];
+      await store2().query((e) => events.push(e), query);
+      return events;
+    });
   }
   /**
    * Processes pending reactions by draining uncommitted events from the event store.
@@ -2589,7 +2631,7 @@ var Act = class {
    * @see {@link start_correlations} for automatic correlation
    */
   async drain(options = {}) {
-    return this._drain.drain(options);
+    return this._scoped(() => this._drain.drain(options));
   }
   /**
    * Discovers and registers new streams dynamically based on reaction resolvers.
@@ -2637,7 +2679,7 @@ var Act = class {
    * @see {@link stop_correlations} to stop automatic correlation
    */
   async correlate(query = { after: -1, limit: 10 }) {
-    return this._correlate.correlate(query);
+    return this._scoped(() => this._correlate.correlate(query));
   }
   /**
    * Starts automatic periodic correlation worker for discovering new streams.
@@ -2758,9 +2800,11 @@ var Act = class {
    * @see {@link settle} for the debounced full-catch-up loop
    */
   async reset(streams) {
-    const count = await store().reset(streams);
-    if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
-    return count;
+    return this._scoped(async () => {
+      const count = await store2().reset(streams);
+      if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
+      return count;
+    });
   }
   /**
    * Bulk-update scheduling priority for streams matching `filter`.
@@ -2801,7 +2845,7 @@ var Act = class {
    * @see {@link claim} for how priority biases scheduling
    */
   async prioritize(filter, priority) {
-    return store().prioritize(filter, priority);
+    return this._scoped(() => store2().prioritize(filter, priority));
   }
   /**
    * Close the books — guard, archive, truncate, and optionally restart streams.
@@ -2838,16 +2882,18 @@ var Act = class {
    */
   async close(targets) {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
-    await this.correlate({ limit: 1e3 });
-    const result = await runCloseCycle(targets, {
-      reactiveEventsSize: this._reactive_events.size,
-      eventToState: this._event_to_state,
-      load: this._es.load,
-      tombstone: this._es.tombstone,
-      logger: this._logger
+    return this._scoped(async () => {
+      await this.correlate({ limit: 1e3 });
+      const result = await runCloseCycle(targets, {
+        reactiveEventsSize: this._reactive_events.size,
+        eventToState: this._event_to_state,
+        load: this._es.load,
+        tombstone: this._es.tombstone,
+        logger: this._logger
+      });
+      this.emit("closed", result);
+      return result;
     });
-    this.emit("closed", result);
-    return result;
   }
   /**
    * Debounced, non-blocking correlate→drain cycle.
@@ -2901,6 +2947,41 @@ function act() {
   };
   const pendingProjections = [];
   const batchHandlers = /* @__PURE__ */ new Map();
+  let _built = false;
+  const finalizeDeprecations = () => {
+    const deprecationSummary = [];
+    for (const state2 of states.values()) {
+      const eventNames = Object.keys(state2.events);
+      const deprecated = deprecatedEventNames(eventNames);
+      if (deprecated.size === 0) continue;
+      state2._deprecated = deprecated;
+      for (const name of deprecated) {
+        const current = currentVersionOf(name, eventNames);
+        deprecationSummary.push({
+          stateName: state2.name,
+          deprecated: name,
+          current
+        });
+      }
+      for (const [actionName, handler] of Object.entries(state2.on)) {
+        const staticTarget = handler?._staticEmit;
+        if (staticTarget && deprecated.has(staticTarget)) {
+          const current = currentVersionOf(staticTarget, eventNames);
+          throw new Error(
+            `Action "${actionName}" in state "${state2.name}" emits deprecated event "${staticTarget}". A newer version exists: "${current}". Update the .emit() call to target the current version. The reducer (.patch) for "${staticTarget}" stays as-is \u2014 historical events still need it.`
+          );
+        }
+      }
+    }
+    if (deprecationSummary.length > 0) {
+      const list = deprecationSummary.map(
+        (d) => `"${d.deprecated}" (current: "${d.current}", state: "${d.stateName}")`
+      ).join(", ");
+      log().info(
+        `Act registered ${deprecationSummary.length} deprecated event(s): ${list}. These are legacy versions kept for the read path. Consider truncating closed streams via app.close() when feasible to reduce historical event load. See docs/docs/architecture/event-schema-evolution.md.`
+      );
+    }
+  };
   const builder = {
     withState: (state2) => {
       registerState(state2, states, registry.actions, registry.events);
@@ -2944,41 +3025,13 @@ function act() {
       }
     }),
     build: (options) => {
-      for (const proj of pendingProjections) {
-        mergeProjection(proj, registry.events);
-        registerBatchHandler(proj, batchHandlers);
-      }
-      const deprecationSummary = [];
-      for (const state2 of states.values()) {
-        const eventNames = Object.keys(state2.events);
-        const deprecated = deprecatedEventNames(eventNames);
-        if (deprecated.size === 0) continue;
-        state2._deprecated = deprecated;
-        for (const name of deprecated) {
-          const current = currentVersionOf(name, eventNames);
-          deprecationSummary.push({
-            stateName: state2.name,
-            deprecated: name,
-            current
-          });
+      if (!_built) {
+        for (const proj of pendingProjections) {
+          mergeProjection(proj, registry.events);
+          registerBatchHandler(proj, batchHandlers);
         }
-        for (const [actionName, handler] of Object.entries(state2.on)) {
-          const staticTarget = handler?._staticEmit;
-          if (staticTarget && deprecated.has(staticTarget)) {
-            const current = currentVersionOf(staticTarget, eventNames);
-            throw new Error(
-              `Action "${actionName}" in state "${state2.name}" emits deprecated event "${staticTarget}". A newer version exists: "${current}". Update the .emit() call to target the current version. The reducer (.patch) for "${staticTarget}" stays as-is \u2014 historical events still need it.`
-            );
-          }
-        }
-      }
-      if (deprecationSummary.length > 0) {
-        const list = deprecationSummary.map(
-          (d) => `"${d.deprecated}" (current: "${d.current}", state: "${d.stateName}")`
-        ).join(", ");
-        log().info(
-          `Act registered ${deprecationSummary.length} deprecated event(s): ${list}. These are legacy versions kept for the read path. Consider truncating closed streams via app.close() when feasible to reduce historical event load. See docs/docs/architecture/event-schema-evolution.md.`
-        );
+        finalizeDeprecations();
+        _built = true;
       }
       return new Act(
         registry,
@@ -3222,6 +3275,7 @@ function action_builder(state2) {
   log,
   port,
   projection,
+  scoped,
   sleep,
   slice,
   state,