@rotorsoft/act 1.16.0 → 1.17.0

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-46OCUAVF.js";
+} from "./chunk-7XME4ZLK.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -540,353 +540,6 @@ function in_autoclose_window(window, now) {
   return window.start < window.end ? hour >= window.start && hour < window.end : hour >= window.start || hour < window.end;
 }
 
-// src/internal/close-cycle.ts
-var SAFETY_PROBE_PAGE_SIZE = 1e3;
-async function run_close_cycle(targets, deps) {
-  const target_map = new Map(targets.map((t) => [t.stream, t]));
-  const streams = [...target_map.keys()];
-  const skipped = [];
-  const stream_info = await scan_stream_heads(streams);
-  const safe = await partition_by_safety(
-    stream_info,
-    deps.reactive_events_size,
-    skipped,
-    deps.probe_page_size ?? SAFETY_PROBE_PAGE_SIZE
-  );
-  if (!safe.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
-  const { guarded, guard_events } = await guard_with_tombstones(
-    safe,
-    stream_info,
-    deps.correlation,
-    deps.tombstone,
-    skipped
-  );
-  if (!guarded.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
-  const seed_states = await load_restart_seeds(
-    guarded,
-    target_map,
-    stream_info,
-    deps.event_to_state,
-    deps.load,
-    deps.logger
-  );
-  await run_archive_callbacks(guarded, target_map);
-  const truncated = await truncate_and_warm_cache(
-    guarded,
-    seed_states,
-    guard_events,
-    deps.correlation
-  );
-  return { truncated, skipped };
-}
-async function scan_stream_heads(streams) {
-  const stats = await store().query_stats(streams, {
-    exclude: [SNAP_EVENT]
-  });
-  const out = /* @__PURE__ */ new Map();
-  for (const [stream, { head }] of stats) {
-    if (head.name === TOMBSTONE_EVENT) continue;
-    out.set(stream, {
-      max_id: head.id,
-      version: head.version,
-      last_event_name: head.name
-    });
-  }
-  return out;
-}
-async function partition_by_safety(stream_info, reactive_events_size, skipped, page_size) {
-  if (reactive_events_size === 0) return [...stream_info.keys()];
-  const pending_set = /* @__PURE__ */ new Set();
-  const source_regex = /* @__PURE__ */ new Map();
-  const get_regex = (source) => {
-    let re = source_regex.get(source);
-    if (!re) {
-      re = new RegExp(source);
-      source_regex.set(source, re);
-    }
-    return re;
-  };
-  const targets = [...stream_info.keys()];
-  let after;
-  for (; ; ) {
-    let last;
-    const { count } = await store().query_streams(
-      (position) => {
-        last = position.stream;
-        const source_re = position.source ? get_regex(position.source) : void 0;
-        for (const [stream, info] of stream_info) {
-          if ((!source_re || source_re.test(stream)) && position.at < info.max_id) {
-            pending_set.add(stream);
-          }
-        }
-      },
-      { after, limit: page_size, source_matches: targets }
-    );
-    if (count < page_size) break;
-    after = last;
-  }
-  const safe = [];
-  for (const [stream] of stream_info) {
-    if (pending_set.has(stream)) skipped.push(stream);
-    else safe.push(stream);
-  }
-  return safe;
-}
-async function guard_with_tombstones(safe, stream_info, correlation, tombstone2, skipped) {
-  const guarded = [];
-  const guard_events = /* @__PURE__ */ new Map();
-  await Promise.all(
-    safe.map(async (stream) => {
-      const info = stream_info.get(stream);
-      const committed = await tombstone2(stream, info.version, correlation);
-      if (committed) {
-        guarded.push(stream);
-        guard_events.set(stream, { id: committed.id, stream });
-      } else {
-        skipped.push(stream);
-      }
-    })
-  );
-  return { guarded, guard_events };
-}
-async function load_restart_seeds(guarded, target_map, stream_info, event_to_state, load2, logger) {
-  const seed_states = /* @__PURE__ */ new Map();
-  await Promise.all(
-    guarded.filter((s) => target_map.get(s)?.restart).map(async (stream) => {
-      const last_event_name = stream_info.get(stream).last_event_name;
-      const owner_state = event_to_state.get(last_event_name);
-      if (!owner_state) {
-        logger.error(
-          `Cannot seed restart for "${stream}": no registered state owns event "${last_event_name}". Stream will be tombstoned instead.`
-        );
-        return;
-      }
-      const snap2 = await load2(owner_state, { stream });
-      seed_states.set(stream, snap2.state);
-    })
-  );
-  return seed_states;
-}
-async function run_archive_callbacks(guarded, target_map) {
-  for (const stream of guarded) {
-    const archive_fn = target_map.get(stream)?.archive;
-    if (archive_fn) await archive_fn();
-  }
-}
-async function truncate_and_warm_cache(guarded, seed_states, guard_events, correlation) {
-  const trunc_targets = guarded.map((stream) => {
-    const snapshot = seed_states.get(stream);
-    const guard = guard_events.get(stream);
-    return {
-      stream,
-      snapshot,
-      meta: {
-        correlation,
-        causation: {
-          event: { id: guard.id, name: TOMBSTONE_EVENT, stream: guard.stream }
-        }
-      }
-    };
-  });
-  const truncated = await store().truncate(trunc_targets);
-  await Promise.all(
-    guarded.map(async (stream) => {
-      const entry = truncated.get(stream);
-      const state2 = seed_states.get(stream);
-      if (state2 && entry) {
-        await cache().set(stream, {
-          state: state2,
-          version: entry.committed.version,
-          event_id: entry.committed.id,
-          patches: 0,
-          snaps: 1
-        });
-      } else {
-        await cache().invalidate(stream);
-      }
-    })
-  );
-  return truncated;
-}
-
-// src/internal/correlator.ts
-import { randomInt } from "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(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 = store();
-  let inspected = 0;
-  let evaluated = 0;
-  let predicate_errors = 0;
-  const truncated = /* @__PURE__ */ new Map();
-  const skipped = [];
-  const page = deps.config.closeBatchSize;
-  let after;
-  for (; ; ) {
-    const stats = await s.query_stats(
-      {},
-      { count: true, exclude: [TOMBSTONE_EVENT], after, limit: page }
-    );
-    if (stats.size === 0) break;
-    inspected += stats.size;
-    const candidates = [];
-    for (const [stream, { head, count }] of stats) {
-      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 > 0) {
-      const result = await run_close_cycle(candidates, {
-        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);
-    }
-    if (stats.size < page) break;
-    after = [...stats.keys()].at(-1);
-  }
-  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(() => {
-      });
-    }, this.deps.config.autocloseCycleMinutes * 6e4);
-    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;
-    if (this.deps.breaker.state(Date.now()) === "open") return null;
-    if (!in_autoclose_window(this.deps.config.autocloseWindow, /* @__PURE__ */ new Date()))
-      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
-      });
-      this.deps.breaker.passed();
-      if (result.close_result.truncated.size > 0) {
-        this.deps.on_closed(result.close_result);
-      }
-      return result;
-    } catch (error) {
-      this.deps.breaker.failed(Date.now(), error);
-      throw error;
-    } finally {
-      this._running = false;
-    }
-  }
-};
-
 // src/internal/autoclose-policy.ts
 import { z as z2 } from "zod";
 var MIN_AFTER_MS = 6e4;
