@rotorsoft/act 0.36.0 → 0.38.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];
@@ -1485,6 +1496,43 @@ 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) {
@@ -1763,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
@@ -1777,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");
@@ -1787,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 }],
       {
@@ -1803,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: {} },
@@ -1817,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;
@@ -1825,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;
@@ -1860,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,
@@ -1897,6 +1945,20 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     return [snapshot];
   }
   const tuples = Array.isArray(result[0]) ? result : [result];
+  const deprecated = me._deprecated;
+  if (deprecated && deprecated.size > 0) {
+    const me_ = me;
+    const warned = me_._warned ?? (me_._warned = /* @__PURE__ */ new Set());
+    for (const [name] of tuples) {
+      const evt = name;
+      if (deprecated.has(evt) && !warned.has(evt)) {
+        warned.add(evt);
+        log().warn(
+          `Action "${String(action2)}" emitted deprecated event "${evt}". A newer version exists in the registry \u2014 update the action's .emit() to target the current version. (warned once per process)`
+        );
+      }
+    }
+  }
   const emitted = tuples.map(([name, data]) => ({
     name,
     data: skipValidation ? data : validate(name, data, me.events[name])
@@ -1919,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,
@@ -1931,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;
   }
@@ -1953,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,
@@ -2148,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({
@@ -2193,7 +2256,7 @@ var Act = class {
       },
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
-    this._notify_disposer = this._wireNotify();
+    this._notify_disposer = this._wireNotify(options.scoped?.store ?? store2());
     dispose(async () => {
       this._emitter.removeAllListeners();
       this.stop_correlations();
@@ -2262,6 +2325,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);
@@ -2277,9 +2345,8 @@ var Act = class {
    * 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) => {
@@ -2383,35 +2450,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.
@@ -2460,14 +2531,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.
@@ -2496,9 +2569,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.
@@ -2538,7 +2613,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.
@@ -2586,7 +2661,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.
@@ -2707,9 +2782,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`.
@@ -2750,7 +2827,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.
@@ -2787,16 +2864,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.
@@ -2850,6 +2929,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);
@@ -2893,9 +3007,13 @@ function act() {
       }
     }),
     build: (options) => {
-      for (const proj of pendingProjections) {
-        mergeProjection(proj, registry.events);
-        registerBatchHandler(proj, batchHandlers);
+      if (!_built) {
+        for (const proj of pendingProjections) {
+          mergeProjection(proj, registry.events);
+          registerBatchHandler(proj, batchHandlers);
+        }
+        finalizeDeprecations();
+        _built = true;
       }
       return new Act(
         registry,
@@ -3083,10 +3201,10 @@ function action_builder(state2) {
       function emit(handler) {
         if (typeof handler === "string") {
           const eventName = handler;
-          internal.on[action2] = (payload) => [
-            eventName,
-            payload
-          ];
+          const emitFn = Object.assign((payload) => [eventName, payload], {
+            _staticEmit: eventName
+          });
+          internal.on[action2] = emitFn;
         } else {
           internal.on[action2] = handler;
         }
@@ -3139,6 +3257,7 @@ function action_builder(state2) {
   log,
   port,
   projection,
+  scoped,
   sleep,
   slice,
   state,