@rotorsoft/act 1.10.2 → 1.12.0

package/dist/index.cjs

@@ -37,6 +37,9 @@ __export(index_exports, {
   ConcurrencyError: () => ConcurrencyError,
   ConsoleLogger: () => ConsoleLogger,
   CsvFile: () => CsvFile,
+  DEFAULT_AUTOCLOSE_CYCLE_MS: () => DEFAULT_AUTOCLOSE_CYCLE_MS,
+  DEFAULT_CLOSE_BATCH_SIZE: () => DEFAULT_CLOSE_BATCH_SIZE,
+  DEFAULT_CLOSE_YIELD_MS: () => DEFAULT_CLOSE_YIELD_MS,
   DEFAULT_LANE: () => DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS: () => DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS: () => DEFAULT_SETTLE_DEBOUNCE_MS,
@@ -68,6 +71,7 @@ __export(index_exports, {
   log: () => log,
   port: () => port,
   projection: () => projection,
+  resolveAutocloseConfig: () => resolveAutocloseConfig,
   scoped: () => scoped,
   sensitive: () => sensitive,
   sleep: () => sleep,
@@ -1854,57 +1858,24 @@ var PASS_FACTORIES = {
   "clock-anomalies": make_clock_anomalies_pass
 };
 
-// src/internal/build-classify.ts
-var ALL_LANES = /* @__PURE__ */ Symbol("act-1103/all-lanes");
-function classify_registry(registry, states) {
-  const statics = /* @__PURE__ */ new Map();
-  const reactive_events = /* @__PURE__ */ new Set();
-  const event_to_lanes = /* @__PURE__ */ new Map();
-  let has_dynamic_resolvers = false;
-  for (const [name, register] of Object.entries(registry.events)) {
-    if (register.reactions.size > 0) reactive_events.add(name);
-    for (const reaction of register.reactions.values()) {
-      if (typeof reaction.resolver === "function") {
-        has_dynamic_resolvers = true;
-        event_to_lanes.set(name, ALL_LANES);
-      } else {
-        const { target, source, priority = 0, lane } = reaction.resolver;
-        const lane_name = lane ?? "default";
-        const existing_lanes = event_to_lanes.get(name);
-        if (existing_lanes !== ALL_LANES) {
-          const set = existing_lanes ?? /* @__PURE__ */ new Set();
-          set.add(lane_name);
-          event_to_lanes.set(name, set);
-        }
-        const key = `${target}|${source ?? ""}`;
-        const existing = statics.get(key);
-        if (!existing) {
-          statics.set(key, { stream: target, source, priority, lane });
-        } else {
-          if ((existing.lane ?? void 0) !== (lane ?? void 0))
-            throw new Error(
-              `Stream "${target}" has conflicting lane assignments ("${existing.lane ?? "default"}" vs "${lane ?? "default"}")`
-            );
-          if (priority > existing.priority) {
-            statics.set(key, { ...existing, priority });
-          }
-        }
-      }
-    }
-  }
-  const event_to_state = /* @__PURE__ */ new Map();
-  for (const merged of states.values()) {
-    for (const event_name of Object.keys(merged.events)) {
-      event_to_state.set(event_name, merged);
-    }
-  }
-  return {
-    static_targets: [...statics.values()],
-    has_dynamic_resolvers,
-    reactive_events,
-    event_to_state,
-    event_to_lanes
-  };
+// src/internal/autoclose-config.ts
+var import_zod5 = require("zod");
+var DEFAULT_AUTOCLOSE_CYCLE_MS = 6e4;
+var DEFAULT_CLOSE_BATCH_SIZE = 64;
+var DEFAULT_CLOSE_YIELD_MS = 0;
+var AutocloseOptionsSchema = import_zod5.z.object({
+  autocloseCycleMs: import_zod5.z.number().min(1e4).max(36e5).default(DEFAULT_AUTOCLOSE_CYCLE_MS),
+  closeBatchSize: import_zod5.z.number().int().min(1).max(1024).default(DEFAULT_CLOSE_BATCH_SIZE),
+  closeYieldMs: import_zod5.z.number().min(0).max(1e3).default(DEFAULT_CLOSE_YIELD_MS),
+  closeOnError: import_zod5.z.boolean().default(false)
+});
+function resolveAutocloseConfig(options) {
+  return AutocloseOptionsSchema.parse({
+    autocloseCycleMs: options?.autocloseCycleMs,
+    closeBatchSize: options?.closeBatchSize,
+    closeYieldMs: options?.closeYieldMs,
+    closeOnError: options?.closeOnError
+  });
 }
 
 // src/internal/close-cycle.ts
@@ -2054,6 +2025,303 @@ async function truncate_and_warm_cache(guarded, seed_states, guard_events, corre
   return truncated;
 }
 
+// src/internal/correlator.ts
+var import_node_crypto = require("crypto");
+var BASE = 36;
+var SEG_WIDTH = 4;
+var SEG_SPACE = BASE ** SEG_WIDTH;
+function seg(n) {
+  return n.toString(BASE).padStart(SEG_WIDTH, "0");
+}
+var default_correlator = ({ state: state2, action: action2 }) => {
+  const s = state2.slice(0, SEG_WIDTH).toLowerCase();
+  const a = action2.slice(0, SEG_WIDTH).toLowerCase();
+  const ts = seg(Date.now() % SEG_SPACE);
+  const rnd = seg((0, import_node_crypto.randomInt)(SEG_SPACE));
+  return `${s}-${a}-${ts}${rnd}`;
+};
+function close_correlation(correlator, actor) {
+  return correlator({
+    state: "$close",
+    action: "close",
+    stream: "$close",
+    actor
+  });
+}
+
+// src/internal/autoclose-cycle.ts
+function yield_between_batches(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function run_autoclose_cycle(deps) {
+  const s = store2();
+  let inspected = 0;
+  let evaluated = 0;
+  let predicate_errors = 0;
+  const truncated = /* @__PURE__ */ new Map();
+  const skipped = [];
+  const stats = await s.query_stats(
+    {},
+    { count: true, exclude: [TOMBSTONE_EVENT] }
+  );
+  const flush_batch = async (candidates2) => {
+    if (candidates2.length === 0) return;
+    const result = await run_close_cycle(candidates2, {
+      reactive_events_size: deps.reactive_events_size,
+      event_to_state: deps.event_to_state,
+      load: deps.load,
+      tombstone: deps.tombstone,
+      logger: deps.logger,
+      correlation: deps.correlation
+    });
+    for (const [stream, entry] of result.truncated) {
+      truncated.set(stream, entry);
+    }
+    for (const stream of result.skipped) skipped.push(stream);
+    await yield_between_batches(deps.config.closeYieldMs);
+  };
+  let candidates = [];
+  for (const [stream, { head, count }] of stats) {
+    inspected += 1;
+    const owner = deps.event_to_state.get(head.name);
+    if (!owner) continue;
+    const predicate = deps.autoclose_policy(owner.name);
+    if (!predicate) continue;
+    let close = false;
+    try {
+      close = predicate(stream, head, count ?? 0);
+      evaluated += 1;
+    } catch (err) {
+      predicate_errors += 1;
+      deps.logger.error(
+        `Autoclose predicate for state "${owner.name}" threw on stream "${stream}": ${err instanceof Error ? err.message : String(err)}`
+      );
+      close = deps.config.closeOnError;
+    }
+    if (!close) continue;
+    const archiver = deps.autoclose_archiver(owner.name);
+    const archive = archiver ? () => archiver(stream, head) : void 0;
+    candidates.push({ stream, archive });
+    if (candidates.length >= deps.config.closeBatchSize) {
+      await flush_batch(candidates);
+      candidates = [];
+    }
+  }
+  await flush_batch(candidates);
+  return {
+    inspected,
+    evaluated,
+    predicate_errors,
+    close_result: { truncated, skipped }
+  };
+}
+var AutocloseController = class {
+  deps;
+  _timer;
+  /**
+   * Reentrancy guard. The interval fires the next tick on cadence
+   * regardless of how long the previous one took; this flag drops
+   * overlapping ticks so the cycle stays sequential per controller.
+   */
+  _running = false;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /**
+   * Start the cycle ticker. Returns `false` if already running so
+   * accidental double-start doesn't stack timers (matches
+   * `_correlate.start_polling` semantics).
+   */
+  start() {
+    if (this._timer) return false;
+    this._timer = setInterval(() => {
+      this.run_once().catch((err) => {
+        this.deps.logger.error(
+          `Autoclose cycle errored: ${err instanceof Error ? err.message : String(err)}`
+        );
+      });
+    }, this.deps.config.autocloseCycleMs);
+    this._timer.unref();
+    return true;
+  }
+  /**
+   * Stop the cycle ticker. Idempotent.
+   */
+  stop() {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = void 0;
+    }
+  }
+  /**
+   * Whether the ticker is currently running.
+   */
+  get is_running() {
+    return this._timer !== void 0;
+  }
+  /**
+   * Run one cycle synchronously. The controller's interval callback
+   * delegates here; tests can invoke it directly to deterministically
+   * exercise the cycle without spinning real timers.
+   *
+   * Overlapping invocations short-circuit: if a previous tick is
+   * still running, this one drops and returns `null`. The orchestrator
+   * never sees a queue of pending ticks regardless of how slow the
+   * predicate / archive / truncate are.
+   */
+  async run_once() {
+    if (this._running) return null;
+    this._running = true;
+    try {
+      const correlation = close_correlation(
+        this.deps.correlator,
+        this.deps.close_actor
+      );
+      const result = await run_autoclose_cycle({
+        autoclose_policy: this.deps.autoclose_policy,
+        autoclose_archiver: this.deps.autoclose_archiver,
+        event_to_state: this.deps.event_to_state,
+        reactive_events_size: this.deps.reactive_events_size,
+        load: this.deps.load,
+        tombstone: this.deps.tombstone,
+        logger: this.deps.logger,
+        config: this.deps.config,
+        correlation
+      });
+      if (result.close_result.truncated.size > 0) {
+        this.deps.on_closed(result.close_result);
+      }
+      return result;
+    } finally {
+      this._running = false;
+    }
+  }
+};
+
+// src/internal/autoclose-policy.ts
+var import_zod6 = require("zod");
+var MIN_AFTER_MS = 6e4;
+var AfterSchema = import_zod6.z.object({
+  days: import_zod6.z.number({ message: "autocloses: after.days must be a number" }).positive("autocloses: after.days must be > 0")
+}).refine((o) => o.days * 864e5 >= MIN_AFTER_MS, {
+  message: `autocloses: after resolves to < ${MIN_AFTER_MS}ms (one minute), which is too short to be a meaningful retention window`
+});
+var IsSchema = import_zod6.z.union([
+  import_zod6.z.string().min(1, "autocloses: is must be a non-empty event name"),
+  import_zod6.z.array(
+    import_zod6.z.string().min(1, "autocloses: is entries must be non-empty event names")
+  ).min(1, "autocloses: is must include at least one event name").readonly()
+]);
+var ReachesSchema = import_zod6.z.number({ message: "autocloses: reaches must be a number" }).int("autocloses: reaches must be an integer").min(1, "autocloses: reaches must be >= 1");
+var OrBlockSchema = import_zod6.z.object({
+  after: AfterSchema.optional(),
+  is: IsSchema.optional(),
+  reaches: ReachesSchema.optional()
+}).strict().refine(
+  (o) => o.after !== void 0 || o.is !== void 0 || o.reaches !== void 0,
+  {
+    message: "autocloses: `or` block must include at least one of after / is / reaches"
+  }
+);
+var AutoclosePolicySchema = import_zod6.z.object({
+  after: AfterSchema.optional(),
+  is: IsSchema.optional(),
+  reaches: ReachesSchema.optional(),
+  or: OrBlockSchema.optional()
+}).strict().refine(
+  (o) => o.after !== void 0 || o.is !== void 0 || o.reaches !== void 0 || o.or !== void 0,
+  {
+    message: "autocloses: at least one of after / is / reaches / or must be specified \u2014 empty `{}` is a misconfiguration"
+  }
+);
+function compile_after(after) {
+  const after_ms = after.days * 864e5;
+  return (_stream, head) => Date.now() - head.created.getTime() >= after_ms;
+}
+function compile_is(is) {
+  const set = new Set(typeof is === "string" ? [is] : is);
+  return (_stream, head) => set.has(head.name);
+}
+function compile_reaches(reaches) {
+  return (_stream, _head, count) => count >= reaches;
+}
+function compile_autoclose_policy(options) {
+  const parsed = AutoclosePolicySchema.parse(options);
+  const and_preds = [];
+  if (parsed.after) and_preds.push(compile_after(parsed.after));
+  if (parsed.is) and_preds.push(compile_is(parsed.is));
+  if (parsed.reaches) and_preds.push(compile_reaches(parsed.reaches));
+  const or_preds = [];
+  if (parsed.or) {
+    if (parsed.or.after) or_preds.push(compile_after(parsed.or.after));
+    if (parsed.or.is) or_preds.push(compile_is(parsed.or.is));
+    if (parsed.or.reaches) or_preds.push(compile_reaches(parsed.or.reaches));
+  }
+  return (stream, head, count) => {
+    if (and_preds.length > 0 && and_preds.every((p) => p(stream, head, count))) {
+      return true;
+    }
+    if (or_preds.some((p) => p(stream, head, count))) {
+      return true;
+    }
+    return false;
+  };
+}
+
+// src/internal/build-classify.ts
+var ALL_LANES = /* @__PURE__ */ Symbol("act-1103/all-lanes");
+function classify_registry(registry, states) {
+  const statics = /* @__PURE__ */ new Map();
+  const reactive_events = /* @__PURE__ */ new Set();
+  const event_to_lanes = /* @__PURE__ */ new Map();
+  let has_dynamic_resolvers = false;
+  for (const [name, register] of Object.entries(registry.events)) {
+    if (register.reactions.size > 0) reactive_events.add(name);
+    for (const reaction of register.reactions.values()) {
+      if (typeof reaction.resolver === "function") {
+        has_dynamic_resolvers = true;
+        event_to_lanes.set(name, ALL_LANES);
+      } else {
+        const { target, source, priority = 0, lane } = reaction.resolver;
+        const lane_name = lane ?? "default";
+        const existing_lanes = event_to_lanes.get(name);
+        if (existing_lanes !== ALL_LANES) {
+          const set = existing_lanes ?? /* @__PURE__ */ new Set();
+          set.add(lane_name);
+          event_to_lanes.set(name, set);
+        }
+        const key = `${target}|${source ?? ""}`;
+        const existing = statics.get(key);
+        if (!existing) {
+          statics.set(key, { stream: target, source, priority, lane });
+        } else {
+          if ((existing.lane ?? void 0) !== (lane ?? void 0))
+            throw new Error(
+              `Stream "${target}" has conflicting lane assignments ("${existing.lane ?? "default"}" vs "${lane ?? "default"}")`
+            );
+          if (priority > existing.priority) {
+            statics.set(key, { ...existing, priority });
+          }
+        }
+      }
+    }
+  }
+  const event_to_state = /* @__PURE__ */ new Map();
+  for (const merged of states.values()) {
+    for (const event_name of Object.keys(merged.events)) {
+      event_to_state.set(event_name, merged);
+    }
+  }
+  return {
+    static_targets: [...statics.values()],
+    has_dynamic_resolvers,
+    reactive_events,
+    event_to_state,
+    event_to_lanes
+  };
+}
+
 // src/internal/correlate-cycle.ts
 var CorrelateCycle = class {
   _checkpoint = -1;
@@ -2182,30 +2450,6 @@ var CorrelateCycle = class {
   }
 };
 
-// src/internal/correlator.ts
-var import_node_crypto = require("crypto");
-var BASE = 36;
-var SEG_WIDTH = 4;
-var SEG_SPACE = BASE ** SEG_WIDTH;
-function seg(n) {
-  return n.toString(BASE).padStart(SEG_WIDTH, "0");
-}
-var default_correlator = ({ state: state2, action: action2 }) => {
-  const s = state2.slice(0, SEG_WIDTH).toLowerCase();
-  const a = action2.slice(0, SEG_WIDTH).toLowerCase();
-  const ts = seg(Date.now() % SEG_SPACE);
-  const rnd = seg((0, import_node_crypto.randomInt)(SEG_SPACE));
-  return `${s}-${a}-${ts}${rnd}`;
-};
-function close_correlation(correlator, actor) {
-  return correlator({
-    state: "$close",
-    action: "close",
-    stream: "$close",
-    actor
-  });
-}
-
 // src/internal/drain-cycle.ts
 var import_node_crypto2 = require("crypto");
 
@@ -2981,7 +3225,7 @@ var DrainController = class {
 };
 
 // src/internal/merge.ts
-var import_zod5 = require("zod");
+var import_zod7 = require("zod");
 function base_type_name(zodType) {
   let t = zodType;
   while (typeof t.unwrap === "function") {
@@ -2990,7 +3234,7 @@ function base_type_name(zodType) {
   return t.constructor.name;
 }
 function merge_schemas(existing, incoming, state_name) {
-  if (existing instanceof import_zod5.ZodObject && incoming instanceof import_zod5.ZodObject) {
+  if (existing instanceof import_zod7.ZodObject && incoming instanceof import_zod7.ZodObject) {
     const existing_shape = existing.shape;
     const incoming_shape = incoming.shape;
     for (const key of Object.keys(incoming_shape)) {
@@ -3309,6 +3553,22 @@ var Act = class {
   registry;
   /** Map of state name → state definition; populated by the builder. */
   _states;
+  /**
+   * Resolved autoclose configuration (#837 / epic #802). Frozen at
+   * `act().build()` via {@link resolveAutocloseConfig}.
+   *
+   * @internal
+   */
+  _autoclose_config;
+  /**
+   * App-level autoclose controller. `undefined` when no state declares
+   * `.autocloses(...)` — the controller is never constructed, so
+   * `start_correlations()` / `stop_correlations()` skip the autoclose
+   * lifecycle and the orchestrator pays zero per-tick cost.
+   *
+   * @internal
+   */
+  _autoclose;
   /**
    * Emit a lifecycle event. The payload type is inferred from the event name
    * via {@link ActLifecycleEvents}.
@@ -3443,6 +3703,7 @@ var Act = class {
     this._reactive_events = reactive_events;
     this._listen = options.listen !== false;
     this._drain = options.drain !== false;
+    this._autoclose_config = resolveAutocloseConfig(options);
     this._event_to_state = event_to_state;
     this._event_to_lanes = event_to_lanes;
     const all_lanes = ["default", ...lanes.map((l) => l.name)];
@@ -3506,6 +3767,26 @@ var Act = class {
       },
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
+    const states_with_policy = [...this._states.values()].filter(
+      (s) => s.autoclose
+    );
+    this._autoclose = states_with_policy.length ? new AutocloseController({
+      // Internal cycle takes the loose `(string) => …` signature; the
+      // public `registry.autoclose_policy` narrows to
+      // `keyof TStateMap & string`. Thin lambdas bridge across the
+      // narrowing — runtime semantics are unchanged.
+      autoclose_policy: (name) => this.registry.autoclose_policy(name),
+      autoclose_archiver: (name) => this.registry.autoclose_archiver(name),
+      event_to_state: this._event_to_state,
+      reactive_events_size: this._reactive_events.size,
+      load: this._es.load,
+      tombstone: this._es.tombstone,
+      logger: this._logger,
+      config: this._autoclose_config,
+      correlator: this._correlator,
+      close_actor: { id: "$autoclose", name: "autoclose" },
+      on_closed: (result) => this.emit("closed", result)
+    }) : void 0;
     this._notify_disposer = this._wire_notify(options.scoped?.store ?? store2());
     dispose(() => this.shutdown());
   }
@@ -3997,7 +4278,9 @@ var Act = class {
    * @see {@link stop_correlations} to stop the worker
    */
   start_correlations(query = {}, frequency = 1e4, callback) {
-    return this._correlate.start_polling(query, frequency, callback);
+    const started = this._correlate.start_polling(query, frequency, callback);
+    this._autoclose?.start();
+    return started;
   }
   /**
    * Stops the automatic correlation worker.
@@ -4018,6 +4301,7 @@ var Act = class {
    */
   stop_correlations() {
     this._correlate.stop_polling();
+    this._autoclose?.stop();
   }
   /**
    * Cancels any pending or active settle cycle.
@@ -4402,13 +4686,17 @@ function act() {
   const _sf = /* @__PURE__ */ new Map();
   const _dp = /* @__PURE__ */ new Map();
   const _de = /* @__PURE__ */ new Map();
+  const _ac = /* @__PURE__ */ new Map();
+  const _aa = /* @__PURE__ */ new Map();
   const EMPTY_DEPRECATED = /* @__PURE__ */ new Set();
   const registry = {
     actions: {},
     events: {},
     sensitive_fields: (event_name) => _sf.get(event_name) ?? [],
     disclosure_predicate: (state_name) => _dp.get(state_name) ?? null,
-    deprecated_events: (state_name) => _de.get(state_name) ?? EMPTY_DEPRECATED
+    deprecated_events: (state_name) => _de.get(state_name) ?? EMPTY_DEPRECATED,
+    autoclose_policy: (state_name) => _ac.get(state_name) ?? null,
+    autoclose_archiver: (state_name) => _aa.get(state_name) ?? null
   };
   const pending_projections = [];
   const batch_handlers = /* @__PURE__ */ new Map();
@@ -4535,6 +4823,8 @@ function act() {
         }
         for (const state2 of states.values()) {
           if (state2.disclose) _dp.set(state2.name, state2.disclose);
+          if (state2.autoclose) _ac.set(state2.name, state2.autoclose);
+          if (state2.archive) _aa.set(state2.name, state2.archive);
           const fields_by_event = /* @__PURE__ */ new Map();
           for (const event_name of Object.keys(state2.events)) {
             const fields = _sf.get(event_name);
@@ -4802,6 +5092,31 @@ function action_builder(state2) {
       internal.disclose = disclose;
       return builder;
     },
+    autocloses(predicate_or_policy) {
+      let predicate;
+      if (typeof predicate_or_policy === "function") {
+        predicate = predicate_or_policy;
+      } else if (predicate_or_policy !== null && typeof predicate_or_policy === "object") {
+        predicate = compile_autoclose_policy(
+          predicate_or_policy
+        );
+      } else {
+        throw new Error(
+          ".autocloses(...) requires a function or a policy object; got " + typeof predicate_or_policy
+        );
+      }
+      internal.autoclose = predicate;
+      return builder;
+    },
+    archives(archive) {
+      if (typeof archive !== "function") {
+        throw new Error(
+          ".archives(archive) requires a function; got " + typeof archive
+        );
+      }
+      internal.archive = archive;
+      return builder;
+    },
     build() {
       return internal;
     }
@@ -4978,6 +5293,9 @@ function write_line(writer, line) {
   ConcurrencyError,
   ConsoleLogger,
   CsvFile,
+  DEFAULT_AUTOCLOSE_CYCLE_MS,
+  DEFAULT_CLOSE_BATCH_SIZE,
+  DEFAULT_CLOSE_YIELD_MS,
   DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS,
@@ -5009,6 +5327,7 @@ function write_line(writer, line) {
   log,
   port,
   projection,
+  resolveAutocloseConfig,
   scoped,
   sensitive,
   sleep,