@@ -934,6 +587,13 @@ function compile_is(is) {
 function compile_reaches(reaches) {
   return (_stream, _head, count) => count >= reaches;
 }
+function policy_min_after_ms(options) {
+  const parsed = AutoclosePolicySchema.parse(options);
+  const windows = [];
+  if (parsed.after) windows.push(parsed.after.days * 864e5);
+  if (parsed.or?.after) windows.push(parsed.or.after.days * 864e5);
+  return windows.length ? Math.min(...windows) : void 0;
+}
 function compile_autoclose_policy(options) {
   const parsed = AutoclosePolicySchema.parse(options);
   const and_preds = [];
@@ -993,107 +653,304 @@ function classify_registry(registry, states) {
           }
         }
       }
-    }
-  }
-  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);
-    }
+    }
+  }
+  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/circuit-breaker.ts
+import { z as z3 } from "zod";
+var DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 5;
+var DEFAULT_CIRCUIT_COOLDOWN_MS = 3e4;
+var CircuitBreakerOptionsSchema = z3.object({
+  failureThreshold: z3.number().int().min(1).default(DEFAULT_CIRCUIT_FAILURE_THRESHOLD),
+  cooldownMs: z3.number().int().min(100).max(36e5).default(DEFAULT_CIRCUIT_COOLDOWN_MS)
+});
+var resolveCircuitBreakerConfig = (options) => CircuitBreakerOptionsSchema.parse(options ?? {});
+var CircuitBreaker = class {
+  _failures = 0;
+  _opened_at;
+  _wake;
+  _threshold;
+  _cooldown_ms;
+  _hooks;
+  constructor(config2, hooks = {}) {
+    this._threshold = config2.failureThreshold;
+    this._cooldown_ms = config2.cooldownMs;
+    this._hooks = hooks;
+  }
+  /** Current state given the wall-clock `now`. */
+  state(now) {
+    if (this._opened_at === void 0) return "closed";
+    return now - this._opened_at >= this._cooldown_ms ? "half-open" : "open";
+  }
+  /** A store op passed — reset to closed and cancel any pending retry. */
+  passed() {
+    this._failures = 0;
+    this._opened_at = void 0;
+    this._clear_wake();
+  }
+  /**
+   * A store op failed. Opens the breaker when the consecutive-failure
+   * threshold is reached, or immediately re-opens (restarting the cooldown)
+   * if a half-open trial just failed. Returns the resulting state.
+   *
+   * Callers gate on the state directly — `state(now) === "open"` means skip.
+   * On opening, schedules the `on_retry` wake so recovery is automatic;
+   * always surfaces the failure via `on_error`.
+   */
+  failed(now, error) {
+    const circuit = this._advance(now);
+    if (circuit === "open") this._schedule_wake();
+    this._hooks.on_error?.(error, circuit);
+    return circuit;
+  }
+  /** Cancel the pending retry timer. Idempotent; call on shutdown. */
+  stop() {
+    this._clear_wake();
+  }
+  /**
+   * Schedule the `on_retry` wake `cooldownMs` out so the breaker re-trials
+   * the store on its own. No-op when no `on_retry` hook is wired (e.g. unit
+   * tests of the pure state machine). The timer is `unref`'d so it never
+   * keeps the process alive.
+   */
+  _schedule_wake() {
+    if (!this._hooks.on_retry) return;
+    this._clear_wake();
+    this._wake = setTimeout(() => {
+      this._wake = void 0;
+      this._hooks.on_retry?.();
+    }, this._cooldown_ms);
+    this._wake.unref();
+  }
+  _clear_wake() {
+    if (this._wake) {
+      clearTimeout(this._wake);
+      this._wake = void 0;
+    }
+  }
+  /** Pure state transition for a failure — no side effects. */
+  _advance(now) {
+    if (this._opened_at !== void 0) {
+      this._opened_at = now;
+      return "open";
+    }
+    this._failures += 1;
+    if (this._failures >= this._threshold) {
+      this._opened_at = now;
+      return "open";
+    }
+    return "closed";
+  }
+};
+
+// src/internal/close-cycle.ts
+var SAFETY_PROBE_PAGE_SIZE = 1e3;
+async function run_close_cycle(targets, deps) {
+  const target_map = new Map(targets.map((t) => [t.stream, t]));
+  const streams = [...target_map.keys()];
+  const skipped = [];
+  const stream_info = await scan_stream_heads(streams);
+  const safe = await partition_by_safety(
+    stream_info,
+    deps.reactive_events_size,
+    skipped,
+    deps.probe_page_size ?? SAFETY_PROBE_PAGE_SIZE
+  );
+  if (!safe.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
+  const { guarded, guard_events } = await guard_with_tombstones(
+    safe,
+    stream_info,
+    deps.correlation,
+    deps.tombstone,
+    skipped
+  );
+  if (!guarded.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
+  const seed_states = await load_restart_seeds(
+    guarded,
+    target_map,
+    stream_info,
+    deps.event_to_state,
+    deps.load,
+    deps.logger
+  );
+  await run_archive_callbacks(guarded, target_map);
+  const truncated = await truncate_and_warm_cache(
+    guarded,
+    seed_states,
+    guard_events,
+    deps.correlation
+  );
+  return { truncated, skipped };
+}
+async function scan_stream_heads(streams) {
+  const stats = await store().query_stats(streams, {
+    exclude: [SNAP_EVENT]
+  });
+  const out = /* @__PURE__ */ new Map();
+  for (const [stream, { head }] of stats) {
+    if (head.name === TOMBSTONE_EVENT) continue;
+    out.set(stream, {
+      max_id: head.id,
+      version: head.version,
+      last_event_name: head.name
+    });
+  }
+  return out;
+}
+async function partition_by_safety(stream_info, reactive_events_size, skipped, page_size) {
+  if (reactive_events_size === 0) return [...stream_info.keys()];
+  const pending_set = /* @__PURE__ */ new Set();
+  const source_regex = /* @__PURE__ */ new Map();
+  const get_regex = (source) => {
+    let re = source_regex.get(source);
+    if (!re) {
+      re = new RegExp(source);
+      source_regex.set(source, re);
+    }
+    return re;
+  };
+  const targets = [...stream_info.keys()];
+  let after;
+  for (; ; ) {
+    let last;
+    const { count } = await store().query_streams(
+      (position) => {
+        last = position.stream;
+        const source_re = position.source ? get_regex(position.source) : void 0;
+        for (const [stream, info] of stream_info) {
+          if ((!source_re || source_re.test(stream)) && position.at < info.max_id) {
+            pending_set.add(stream);
+          }
+        }
+      },
+      { after, limit: page_size, source_matches: targets }
+    );
+    if (count < page_size) break;
+    after = last;
+  }
+  const safe = [];
+  for (const [stream] of stream_info) {
+    if (pending_set.has(stream)) skipped.push(stream);
+    else safe.push(stream);
+  }
+  return safe;
+}
+async function guard_with_tombstones(safe, stream_info, correlation, tombstone2, skipped) {
+  const guarded = [];
+  const guard_events = /* @__PURE__ */ new Map();
+  await Promise.all(
+    safe.map(async (stream) => {
+      const info = stream_info.get(stream);
+      const committed = await tombstone2(stream, info.version, correlation);
+      if (committed) {
+        guarded.push(stream);
+        guard_events.set(stream, { id: committed.id, stream });
+      } else {
+        skipped.push(stream);
+      }
+    })
+  );
+  return { guarded, guard_events };
+}
+async function load_restart_seeds(guarded, target_map, stream_info, event_to_state, load2, logger) {
+  const seed_states = /* @__PURE__ */ new Map();
+  await Promise.all(
+    guarded.filter((s) => target_map.get(s)?.restart).map(async (stream) => {
+      const last_event_name = stream_info.get(stream).last_event_name;
+      const owner_state = event_to_state.get(last_event_name);
+      if (!owner_state) {
+        logger.error(
+          `Cannot seed restart for "${stream}": no registered state owns event "${last_event_name}". Stream will be tombstoned instead.`
+        );
+        return;
+      }
+      const snap2 = await load2(owner_state, { stream });
+      seed_states.set(stream, snap2.state);
+    })
+  );
+  return seed_states;
+}
+async function run_archive_callbacks(guarded, target_map) {
+  for (const stream of guarded) {
+    const archive_fn = target_map.get(stream)?.archive;
+    if (archive_fn) await archive_fn();
   }
-  return {
-    static_targets: [...statics.values()],
-    has_dynamic_resolvers,
-    reactive_events,
-    event_to_state,
-    event_to_lanes
-  };
+}
+async function truncate_and_warm_cache(guarded, seed_states, guard_events, correlation) {
+  const trunc_targets = guarded.map((stream) => {
+    const snapshot = seed_states.get(stream);
+    const guard = guard_events.get(stream);
+    return {
+      stream,
+      snapshot,
+      meta: {
+        correlation,
+        causation: {
+          event: { id: guard.id, name: TOMBSTONE_EVENT, stream: guard.stream }
+        }
+      }
+    };
+  });
+  const truncated = await store().truncate(trunc_targets);
+  await Promise.all(
+    guarded.map(async (stream) => {
+      const entry = truncated.get(stream);
+      const state2 = seed_states.get(stream);
+      if (state2 && entry) {
+        await cache().set(stream, {
+          state: state2,
+          version: entry.committed.version,
+          event_id: entry.committed.id,
+          patches: 0,
+          snaps: 1
+        });
+      } else {
+        await cache().invalidate(stream);
+      }
+    })
+  );
+  return truncated;
 }
 
-// src/internal/circuit-breaker.ts
-import { z as z3 } from "zod";
-var DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 5;
-var DEFAULT_CIRCUIT_COOLDOWN_MS = 3e4;
-var CircuitBreakerOptionsSchema = z3.object({
-  failureThreshold: z3.number().int().min(1).default(DEFAULT_CIRCUIT_FAILURE_THRESHOLD),
-  cooldownMs: z3.number().int().min(100).max(36e5).default(DEFAULT_CIRCUIT_COOLDOWN_MS)
-});
-var resolveCircuitBreakerConfig = (options) => CircuitBreakerOptionsSchema.parse(options ?? {});
-var CircuitBreaker = class {
-  _failures = 0;
-  _opened_at;
-  _wake;
-  _threshold;
-  _cooldown_ms;
-  _hooks;
-  constructor(config2, hooks = {}) {
-    this._threshold = config2.failureThreshold;
-    this._cooldown_ms = config2.cooldownMs;
-    this._hooks = hooks;
-  }
-  /** Current state given the wall-clock `now`. */
-  state(now) {
-    if (this._opened_at === void 0) return "closed";
-    return now - this._opened_at >= this._cooldown_ms ? "half-open" : "open";
-  }
-  /** A store op passed — reset to closed and cancel any pending retry. */
-  passed() {
-    this._failures = 0;
-    this._opened_at = void 0;
-    this._clear_wake();
-  }
+// src/internal/close-signal.ts
+var CloseSignal = class extends Error {
   /**
-   * A store op failed. Opens the breaker when the consecutive-failure
-   * threshold is reached, or immediately re-opens (restarting the cooldown)
-   * if a half-open trial just failed. Returns the resulting state.
-   *
-   * Callers gate on the state directly — `state(now) === "open"` means skip.
-   * On opening, schedules the `on_retry` wake so recovery is automatic;
-   * always surfaces the failure via `on_error`.
+   * Stream to close. Omitted → the reaction's own lease stream (a self-close).
+   * The synthesized autoclose reaction sets it to the aggregate stream, since
+   * its lease runs on a synthetic `__autoclose__` target.
    */
-  failed(now, error) {
-    const circuit = this._advance(now);
-    if (circuit === "open") this._schedule_wake();
-    this._hooks.on_error?.(error, circuit);
-    return circuit;
-  }
-  /** Cancel the pending retry timer. Idempotent; call on shutdown. */
-  stop() {
-    this._clear_wake();
-  }
+  stream;
+  /** Optional archive callback to run while the stream is guarded. */
+  archive;
   /**
-   * Schedule the `on_retry` wake `cooldownMs` out so the breaker re-trials
-   * the store on its own. No-op when no `on_retry` hook is wired (e.g. unit
-   * tests of the pure state machine). The timer is `unref`'d so it never
-   * keeps the process alive.
+   * Watermark to ack the requesting reaction to before the close runs. The
+   * close-cycle safety guard skips a stream whose subscriptions (matched by
+   * source) lag the head; the autoclose reaction's `source` is the aggregate,
+   * so it must advance its own watermark to the live head id it evaluated
+   * against — otherwise it blocks its own close. Defaults to the triggering
+   * event id when omitted.
    */
-  _schedule_wake() {
-    if (!this._hooks.on_retry) return;
-    this._clear_wake();
-    this._wake = setTimeout(() => {
-      this._wake = void 0;
-      this._hooks.on_retry?.();
-    }, this._cooldown_ms);
-    this._wake.unref();
-  }
-  _clear_wake() {
-    if (this._wake) {
-      clearTimeout(this._wake);
-      this._wake = void 0;
-    }
-  }
-  /** Pure state transition for a failure — no side effects. */
-  _advance(now) {
-    if (this._opened_at !== void 0) {
-      this._opened_at = now;
-      return "open";
-    }
-    this._failures += 1;
-    if (this._failures >= this._threshold) {
-      this._opened_at = now;
-      return "open";
-    }
-    return "closed";
+  at;
+  constructor(opts) {
+    super("reaction requested close");
+    this.name = "CloseSignal";
+    this.stream = opts?.stream;
+    this.archive = opts?.archive;
+    this.at = opts?.at;
   }
 };
 
@@ -1225,9 +1082,122 @@ var CorrelateCycle = class {
   }
 };
 
+// src/internal/correlator.ts
+import { randomInt } from "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(randomInt(SEG_SPACE));
+  return `${s}-${a}-${ts}${rnd}`;
+};
+function close_correlation(correlator, actor) {
+  return correlator({
+    state: "$close",
+    action: "close",
+    stream: "$close",
+    actor
+  });
+}
+
+// src/internal/defer-signal.ts
+var DeferSignal = class extends Error {
+  /** Wall-clock time (ms since epoch) to re-visit the stream. */
+  defer_at;
+  constructor(defer_at) {
+    super("reaction deferred");
+    this.name = "DeferSignal";
+    this.defer_at = defer_at;
+  }
+};
+
 // src/internal/drain-cycle.ts
 import { randomUUID } from "crypto";
 
+// src/internal/defer-timer.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+var DeferTimer = class {
+  _due = /* @__PURE__ */ new Map();
+  _timer;
+  _on_wake;
+  /**
+   * @param on_wake - invoked once each time the earliest due-time elapses,
+   *   after the come-due entries have been removed. Consumers use it to
+   *   re-arm their loop (the drain sets its `armed` flag; autoclose runs a
+   *   tick).
+   */
+  constructor(on_wake) {
+    this._on_wake = on_wake;
+  }
+  /** Number of currently parked streams. */
+  get size() {
+    return this._due.size;
+  }
+  /**
+   * True while `stream` is parked with a due-time still in the future.
+   * Consumers skip work for deferred streams until their window elapses.
+   */
+  is_deferred = (stream) => {
+    const next = this._due.get(stream);
+    return next !== void 0 && next > Date.now();
+  };
+  /**
+   * Park `stream` for a re-visit at `at` (ms since epoch). A plain
+   * overwrite: the caller computes the authoritative next-visit for the
+   * stream (the drain's `handle` already reconciles a stream's reactions
+   * into one result per cycle), so there is no stale value to merge against.
+   */
+  set(stream, at) {
+    this._due.set(stream, at);
+  }
+  /** Drop `stream` from the parked set (e.g. on a successful ack or block). */
+  delete(stream) {
+    this._due.delete(stream);
+  }
+  /**
+   * (Re)schedule the wake timer at the earliest pending due-time. Idempotent
+   * — collapses many parked streams into a single timer. A no-op clears any
+   * pending timer when the map is empty.
+   *
+   * The timer is `unref()`-ed so pending re-visits never keep the process
+   * alive on their own.
+   */
+  schedule() {
+    if (this._timer) clearTimeout(this._timer);
+    if (this._due.size === 0) {
+      this._timer = void 0;
+      return;
+    }
+    let earliest = Number.POSITIVE_INFINITY;
+    for (const t of this._due.values()) if (t < earliest) earliest = t;
+    const delay = Math.min(
+      Math.max(0, earliest - Date.now()),
+      MAX_TIMER_DELAY_MS
+    );
+    this._timer = setTimeout(() => {
+      this._timer = void 0;
+      const now = Date.now();
+      for (const [stream, at] of this._due)
+        if (at <= now) this._due.delete(stream);
+      this._on_wake();
+    }, delay);
+    this._timer.unref();
+  }
+  /** Cancel any pending wake timer. Idempotent. Leaves the parked set intact. */
+  stop() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+  }
+};
+
 // src/internal/drain-ratio.ts
 var RATIO_MIN = 0.2;
 var RATIO_MAX = 0.8;
