@rotorsoft/act 0.36.0 → 0.37.0

package/dist/@types/internal/event-versions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module event-versions
+ * @category Internal
+ *
+ * Auto-deprecation of legacy event versions via the `_v<digits>` naming
+ * convention (ACT-403).
+ *
+ * Act's schema-evolution pattern keeps the old and new event names alive
+ * forever — the old name on the read path (reducers), the new on the write
+ * path (emissions). This module reads the convention to identify legacy
+ * versions automatically; the framework then enforces "emit only the
+ * current version" at build time and warns at runtime for dynamic emits.
+ *
+ * Convention pin: only `_v<digits>` with digits ≥ 2 counts as a version
+ * suffix. `Foo_v1` is just a literal event name (the base `Foo` is
+ * implicitly v1). Pinning here keeps the contract surface small.
+ *
+ * @internal
+ */
+/**
+ * Returns the set of event names that are deprecated by virtue of having
+ * a higher-numbered sibling in the registry. The highest version in each
+ * group is the current version; every lower version is deprecated.
+ *
+ * Gaps are allowed: `{Foo, Foo_v3}` → `Foo` is deprecated, `Foo_v3` is
+ * current. The framework picks the max regardless of contiguity.
+ *
+ * Single-version groups (no siblings) yield no deprecations.
+ *
+ * @internal
+ */
+export declare function deprecatedEventNames(names: Iterable<string>): Set<string>;
+/**
+ * Given a deprecated event name and the full set of event names in its
+ * registry, returns the current (highest-version) sibling. Used to build
+ * actionable error messages — "use `Foo_v3` instead."
+ *
+ * Returns `undefined` if the event has no higher-versioned sibling (which
+ * means the caller's classification is stale or wrong).
+ *
+ * @internal
+ */
+export declare function currentVersionOf(deprecatedName: string, allNames: Iterable<string>): string | undefined;
+//# sourceMappingURL=event-versions.d.ts.map

package/dist/@types/internal/event-versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-versions.d.ts","sourceRoot":"","sources":["../../../src/internal/event-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmBH;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAgBzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GACzB,MAAM,GAAG,SAAS,CASpB"}

package/dist/@types/internal/index.d.ts

@@ -22,6 +22,7 @@ export { CorrelateCycle } from "./correlate-cycle.js";
 export type { DrainOps } from "./drain.js";
 export { DrainController, type Handle, type HandleBatch, } from "./drain-cycle.js";
 export type { EsOps } from "./event-sourcing.js";
+export { currentVersionOf, deprecatedEventNames, } from "./event-versions.js";
 export { _this_, mergeEventRegister, mergeProjection, registerState, } from "./merge.js";
 export { buildHandle, buildHandleBatch } from "./reactions.js";
 export { SettleLoop } from "./settle.js";

package/dist/@types/internal/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EACL,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.cjs

@@ -1485,6 +1485,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) {
@@ -1897,6 +1934,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])
@@ -2897,6 +2948,38 @@ function act() {
         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
+          });
+        }
+        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.`
+        );
+      }
       return new Act(
         registry,
         states,
@@ -3083,10 +3166,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;
         }