@rotorsoft/act 1.34.3 → 1.35.0

package/dist/index.js

@@ -40,7 +40,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-IEM2NS6J.js";
+} from "./chunk-MHPUVTMX.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -57,6 +57,7 @@ import {
   InvariantError,
   LogLevels,
   NonRetryableError,
+  PreconditionError,
   QuerySchema,
   REDACTED,
   SHREDDED,
@@ -70,7 +71,7 @@ import {
   pii_fields,
   pii_schemas,
   sensitive
-} from "./chunk-BKCNU6FF.js";
+} from "./chunk-DH2HW5XJ.js";
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -1265,9 +1266,9 @@ var CorrelateCycle = class {
     return pattern.test(stream);
   }
   /** Scan past the checkpoint, subscribe new targets and raise their work marks. */
-  async correlate(query, lease = false) {
+  async correlate(limit, lease = false) {
     if (this._restoring) return { kind: "idle", last_id: this._checkpoint };
-    const pass = this._scan(query, lease);
+    const pass = this._scan(limit, lease);
     this._passes.add(pass);
     try {
       return await pass;
@@ -1275,7 +1276,7 @@ var CorrelateCycle = class {
       this._passes.delete(pass);
     }
   }
-  async _scan(query, lease) {
+  async _scan(limit, lease) {
     await this._init();
     const epoch = this._epoch;
     const idle = () => ({
@@ -1370,7 +1371,7 @@ var CorrelateCycle = class {
       },
       // Resolvers see `pii: null`: correlate runs actor-less, and one
       // undecryptable row would otherwise stop every stream's reactions.
-      { after, limit: query.limit, with_pii: false }
+      { after, limit, with_pii: false }
     );
     if (this._declared_lanes.size > 1) await this._recall(correlated);
     const read = last_id > after;
@@ -1409,7 +1410,7 @@ var CorrelateCycle = class {
       return { kind: "scanned", last_id, subscribed, marked, read };
     }
     this._checkpoint = last_id;
-    if (!stopped && found !== query.limit) this._lowered = raised;
+    if (!stopped && found !== limit) this._lowered = raised;
     return { kind: "scanned", last_id, subscribed: 0, marked: 0, read };
   }
   /**
@@ -1647,14 +1648,12 @@ var subscribe = (streams, correlated_at, correlator) => store().subscribe(stream
 
 // src/internal/event-sourcing.ts
 import { patch } from "@rotorsoft/act-patch";
+import { prettifyError } from "zod";
 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 check_invariants = (target, state2, schema) => {
+  const result = schema.safeParse(state2);
+  if (!result.success)
+    throw new ValidationError(target, state2, prettifyError(result.error));
 };
 var DEFAULT_BATCH = 500;
 var cache_put = (stream, entry) => cache().set(stream, entry).catch(
@@ -1911,8 +1910,8 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
       if (snapshot.event?.name === TOMBSTONE_EVENT)
         throw new StreamClosedError(stream);
       const expected = expectedVersion ?? (snapshot.version >= 0 ? snapshot.version : void 0);
-      for (const { valid: valid2, description } of me.given?.[action2] ?? [])
-        if (!valid2(snapshot.state, actor))
+      for (const { valid, description } of me.given?.[action2] ?? [])
+        if (!valid(snapshot.state, actor))
           throw new InvariantError(
             action2,
             validated,
@@ -1922,25 +1921,22 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
           );
       for (const { holds, description } of me.requires?.[action2] ?? [])
         if (!holds(validated, snapshot.state, actor))
-          throw new InvariantError(
+          throw new PreconditionError(
             action2,
             validated,
             target,
             snapshot,
-            description,
-            "precondition"
+            description
           );
       const result = me.on[action2](validated, snapshot, target);
-      if (!result) return [snapshot];
-      if (Array.isArray(result) && result.length === 0) {
+      if (!result || Array.isArray(result) && !result.length)
         return [snapshot];
-      }
       const tuples = Array.isArray(result[0]) ? result : [result];
-      const valid = tuples.map(([name, data]) => ({
+      const events = tuples.map(([name, data]) => ({
         name,
         data: validate(name, data, me.events[name])
       }));
-      const emitted = valid.map((e) => me.message(e));
+      const emitted = events.map((e) => me.message(e));
       const meta = {
         correlation: reactingTo?.meta.correlation || correlator({
           action: action2,
@@ -1961,6 +1957,23 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
           } : void 0
         }
       };
+      let { state: state2, patches } = snapshot;
+      const created = /* @__PURE__ */ new Date();
+      const folded = events.map((e, i) => {
+        const event = {
+          ...e,
+          id: -1,
+          stream,
+          version: snapshot.version + i + 1,
+          created,
+          meta
+        };
+        const patch2 = me.patch[event.name](event, state2);
+        state2 = patch_fn(me, state2, patch2, event);
+        patches++;
+        return { state: state2, patch: patch2, patches };
+      });
+      check_invariants(`${me.name}.${action2}`, state2, me.state);
       let committed;
       try {
         committed = await store().commit(
@@ -1975,24 +1988,17 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
         if (error instanceof ConcurrencyError) void cache_drop(stream);
         throw error;
       }
-      let { state: state2, patches } = snapshot;
-      const snapshots = committed.map((row, i) => {
-        const event = { ...row, data: valid[i].data };
-        const p = me.patch[event.name](event, state2);
-        state2 = patch_fn(me, state2, p, event);
-        patches++;
-        return {
-          event,
-          state: state2,
-          version: event.version,
-          id: event.id,
-          patches,
-          snaps: snapshot.snaps,
-          patch: p,
-          cache_hit: snapshot.cache_hit,
-          replayed: snapshot.replayed
-        };
-      });
+      const snapshots = committed.map((row, i) => ({
+        event: { ...row, data: events[i].data },
+        state: folded[i].state,
+        version: row.version,
+        id: row.id,
+        patches: folded[i].patches,
+        snaps: snapshot.snaps,
+        patch: folded[i].patch,
+        cache_hit: snapshot.cache_hit,
+        replayed: snapshot.replayed
+      }));
       const last = snapshots.at(-1);
       const contiguous = committed[0].version === snapshot.version + 1;
       const snapped = contiguous && me.snap?.(last);
@@ -2569,7 +2575,7 @@ function pii_strip(event, fields) {
 
 // src/internal/projection-fold.ts
 var FOLD_RESET = /* @__PURE__ */ Symbol("act.fold.reset");
-function make_fold_handler(me, flush, config2, patch_fn = bare_patch, sensitive_fields) {
+function make_fold_handler(me, flush, config2, patch_fn, sensitive_fields) {
   const load_me = {
     ...me,
     view: (raw, actor) => {
@@ -2933,10 +2939,8 @@ var SettleLoop = class {
 };
 
 // src/act.ts
-function validate_only_lanes(options, lanes) {
-  if (!options.onlyLanes || options.onlyLanes.length === 0) return;
-  const declared = /* @__PURE__ */ new Set(["default", ...lanes.map((l) => l.name)]);
-  const unknown = options.onlyLanes.filter((l) => !declared.has(l));
+function validate_only_lanes(only, declared) {
+  const unknown = (only ?? []).filter((l) => !declared.includes(l));
   if (unknown.length > 0)
     throw new Error(
       `ActOptions.onlyLanes references undeclared lane(s): ${unknown.map((l) => `"${l}"`).join(", ")}`
@@ -3040,7 +3044,7 @@ var Act = class {
     this._batch_handlers = batch_handlers;
     this._lanes = lanes;
     this._declared_lanes = ["default", ...lanes.map((l) => l.name)];
-    validate_only_lanes(options, lanes);
+    validate_only_lanes(options.onlyLanes, this._declared_lanes);
     this._ports = options.scoped ?? default_scope();
     const ports = this._ports;
     this._scoped = make_run_scoped({
@@ -3082,7 +3086,7 @@ var Act = class {
       handle,
       handle_batch
     );
-    this._advise_orphaned_lanes(options);
+    this._advise_orphaned_lanes();
     this._audit_deps = this._build_audit_deps();
     this._correlate = this._build_correlate(options, classification);
     this._settle = this._build_settle(options);
@@ -3107,7 +3111,7 @@ var Act = class {
   /** Apps that declare no lanes pass no lane filter to `claim`. */
   _build_drain_controllers(options, lanes, handle, handle_batch) {
     const all_lanes = this._declared_lanes;
-    const only_set = options.onlyLanes && options.onlyLanes.length > 0 ? new Set(options.onlyLanes) : void 0;
+    const only_set = options.onlyLanes?.length ? new Set(options.onlyLanes) : void 0;
     const active_lanes = only_set ? all_lanes.filter((n) => only_set.has(n)) : all_lanes;
     const single_default_lane = lanes.length === 0;
     const controllers = /* @__PURE__ */ new Map();
@@ -3144,15 +3148,14 @@ var Act = class {
           leaseMillis: cfg.leaseMillis
         }
       });
-      if (cfg?.cycleMs !== void 0 && options.drain !== false)
+      if (cfg?.cycleMs !== void 0 && this._drain)
         controller.start(cfg.cycleMs);
       controllers.set(name, controller);
     }
     return controllers;
   }
   /** One process can't see the cluster, so it reports its own lane gaps. */
-  _advise_orphaned_lanes(options) {
-    if (!options.onlyLanes || options.onlyLanes.length === 0) return;
+  _advise_orphaned_lanes() {
     const active = new Set(this._drain_controllers.keys());
     const orphaned = this._declared_lanes.filter((name) => !active.has(name));
     if (orphaned.length === 0) return;
@@ -3202,10 +3205,7 @@ var Act = class {
   _build_settle(options) {
     return new SettleLoop(
       {
-        correlate: (q) => this._correlate_pass(
-          { ...q, limit: q.limit ?? this._poll_limit ?? 100 },
-          true
-        ),
+        correlate: (q) => this._correlate_pass(q.limit ?? this._poll_limit ?? 100, true),
         // `settle()` validated the options, and `_schedule` skips writer-only
         // instances, so the loop drains through the internal path.
         drain: (o) => this._scoped(() => this._drain_all(o)),
@@ -3300,9 +3300,10 @@ var Act = class {
   }
   /**
    * Executes an action: validates the payload, loads the state, checks its
-   * invariants, and commits the events its handler emits, with optimistic
-   * concurrency on the stream. The reactions to those events settle on
-   * their own (unless `autoSettle: false`).
+   * preconditions, runs the handler, folds the events it emits, checks the
+   * state's invariants (its schema) on the result, and commits them with
+   * optimistic concurrency on the stream. The reactions to those events
+   * settle on their own (unless `autoSettle: false`).
    *
    * @template TKey - Action name from registered actions
    * @param action - The name of the action to execute
@@ -3313,8 +3314,9 @@ var Act = class {
    *   framework or orchestrator-level correlator for this call only.
    * @returns Array of snapshots for all affected states (usually one)
    *
-   * @throws {ValidationError} If payload doesn't match action schema
-   * @throws {InvariantError} If business rules are violated
+   * @throws {ValidationError} If the payload doesn't match the action schema,
+   *   or the state the action leaves breaks the state schema
+   * @throws {PreconditionError} If business rules are violated
    * @throws {ConcurrencyError} If another process modified the stream
    *
    * @example Basic action execution
@@ -3333,7 +3335,7 @@ var Act = class {
    *
    * @see {@link Target} for target structure
    * @see {@link Snapshot} for return value structure
-   * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
+   * @see {@link ValidationError}, {@link PreconditionError}, {@link ConcurrencyError}
    */
   async do(action2, target, payload, options) {
     const reacting_to = options?.reactingTo ?? current_reacting();
@@ -3567,17 +3569,17 @@ var Act = class {
    * @see {@link start_correlations} for automatic periodic correlation
    */
   async correlate(query = {}) {
-    const pass = await this._correlate_pass({ limit: query.limit ?? 10 });
+    const pass = await this._correlate_pass(query.limit ?? 10);
     return {
       subscribed: pass.kind === "scanned" ? pass.subscribed : 0,
       last_id: pass.last_id
     };
   }
   /** One correlate pass; arms every lane when it found work. */
-  async _correlate_pass(query, lease = false) {
+  async _correlate_pass(limit, lease = false) {
     if (!this._drain) return { kind: "idle", last_id: -1 };
     return this._scoped(async () => {
-      const pass = await this._correlate.correlate(query, lease);
+      const pass = await this._correlate.correlate(limit, lease);
       if (pass.kind === "scanned" && pass.marked > 0) this._arm_all();
       return pass;
     });
@@ -3595,8 +3597,9 @@ var Act = class {
    * (`drain: false`) each tick is a no-op, like `settle()`.
    *
    * @param query - Only `limit` is used: the most events each correlate pass
-   *   reads (default 100). The scan always starts at the correlation
-   *   checkpoint, so `after` is ignored.
+   *   reads. With no limit, or `0`, the passes use the background default
+   *   (100): a poll never reads the whole log in one tick. The scan always
+   *   starts at the correlation checkpoint, so `after` is ignored.
    * @param frequency - Milliseconds between ticks (default: 10000)
    * @returns `true` if the poll started, `false` if one is already running
    *
@@ -4639,7 +4642,7 @@ function act() {
     if (reset) Object.defineProperty(wrapped, FOLD_RESET, { value: reset });
     return wrapped;
   };
-  const make_batch_handlers = (patch_fn) => {
+  const make_batch_handlers = () => {
     const handlers = new Map(batch_handlers);
     for (const spec of fold_specs) {
       handlers.set(
@@ -4649,7 +4652,7 @@ function act() {
             spec.merged,
             spec.flush,
             spec.config,
-            patch_fn,
+            bare_patch,
             // Head loads strip sensitive keys like the warm path.
             registry.sensitive_fields
           )
@@ -4730,7 +4733,6 @@ function act() {
     },
     build: (options) => {
       resolveActConfig(options);
-      const patch_fn = options?.validateFoldedState === true ? validating_patch : bare_patch;
       if (!_built) {
         for (const proj of pending_projections) add_projection(proj);
         for (const proj of fold_projections) {
@@ -4791,10 +4793,9 @@ function act() {
       return new Act(
         registry,
         states,
-        make_batch_handlers(patch_fn),
+        make_batch_handlers(),
         options,
-        lanes,
-        patch_fn
+        lanes
       );
     },
     events: registry.events
@@ -5269,6 +5270,7 @@ export {
   LogLevels,
   NonRetryableError,
   PackageSchema,
+  PreconditionError,
   QuerySchema,
   REDACTED,
   SHREDDED,