@@ -1263,6 +1233,7 @@ async function fetch(leased, eventLimit) {
 }
 var ack = (leases) => store().ack(leases);
 var block = (leases) => store().block(leases);
+var defer = (input, deferred_at) => store().defer(input, deferred_at);
 var subscribe = (streams) => store().subscribe(streams);
 
 // src/internal/event-sourcing.ts
@@ -1740,6 +1711,7 @@ function build_drain(logger) {
     fetch,
     ack,
     block,
+    defer,
     subscribe: logger.level !== "trace" ? subscribe : traced(subscribe, (result, streams) => {
       if (!result.subscribed) return;
       const lanes = new Set(streams.map((s) => s.lane ?? "default"));
@@ -1808,7 +1780,8 @@ async function run_drain_cycle(ops, registry, batch_handlers, handle, handle_bat
       fetched: [],
       handled: [],
       acked: [],
-      blocked: []
+      blocked: [],
+      closeable: []
     };
   }
   const fetched = await ops.fetch(active, eventLimit);
@@ -1842,12 +1815,23 @@ async function run_drain_cycle(ops, registry, batch_handlers, handle, handle_bat
     })
   );
   const acked = await ops.ack(
-    handled.filter((h) => h.handled > 0 || !h.error).map((h) => ({ ...h.lease, at: h.acked_at }))
+    handled.filter((h) => h.defer === void 0 && (h.handled > 0 || !h.error)).map((h) => ({ ...h.lease, at: h.acked_at }))
   );
   const blocked = await ops.block(
     handled.filter(({ block: block2 }) => block2).map(({ lease, error }) => ({ ...lease, error }))
   );
