@rotorsoft/act 1.22.8 → 1.23.0

package/dist/index.js

@@ -1396,6 +1396,7 @@ async function truncate_and_warm_cache(guarded, seed_states, guard_events, corre
 }
 
 // src/internal/correlate-cycle.ts
+var DEFAULT_COLD_START_BACK_SCAN = 1e4;
 var CorrelateCycle = class {
   _checkpoint = -1;
   _initialized = false;
@@ -1424,8 +1425,24 @@ var CorrelateCycle = class {
    * `_scoped` (identity for a non-scoped Act), so it's required.
    */
   _run_scoped;
-  constructor(registry, static_targets, has_dynamic_resolvers, cd, maxSubscribedStreams, on_init, run_scoped, on_init_async) {
-    this._subscribed = new LruSet(maxSubscribedStreams);
+  /**
+   * Tail re-scan window applied to the cold-start checkpoint (ACT-1207).
+   * See {@link DEFAULT_COLD_START_BACK_SCAN}. Constructor arg (not a
+   * public option) so tests can shrink it; defaults otherwise.
+   */
+  _cold_start_back_scan;
+  constructor({
+    registry,
+    static_targets,
+    has_dynamic_resolvers,
+    cd,
+    max_subscribed_streams,
+    run_scoped,
+    on_init,
+    on_init_async,
+    cold_start_back_scan = DEFAULT_COLD_START_BACK_SCAN
+  }) {
+    this._subscribed = new LruSet(max_subscribed_streams);
     this._registry = registry;
     this._static_targets = static_targets;
     this._has_dynamic_resolvers = has_dynamic_resolvers;
@@ -1433,6 +1450,7 @@ var CorrelateCycle = class {
     this._on_init = on_init;
     this._run_scoped = run_scoped;
     this._on_init_async = on_init_async;
+    this._cold_start_back_scan = cold_start_back_scan;
   }
   /** Last correlated event id. */
   get checkpoint() {
@@ -1440,7 +1458,10 @@ var CorrelateCycle = class {
   }
   /**
    * Initialize correlation state on first call.
-   * - Reads max(at) from store as cold-start checkpoint
+   * - Reads max(at) from store, then floors the cold-start checkpoint at
+   *   `watermark - back_scan` when dynamic resolvers exist, so an event
+   *   committed-but-not-correlated before a crash is re-scanned on
+   *   restart instead of skipped (ACT-1207)
    * - Subscribes static resolver targets (idempotent upsert)
    * - Populates the subscribed-streams LRU
    * - Fires `on_init` once (Act uses this to flag a cold-start drain)
@@ -1449,7 +1470,7 @@ var CorrelateCycle = class {
     if (this._initialized) return;
     this._initialized = true;
     const { watermark } = await store().subscribe([...this._static_targets]);
-    this._checkpoint = watermark;
+    this._checkpoint = this._has_dynamic_resolvers ? Math.max(-1, watermark - this._cold_start_back_scan) : watermark;
     this._on_init?.();
     for (const { stream } of this._static_targets) {
       this._subscribed.add(stream);
@@ -1715,6 +1736,15 @@ function compute_backoff_delay(retry, opts) {
 }
 
 // src/internal/event-sourcing.ts
+var bare_patch = (_me, state2, partial) => patch(state2, partial);
+var validating_patch = (me, state2, partial, event) => {
+  const next = patch(state2, partial);
+  return validate(
+    `${me.name}.${String(event.name)}#${event.id}`,
+    next,
+    me.state
+  );
+};
 var DEFAULT_BATCH = 500;
 async function snap(snapshot) {
   const { id, stream, name, meta, version } = snapshot.event;
@@ -1869,7 +1899,7 @@ async function scan(source, opts = {}, callback) {
     }
   };
 }
-async function load(me, target, callback) {
+async function load(me, target, callback, patch_fn = bare_patch) {
   const { stream, actor, asOf } = target;
   const time_travel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
   const cached = time_travel ? void 0 : await cache().get(stream);
@@ -1888,7 +1918,7 @@ async function load(me, target, callback) {
         patches = 0;
         replayed++;
       } else if (me.patch[event.name]) {
-        state2 = patch(state2, me.patch[event.name](event, state2));
+        state2 = patch_fn(me, state2, me.patch[event.name](event, state2), event);
         patches++;
         replayed++;
       } else if (event.name !== TOMBSTONE_EVENT) {
@@ -1900,6 +1930,7 @@ async function load(me, target, callback) {
         event,
         state: state2,
         version: event.version,
+        id: event.id,
         patches,
         snaps,
         cache_hit,
@@ -1921,19 +1952,24 @@ async function load(me, target, callback) {
       event_id: event.id,
       patches,
       snaps
-    });
+    }).catch((err) => log().error(err));
   }
   return {
     event,
     state: state2,
     version: event?.version ?? cached?.version ?? -1,
+    // Head event id, captured atomically with `state`: the last replayed
+    // event's id on a cache miss, or the cached checkpoint's event_id on a
+    // warm hit with no new events. Consumers read this instead of a
+    // separate cache lookup that could race a concurrent commit (ACT-1204).
+    id: event?.id ?? cached?.event_id ?? -1,
     patches,
     snaps,
     cache_hit,
     replayed
   };
 }
-async function action(me, action2, target, payload, options) {
+async function action(me, action2, target, payload, options, patch_fn = bare_patch) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
   const reactingTo = options?.reactingTo;
@@ -1943,7 +1979,12 @@ async function action(me, action2, target, payload, options) {
   const max_retries = opts?.maxRetries ?? 0;
   for (let attempt = 0; ; attempt++) {
     try {
-      const snapshot = await load(me, { stream, actor: target.actor });
+      const snapshot = await load(
+        me,
+        { stream, actor: target.actor },
+        void 0,
+        patch_fn
+      );
       if (snapshot.event?.name === TOMBSTONE_EVENT)
         throw new StreamClosedError(stream);
       const expected = expectedVersion ?? (snapshot.version >= 0 ? snapshot.version : void 0);
@@ -2014,12 +2055,13 @@ async function action(me, action2, target, payload, options) {
       const snapshots = committed.map((row, i) => {
         const event = { ...row, data: valid[i].data };
         const p = me.patch[event.name](event, state2);
-        state2 = patch(state2, p);
+        state2 = patch_fn(me, state2, p, event);
         patches++;
         return {
           event,
           state: state2,
           version: event.version,
+          id: event.id,
           patches,
           snaps: snapshot.snaps,
           patch: p,
@@ -2047,6 +2089,7 @@ async function action(me, action2, target, payload, options) {
       return snapshots;
     } catch (error) {
       if (!(error instanceof ConcurrencyError)) throw error;
+      if (expectedVersion !== void 0) throw error;
       if (attempt >= max_retries) throw error;
       if (opts?.backoff) {
         const delay_ms = compute_backoff_delay(attempt, opts.backoff);
@@ -2108,12 +2151,20 @@ var traced = (inner, exit, entry) => (async (...args) => {
   exit?.(result, ...args);
   return result;
 });
-function build_es(logger, correlator = default_correlator) {
-  const bound_action = (me, action_name, target, payload, options) => action(me, action_name, target, payload, { correlator, ...options });
+function build_es(logger, correlator = default_correlator, patch_fn = bare_patch) {
+  const bound_action = (me, action_name, target, payload, options) => action(
+    me,
+    action_name,
+    target,
+    payload,
+    { correlator, ...options },
+    patch_fn
+  );
+  const bound_load = (me, target, callback) => load(me, target, callback, patch_fn);
   if (logger.level !== "trace") {
     return {
       snap,
-      load,
+      load: bound_load,
       action: bound_action,
       tombstone
     };
@@ -2128,7 +2179,7 @@ function build_es(logger, correlator = default_correlator) {
         )
       );
     }),
-    load: traced(load, (result, _me, target) => {
+    load: traced(bound_load, (result, _me, target) => {
       const stats = stats_marker(
         result.version,
         result.replayed,
@@ -2439,6 +2490,83 @@ var DrainController = class {
   }
 };
 
+// src/internal/projection-fold.ts
+import { z as z5 } from "zod";
+var DEFAULT_FOLD_FLUSH_EVERY = 1e3;
+var DEFAULT_MAX_CACHED_STATES = 1e4;
+var FoldOptionsSchema = z5.object({
+  flushEvery: z5.number().int().min(1).default(DEFAULT_FOLD_FLUSH_EVERY),
+  maxCachedStates: z5.number().int().min(1).default(DEFAULT_MAX_CACHED_STATES)
+});
+function resolveFoldConfig(options) {
+  return FoldOptionsSchema.parse(options);
+}
+function make_fold_handler(me, flush, config2, patch_fn = bare_patch) {
+  const cache2 = /* @__PURE__ */ new Map();
+  const row = ({ dirty: _, ...row2 }) => row2;
+  const flush_dirty = async () => {
+    const rows = [];
+    const flushed = [];
+    for (const f of cache2.values())
+      if (f.dirty) {
+        rows.push(row(f));
+        flushed.push(f);
+      }
+    if (rows.length === 0) return;
+    await flush(rows);
+    for (const f of flushed) f.dirty = false;
+  };
+  return async (events) => {
+    let folded_since_flush = 0;
+    for (const event of events) {
+      const stream = event.stream;
+      let fold = cache2.get(stream);
+      if (fold) {
+        cache2.delete(stream);
+        cache2.set(stream, fold);
+      } else {
+        if (cache2.size >= config2.maxCachedStates) {
+          const oldest = cache2.keys().next().value;
+          const evictee = cache2.get(oldest);
+          if (evictee.dirty) await flush([row(evictee)]);
+          cache2.delete(oldest);
+        }
+        const snapshot = await load(me, { stream }, void 0, patch_fn);
+        fold = {
+          stream,
+          state: snapshot.state,
+          version: snapshot.version,
+          event_id: snapshot.id,
+          patches: snapshot.patches,
+          snaps: snapshot.snaps,
+          dirty: true
+        };
+        cache2.set(stream, fold);
+      }
+      if (event.id > fold.event_id) {
+        const reducer = me.patch[event.name];
+        fold.state = patch_fn(
+          me,
+          fold.state,
+          reducer(event, fold.state),
+          event
+        );
+        fold.version = event.version;
+        fold.event_id = event.id;
+        fold.patches++;
+        fold.dirty = true;
+      } else {
+        fold.dirty = true;
+      }
+      if (++folded_since_flush >= config2.flushEvery) {
+        await flush_dirty();
+        folded_since_flush = 0;
+      }
+    }
+    await flush_dirty();
+  };
+}
+
 // src/internal/reactions.ts
 function finalize(lease, handled, at, error, options, logger, failed_at) {
   if (!error) return { lease, handled, acked_at: at };
@@ -2569,6 +2697,16 @@ function build_handle_batch(logger) {
 var SettleLoop = class {
   _timer = void 0;
   _running = false;
+  /**
+   * Set when a `schedule()` timer fires while a cycle is still running
+   * (ACT-1205). The in-flight cycle's `finally` re-arms one more pass so
+   * the wake-up isn't dropped — a commit landing during the final
+   * no-progress drain pass would otherwise leave armed controllers with
+   * nothing to re-drain on an instance with no lane `cycleMs` and no
+   * polling. Carries the options of the dropped call so the re-armed
+   * pass honors its `debounceMs`/`maxPasses`/drain overrides.
+   */
+  _pending = void 0;
   _deps;
   /** Debounce window applied when the caller doesn't override via `SettleOptions.debounceMs`. */
   _default_debounce_ms;
@@ -2593,7 +2731,10 @@ var SettleLoop = class {
     if (this._timer) clearTimeout(this._timer);
     this._timer = setTimeout(() => {
       this._timer = void 0;
-      if (this._running) return;
+      if (this._running) {
+        this._pending = options;
+        return;
+      }
       this._running = true;
       (async () => {
         await this._deps.init();
@@ -2613,11 +2754,17 @@ var SettleLoop = class {
         this._deps.breaker.failed(Date.now(), err);
       }).finally(() => {
         this._running = false;
+        const pending = this._pending;
+        if (pending !== void 0) {
+          this._pending = void 0;
+          this.schedule(pending);
+        }
       });
     }, debounceMs);
   }
   /** Cancel any pending or active settle cycle. Idempotent. */
   stop() {
+    this._pending = void 0;
     if (this._timer) {
       clearTimeout(this._timer);
       this._timer = void 0;
@@ -2625,89 +2772,6 @@ var SettleLoop = class {
   }
 };
 
-// src/internal/state-fold.ts
-import { patch as patch2 } from "@rotorsoft/act-patch";
-import { z as z5 } from "zod";
-var DEFAULT_FOLD_FLUSH_EVERY = 1e3;
-var DEFAULT_MAX_CACHED_STATES = 1e4;
-var FoldOptionsSchema = z5.object({
-  flushEvery: z5.number().int().min(1).default(DEFAULT_FOLD_FLUSH_EVERY),
-  maxCachedStates: z5.number().int().min(1).default(DEFAULT_MAX_CACHED_STATES)
-});
-function resolveFoldConfig(options) {
-  return FoldOptionsSchema.parse(options);
-}
-function make_fold_handler(me, flush, config2) {
-  const cache2 = /* @__PURE__ */ new Map();
-  const row = ({ dirty: _, ...row2 }) => row2;
-  const flush_dirty = async () => {
-    const rows = [];
-    const flushed = [];
-    for (const f of cache2.values())
-      if (f.dirty) {
-        rows.push(row(f));
-        flushed.push(f);
-      }
-    if (rows.length === 0) return;
-    await flush(rows);
-    for (const f of flushed) f.dirty = false;
-  };
-  return async (events) => {
-    let folded_since_flush = 0;
-    for (const event of events) {
-      const stream = event.stream;
-      let fold = cache2.get(stream);
-      if (fold) {
-        cache2.delete(stream);
-        cache2.set(stream, fold);
-      } else {
-        if (cache2.size >= config2.maxCachedStates) {
-          const oldest = cache2.keys().next().value;
-          const evictee = cache2.get(oldest);
-          if (evictee.dirty) await flush([row(evictee)]);
-          cache2.delete(oldest);
-        }
-        const snapshot = await load(me, { stream });
-        const entry = await cache().get(stream);
-        const frontier = entry ?? {
-          version: snapshot.event.version,
-          event_id: snapshot.event.id,
-          patches: snapshot.patches,
-          snaps: snapshot.snaps
-        };
-        fold = {
-          stream,
-          state: snapshot.state,
-          version: frontier.version,
-          event_id: frontier.event_id,
-          patches: frontier.patches,
-          snaps: frontier.snaps,
-          dirty: true
-        };
-        cache2.set(stream, fold);
-      }
-      if (event.id > fold.event_id) {
-        const reducer = me.patch[event.name];
-        fold.state = patch2(
-          fold.state,
-          reducer(event, fold.state)
-        );
-        fold.version = event.version;
-        fold.event_id = event.id;
-        fold.patches++;
-        fold.dirty = true;
-      } else {
-        fold.dirty = true;
-      }
-      if (++folded_since_flush >= config2.flushEvery) {
-        await flush_dirty();
-        folded_since_flush = 0;
-      }
-    }
-    await flush_dirty();
-  };
-}
-
 // src/act.ts
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
@@ -2864,8 +2928,14 @@ var Act = class {
    * @param lanes     Declared drain lanes (ACT-1103). The builder collects
    *   these from `.withLane(...)` calls. Slice 1 records them on the
    *   instance; later slices fan out one `DrainController` per lane.
+   * @param patch_fn  The per-event patch step selected once by the builder
+   *   from `ActOptions.validateFoldedState` (ACT-1238) — `bare_patch` by
+   *   default, `validating_patch` when the flag is on. The builder uses
+   *   the same value for its projection-fold handlers, so there is a
+   *   single selection site. Defaults to `bare_patch` for direct
+   *   construction.
    */
-  constructor(registry, states = /* @__PURE__ */ new Map(), batch_handlers = /* @__PURE__ */ new Map(), options = {}, lanes = []) {
+  constructor(registry, states = /* @__PURE__ */ new Map(), batch_handlers = /* @__PURE__ */ new Map(), options = {}, lanes = [], patch_fn = bare_patch) {
     this.registry = registry;
     this._states = states;
     this._batch_handlers = batch_handlers;
@@ -2873,7 +2943,7 @@ var Act = class {
     validate_only_lanes(options, lanes);
     this._scoped = options.scoped ? (fn) => scoped.run(options.scoped, fn) : (fn) => fn();
     this._correlator = options.correlator ?? default_correlator;
-    this._es = build_es(this._logger, this._correlator);
+    this._es = build_es(this._logger, this._correlator, patch_fn);
     this._cd = build_drain(this._logger);
     this._handle = build_handle({
       logger: this._logger,
@@ -3040,22 +3110,22 @@ var Act = class {
    * except on writer-only instances (`drain: false`).
    */
   _build_correlate(options, classification) {
-    return new CorrelateCycle(
-      this.registry,
-      classification.static_targets,
-      classification.has_dynamic_resolvers,
-      this._cd,
-      options.maxSubscribedStreams ?? DEFAULT_MAX_SUBSCRIBED_STREAMS,
-      () => {
+    return new CorrelateCycle({
+      registry: this.registry,
+      static_targets: classification.static_targets,
+      has_dynamic_resolvers: classification.has_dynamic_resolvers,
+      cd: this._cd,
+      max_subscribed_streams: options.maxSubscribedStreams ?? DEFAULT_MAX_SUBSCRIBED_STREAMS,
+      on_init: () => {
         if (this._drain && this._reactive_events.size > 0) this._arm_all();
       },
       // Re-scope the background `start_correlations` timer so its
       // correlate resolves the scoped ports, not the singleton (#1191).
-      this._scoped,
+      run_scoped: this._scoped,
       // Cold-start defer re-seed (#1221). Skipped on writer-only instances
       // (`drain: false`) — they run no local controllers to re-arm.
-      this._drain ? () => this._seed_persisted_defers() : void 0
-    );
+      on_init_async: this._drain ? () => this._seed_persisted_defers() : void 0
+    });
   }
   /**
    * Re-seed every active lane controller's process-local defer timer from
@@ -4114,6 +4184,7 @@ function act() {
     },
     on: (event) => reaction_on(event, registry.events, builder),
     build: (options) => {
+      const patch_fn = options?.validateFoldedState === true ? validating_patch : bare_patch;
       if (!_built) {
         for (const proj of pending_projections) {
           merge_projection(proj, registry.events);
@@ -4136,7 +4207,7 @@ function act() {
             );
           batch_handlers.set(
             proj.target,
-            make_fold_handler(merged, fold.flush, fold.config)
+            make_fold_handler(merged, fold.flush, fold.config, patch_fn)
           );
         }
         finalize_deprecations();
@@ -4209,7 +4280,8 @@ function act() {
         states,
         batch_handlers,
         options,
-        lanes
+        lanes,
+        patch_fn
       );
     },
     events: registry.events