-  return { leased, fetched, handled, acked, blocked };
+  const deferrals = handled.filter((h) => h.defer !== void 0);
+  if (deferrals.length) {
+    const by_time = /* @__PURE__ */ new Map();
+    for (const h of deferrals) {
+      const list = by_time.get(h.defer);
+      if (list) list.push(h.lease.stream);
+      else by_time.set(h.defer, [h.lease.stream]);
+    }
+    for (const [at, streams] of by_time) await ops.defer(streams, at);
+  }
+  const closeable = handled.filter((h) => h.close !== void 0).map((h) => h.close);
+  return { leased, fetched, handled, acked, blocked, closeable };
 }
 var EMPTY_DRAIN = {
   fetched: [],
@@ -1860,14 +1844,16 @@ var DrainController = class {
   _locked = false;
   _ratio = 0.5;
   /**
-   * Per-stream backoff: `stream → next_attempt_at` (ms since epoch). Set by
-   * `_finalize` via `HandleResult.next_attempt_at`; cleared on successful
-   * ack or terminal block. Lives in process memory — per-worker pacing
-   * by design (see {@link BackoffOptions} for the multi-worker trade-off).
+   * Per-stream re-visit schedule (#1090): `stream → next visit` (ms since
+   * epoch). Holds both retry backoff (`HandleResult.next_attempt_at`) and the
+   * `defer` outcome; cleared on successful ack or terminal block. Lives in
+   * process memory — per-worker pacing by design (see {@link BackoffOptions}
+   * for the multi-worker trade-off). Its wake re-arms drain at the earliest
+   * pending visit.
    */
-  _backoff = /* @__PURE__ */ new Map();
-  /** Timer re-arming drain at the earliest pending `next_attempt_at`. */
-  _backoff_timer;
+  _defer = new DeferTimer(() => {
+    this._armed = true;
+  });
   /** Worker timer (ACT-1103). Set when `start()` is active, undefined otherwise. */
   _worker;
   _stopped = false;
@@ -1887,32 +1873,6 @@ var DrainController = class {
   get armed() {
     return this._armed;
   }
-  /** Returns true when `stream` is currently within a backoff window. */
-  is_deferred = (stream) => {
-    const next = this._backoff.get(stream);
-    return next !== void 0 && next > Date.now();
-  };
-  /**
-   * Schedule the next drain re-arm at the earliest pending backoff
-   * expiry. Called only when the backoff map is non-empty (caller guard).
-   * Idempotent — collapses many simultaneously deferred streams into a
-   * single timer.
-   */
-  schedule_backoff_wake() {
-    if (this._backoff_timer) clearTimeout(this._backoff_timer);
-    let earliest = Number.POSITIVE_INFINITY;
-    for (const t of this._backoff.values()) if (t < earliest) earliest = t;
-    const delay = Math.max(0, earliest - Date.now());
-    this._backoff_timer = setTimeout(() => {
-      this._backoff_timer = void 0;
-      const now = Date.now();
-      for (const [stream, at] of this._backoff) {
-        if (at <= now) this._backoff.delete(stream);
-      }
-      this._armed = true;
-    }, delay);
-    this._backoff_timer.unref();
-  }
   /** Lane this controller drains (undefined = legacy single-lane span). */
   get lane() {
     return this._deps.lane;
@@ -1944,6 +1904,7 @@ var DrainController = class {
       clearTimeout(this._worker);
       this._worker = void 0;
     }
+    this._defer.stop();
   }
   /** Run one drain pass. Short-circuits when not armed or already running. */
   async drain(options = {}) {
@@ -1969,7 +1930,7 @@ var DrainController = class {
         leading,
         eventLimit,
         leaseMillis,
-        this._backoff.size > 0 ? this.is_deferred : void 0,
+        this._defer.size > 0 ? this._defer.is_deferred : void 0,
         this._deps.lane
       );
       this._deps.breaker.passed();
@@ -1977,19 +1938,19 @@ var DrainController = class {
         this._armed = false;
         return EMPTY_DRAIN;
       }
-      const { leased, fetched, handled, acked, blocked } = cycle;
+      const { leased, fetched, handled, acked, blocked, closeable } = cycle;
       trace_cycle(this._deps.logger, leased, fetched, handled, acked, blocked);
       this._ratio = compute_lag_lead_ratio(handled, lagging, leading);
-      for (const lease of acked) this._backoff.delete(lease.stream);
-      for (const lease of blocked) this._backoff.delete(lease.stream);
+      for (const lease of acked) this._defer.delete(lease.stream);
+      for (const lease of blocked) this._defer.delete(lease.stream);
       for (const h of handled) {
-        if (h.next_attempt_at !== void 0 && !h.block) {
-          this._backoff.set(h.lease.stream, h.next_attempt_at);
-        }
+        const next = h.defer ?? (h.block ? void 0 : h.next_attempt_at);
+        if (next !== void 0) this._defer.set(h.lease.stream, next);
       }
-      if (this._backoff.size > 0) this.schedule_backoff_wake();
+      if (this._defer.size > 0) this._defer.schedule();
       if (acked.length) this._deps.on_acked(acked);
       if (blocked.length) this._deps.on_blocked(blocked);
+      if (closeable.length) await this._deps.on_close(closeable);
       const has_errors = handled.some(({ error }) => error);
       if (!acked.length && !blocked.length && !has_errors) this._armed = false;
       return { fetched, leased, acked, blocked };
@@ -2205,6 +2166,20 @@ function build_handle(deps) {
         at = event.id;
         handled++;
       } catch (error) {
+        if (error instanceof DeferSignal)
+          return { lease, handled, acked_at: at, defer: error.defer_at };
+        if (error instanceof CloseSignal)
+          return {
+            lease,
+            handled: handled + 1,
+            // Advance to the live head the handler evaluated against (when
+            // provided) so the close-cycle guard sees this reaction caught up.
+            acked_at: error.at ?? event.id,
+            // Close the signalled stream (the autoclose reaction's aggregate,
+            // which differs from its synthetic lease stream); a self-closing
+            // user reaction omits it and closes its own lease stream.
+            close: { stream: error.stream ?? stream, archive: error.archive }
+          };
         return finalize(
           lease,
           handled,
@@ -2307,6 +2282,7 @@ var SettleLoop = class {
 // src/act.ts
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
+var AUTOCLOSE_TARGET_PREFIX = "__autoclose__:";
 var Act = class {
   _emitter = new EventEmitter();
   /** ACT-984: orchestrator-owned circuit breaker shared by all drain lanes. */
@@ -2348,15 +2324,6 @@ var Act = class {
    * @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}.
@@ -2497,6 +2464,60 @@ var Act = class {
       bound_forget: this._bound_forget
     });
     this._handle_batch = build_handle_batch(this._logger);
+    for (const st of this._states.values()) {
+      const predicate = st.autoclose;
+      if (!predicate) continue;
+      const after_ms = st.autoclose_after_ms;
+      const archiver = st.archive;
+      const reaction = {
+        // Run on a SYNTHETIC stream — `source` is the aggregate, `target` is a
+        // per-aggregate `__autoclose__` key — so the autoclose reaction never
+        // shares a watermark with the aggregate's own reactions. A shared
+        // watermark would let autoclose's defer short-circuit the aggregate's
+        // other reactions (the "a defer affects all reactions on a stream"
+        // hazard). The close still targets the aggregate (`source`).
+        resolver: (e) => ({
+          target: `${AUTOCLOSE_TARGET_PREFIX}${e.stream}`,
+          source: e.stream
+        }),
+        // Never block on autoclose: a transient query/store error should retry,
+        // not quarantine the synthetic stream.
+        options: { blockOnError: false, maxRetries: 3 },
+        handler: async (event) => {
+          const aggregate = event.stream;
+          const config2 = this._autoclose_config;
+          if (!in_autoclose_window(config2.autocloseWindow, /* @__PURE__ */ new Date()))
+            throw new DeferSignal(
+              Date.now() + config2.autocloseCycleMinutes * 6e4
+            );
+          const stats = await store().query_stats([aggregate], {
+            count: true,
+            exclude: [TOMBSTONE_EVENT]
+          });
+          const entry = stats.get(aggregate);
+          if (!entry) return;
+          const head = entry.head;
+          if (predicate(aggregate, head, entry.count))
+            throw new CloseSignal({
+              stream: aggregate,
+              archive: archiver ? () => archiver(aggregate, head) : void 0,
+              // Ack this reaction's own watermark to the live head so the
+              // close-cycle guard (which matches subscriptions by source =
+              // aggregate) sees it caught up instead of blocking its own close.
+              at: head.id
+            });
+          if (after_ms !== void 0)
+            throw new DeferSignal(head.created.getTime() + after_ms);
+        }
+      };
+      const key = `__autoclose_${st.name}`;
+      for (const event_name of Object.keys(st.events)) {
+        this.registry.events[event_name]?.reactions.set(
+          key,
+          reaction
+        );
+      }
+    }
     const {
       static_targets,
       has_dynamic_resolvers,
@@ -2545,6 +2566,22 @@ var Act = class {
         handle_batch: this._handle_batch,
         on_acked: (acked) => this.emit("acked", acked),
         on_blocked: (blocked) => this.emit("blocked", blocked),
+        // Reaction-requested close (#1090). Runs the same close machinery as
+        // `app.close` (tombstone guard + archive + atomic truncate) for the
+        // targets a handler signalled via `CloseSignal`. No `correlate()` here
+        // — the drain that produced these targets has already correlated.
+        on_close: async (targets) => {
+          const close_actor = { id: "$close", name: "close" };
+          const result = await run_close_cycle(targets, {
+            reactive_events_size: this._reactive_events.size,
+            event_to_state: this._event_to_state,
+            load: this._es.load,
+            tombstone: this._es.tombstone,
+            logger: this._logger,
+            correlation: close_correlation(this._correlator, close_actor)
+          });
+          this.emit("closed", result);
+        },
         breaker: this._breaker,
         // Pass lane only when a true per-lane controller is active.
         // The all-lanes (single default) case keeps lane=undefined so
@@ -2591,27 +2628,6 @@ 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),
-      breaker: this._breaker
-    }) : void 0;
     this._notify_disposer = this._wire_notify(options.scoped?.store ?? store());
     dispose(() => this.shutdown());
   }
@@ -3105,7 +3121,6 @@ var Act = class {
    */
   start_correlations(query = {}, frequency = 1e4, callback) {
     const started = this._correlate.start_polling(query, frequency, callback);
-    this._autoclose?.start();
     return started;
   }
   /**
@@ -3127,7 +3142,6 @@ var Act = class {
    */
   stop_correlations() {
     this._correlate.stop_polling();
-    this._autoclose?.stop();
   }
   /**
    * Cancels any pending or active settle cycle.
@@ -3930,20 +3944,21 @@ 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
+    autocloses(policy) {
+      if (typeof policy === "function") {
+        throw new Error(
+          ".autocloses(fn) is no longer supported \u2014 pass a declarative policy ({ after, is, reaches, or }) or call app.close(...) from your own reaction for custom logic."
         );
-      } else {
+      }
+      if (policy === null || typeof policy !== "object") {
         throw new Error(
-          ".autocloses(...) requires a function or a policy object; got " + typeof predicate_or_policy
+          ".autocloses(...) requires a policy object; got " + typeof policy
         );
       }
-      internal.autoclose = predicate;
+      internal.autoclose = compile_autoclose_policy(
+        policy
+      );
+      internal.autoclose_after_ms = policy_min_after_ms(policy);
       return builder;
     },
     archives(archive) {