@rotorsoft/act 1.10.1 → 1.11.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,
@@ -416,32 +420,18 @@ function pii_fields(schema) {
   return fields;
 }
 function pii_split(emitted, fields) {
-  const rec = emitted.data;
-  const clean = {};
+  const data = { ...emitted.data };
   const pii = {};
-  for (const k of Object.keys(rec)) {
-    if (fields.includes(k)) pii[k] = rec[k];
-    else clean[k] = rec[k];
+  for (const f of fields) {
+    if (f in data) {
+      pii[f] = data[f];
+      delete data[f];
+    }
   }
-  return { name: emitted.name, data: clean, pii };
-}
-function pii_merge(event, fields) {
-  const data = event.data;
-  const pii = event.pii;
-  if (pii != null) {
-    return {
-      ...event,
-      data: { ...data, ...pii }
-    };
-  }
-  const shredded = { ...data };
-  for (const f of fields) shredded[f] = SHREDDED;
-  return {
-    ...event,
-    data: shredded
-  };
+  return { name: emitted.name, data, pii };
 }
 function pii_gate(event, fields, predicate, actor) {
+  if (fields.length === 0) return event;
   const data = event.data;
   if (event.pii == null) {
     const shredded = { ...data };
@@ -1868,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
@@ -2020,7 +1977,7 @@ async function load_restart_seeds(guarded, target_map, stream_info, event_to_sta
         );
         return;
       }
-      const snap2 = await load2(owner_state, stream);
+      const snap2 = await load2(owner_state, { stream });
       seed_states.set(stream, snap2.state);
     })
   );
@@ -2068,6 +2025,233 @@ 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/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;
@@ -2196,30 +2380,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");
 
@@ -2384,7 +2544,6 @@ async function scan(source, opts = {}, callback) {
           migrated = {
             ...event,
             name: migration.to,
-            // biome-ignore lint/suspicious/noExplicitAny: migration target shape is caller-defined
             data: new_data
           };
           migrated_count++;
@@ -2433,39 +2592,37 @@ async function scan(source, opts = {}, callback) {
     }
   };
 }
-async function load(me, stream, callback, asOf, actor) {
+async function load(me, target, callback) {
+  const { stream, actor, asOf } = target;
   const time_travel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
   const cached = time_travel ? void 0 : await cache2().get(stream);
   const cache_hit = !!cached;
   let state2 = cached?.state ?? (me.init ? me.init() : {});
   let patches = cached?.patches ?? 0;
   let snaps = cached?.snaps ?? 0;
-  let version = cached?.version ?? -1;
   let replayed = 0;
   let event;
   await store2().query(
-    (e) => {
-      version = e.version;
-      const typed = e;
-      event = me.view(typed, actor);
-      if (e.name === SNAP_EVENT) {
-        state2 = e.data;
+    (raw) => {
+      event = me.view(raw, actor);
+      if (event.name === SNAP_EVENT) {
+        state2 = event.data;
         snaps++;
         patches = 0;
         replayed++;
-      } else if (me.patch[e.name]) {
-        state2 = (0, import_act_patch.patch)(state2, me.patch[e.name](typed, state2));
+      } else if (me.patch[event.name]) {
+        state2 = (0, import_act_patch.patch)(state2, me.patch[event.name](event, state2));
         patches++;
         replayed++;
-      } else if (e.name !== TOMBSTONE_EVENT) {
+      } else if (event.name !== TOMBSTONE_EVENT) {
         log().warn(
-          `Skipping unknown event "${String(e.name)}" on stream "${stream}" (id=${e.id}) \u2014 no reducer in state "${me.name}"`
+          `Skipping unknown event "${String(event.name)}" on stream "${stream}" (id=${event.id}) \u2014 no reducer in state "${me.name}"`
         );
       }
       callback?.({
         event,
         state: state2,
-        version,
+        version: event.version,
         patches,
         snaps,
         cache_hit,
@@ -2478,39 +2635,43 @@ async function load(me, stream, callback, asOf, actor) {
       ...cached ? { after: cached.event_id } : { with_snaps: true, ...asOf }
     }
   );
-  if (replayed > 0 && !time_travel && event) {
+  if (replayed > 0 && !time_travel && event && !me.pii_aware) {
     await cache2().set(stream, {
       state: state2,
-      version,
+      version: event.version,
       event_id: event.id,
       patches,
       snaps
     });
   }
-  return { event, state: state2, version, patches, snaps, cache_hit, replayed };
+  return {
+    event,
+    state: state2,
+    version: event?.version ?? cached?.version ?? -1,
+    patches,
+    snaps,
+    cache_hit,
+    replayed
+  };
 }
-async function action(me, action2, target, payload, reactingTo, skipValidation = false, correlator = default_correlator) {
+async function action(me, action2, target, payload, options) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
-  const validated = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
+  const reactingTo = options?.reactingTo;
+  const correlator = options?.correlator ?? default_correlator;
+  const validated = validate(action2, payload, me.actions[action2]);
   const opts = me.options?.[action2];
   const max_retries = opts?.maxRetries ?? 0;
   for (let attempt = 0; ; attempt++) {
     try {
-      const snapshot = await load(
-        me,
-        stream,
-        void 0,
-        void 0,
-        target.actor
-      );
+      const snapshot = await load(me, { stream, actor: target.actor });
       if (snapshot.event?.name === TOMBSTONE_EVENT)
         throw new StreamClosedError(stream);
       const expected = expectedVersion ?? snapshot.event?.version;
       if (me.given) {
         const invariants = me.given[action2] || [];
-        invariants.forEach(({ valid, description }) => {
-          if (!valid(snapshot.state, actor))
+        invariants.forEach(({ valid: valid2, description }) => {
+          if (!valid2(snapshot.state, actor))
             throw new InvariantError(
               action2,
               validated,
@@ -2526,24 +2687,11 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
         return [snapshot];
       }
       const tuples = Array.isArray(result[0]) ? result : [result];
-      const deprecated = me._deprecated;
-      if (deprecated && deprecated.size > 0) {
-        const me_ = me;
-        const warned = me_._warned ?? (me_._warned = /* @__PURE__ */ new Set());
-        for (const [name] of tuples) {
-          const evt = name;
-          if (deprecated.has(evt) && !warned.has(evt)) {
-            warned.add(evt);
-            log().warn(
-              `Action "${String(action2)}" emitted deprecated event "${evt}". A newer version exists in the registry \u2014 update the action's .emit() to target the current version. (warned once per process)`
-            );
-          }
-        }
-      }
-      const emitted = tuples.map(([name, data]) => {
-        const validated2 = skipValidation ? data : validate(name, data, me.events[name]);
-        return me.message({ name, data: validated2 });
-      });
+      const valid = tuples.map(([name, data]) => ({
+        name,
+        data: validate(name, data, me.events[name])
+      }));
+      const emitted = valid.map((e) => me.message(e));
       const meta = {
         correlation: reactingTo?.meta.correlation || correlator({
           action: action2,
@@ -2584,12 +2732,13 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
         throw error;
       }
       let { state: state2, patches } = snapshot;
-      const snapshots = committed.map((event) => {
+      const snapshots = committed.map((row, i) => {
+        const event = { ...row, data: valid[i].data };
         const p = me.patch[event.name](event, state2);
         state2 = (0, import_act_patch.patch)(state2, p);
         patches++;
         return {
-          event: me.view(event, target.actor),
+          event,
           state: state2,
           version: event.version,
           patches,
@@ -2601,13 +2750,15 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
       });
       const last = snapshots.at(-1);
       const snapped = me.snap?.(last);
-      cache2().set(stream, {
-        state: last.state,
-        version: last.event.version,
-        event_id: last.event.id,
-        patches: snapped ? 0 : last.patches,
-        snaps: snapped ? last.snaps + 1 : last.snaps
-      }).catch((err) => log().error(err));
+      if (!me.pii_aware) {
+        cache2().set(stream, {
+          state: last.state,
+          version: last.event.version,
+          event_id: last.event.id,
+          patches: snapped ? 0 : last.patches,
+          snaps: snapped ? last.snaps + 1 : last.snaps
+        }).catch((err) => log().error(err));
+      }
       if (snapped) void snap(last);
       return snapshots;
     } catch (error) {
@@ -2674,15 +2825,7 @@ var traced = (inner, exit, entry) => (async (...args) => {
   return result;
 });
 function build_es(logger, correlator = default_correlator) {
-  const bound_action = (me, action_name, target, payload, reactingTo, skipValidation = false) => action(
-    me,
-    action_name,
-    target,
-    payload,
-    reactingTo,
-    skipValidation,
-    correlator
-  );
+  const bound_action = (me, action_name, target, payload, options) => action(me, action_name, target, payload, { correlator, ...options });
   if (logger.level !== "trace") {
     return {
       snap,
@@ -2701,7 +2844,7 @@ function build_es(logger, correlator = default_correlator) {
         )
       );
     }),
-    load: traced(load, (result, _me, stream, _cb, asOf) => {
+    load: traced(load, (result, _me, target) => {
       const stats = stats_marker(
         result.version,
         result.replayed,
@@ -2712,7 +2855,7 @@ function build_es(logger, correlator = default_correlator) {
         es_caption(
           "load",
           C_GREEN,
-          `${stream}${as_of_marker(asOf)} ${cache_marker(result.cache_hit)} ${stats}`
+          `${target.stream}${as_of_marker(target.asOf)} ${cache_marker(result.cache_hit)} ${stats}`
         )
       );
     }),
@@ -3012,7 +3155,7 @@ var DrainController = class {
 };
 
 // src/internal/merge.ts
-var import_zod5 = require("zod");
+var import_zod6 = require("zod");
 function base_type_name(zodType) {
   let t = zodType;
   while (typeof t.unwrap === "function") {
@@ -3021,7 +3164,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_zod6.ZodObject && incoming instanceof import_zod6.ZodObject) {
     const existing_shape = existing.shape;
     const incoming_shape = incoming.shape;
     for (const key of Object.keys(incoming_shape)) {
@@ -3200,13 +3343,10 @@ function build_handle(deps) {
     };
     for (const payload of payloads) {
       const { event, handler } = payload;
-      scoped_app.do = (action2, target, action_payload, reactingTo, skipValidation) => bound_do(
-        action2,
-        target,
-        action_payload,
-        reactingTo ?? event,
-        skipValidation
-      );
+      scoped_app.do = (action2, target, action_payload, options) => bound_do(action2, target, action_payload, {
+        ...options,
+        reactingTo: options?.reactingTo ?? event
+      });
       try {
         await handler(event, stream, scoped_app);
         at = event.id;
@@ -3343,6 +3483,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}.
@@ -3477,6 +3633,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)];
@@ -3540,6 +3697,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());
   }
@@ -3612,8 +3789,9 @@ var Act = class {
    * @param action - The name of the action to execute
    * @param target - Target specification with stream ID and actor context
    * @param payload - Action payload matching the action's schema
-   * @param reactingTo - Optional event that triggered this action (for correlation)
-   * @param skipValidation - Skip schema validation (use carefully, for performance)
+   * @param options - Per-call dispatch options ({@link DoOptions}) —
+   *   `reactingTo` to thread correlation, `correlator` to override the
+   *   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
@@ -3668,7 +3846,7 @@ var Act = class {
    *         { amount: event.data.items.length }
    *       );
    *       // To use a different correlation, pass reactingTo explicitly:
-   *       // await app.do("reduceStock", target, payload, customEvent);
+   *       // await app.do("reduceStock", target, payload, { reactingTo: customEvent });
    *     })
    *     .to("inventory-1")
    *   .build();
@@ -3678,15 +3856,14 @@ var Act = class {
    * @see {@link Snapshot} for return value structure
    * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
    */
-  async do(action2, target, payload, reactingTo, skipValidation = false) {
+  async do(action2, target, payload, options) {
     return this._scoped(async () => {
       const snapshots = await this._es.action(
         this.registry.actions[action2],
         action2,
         target,
         payload,
-        reactingTo,
-        skipValidation
+        options
       );
       if (this._reactive_events.size > 0)
         this._arm_for_event_names(
@@ -3696,7 +3873,7 @@ var Act = class {
       return snapshots;
     });
   }
-  async load(stateOrName, stream, callback, asOf, actor) {
+  async load(stateOrName, streamOrTarget, callback, asOf) {
     return this._scoped(async () => {
       let merged;
       if (typeof stateOrName === "string") {
@@ -3706,7 +3883,12 @@ var Act = class {
       } else {
         merged = this._states.get(stateOrName.name) || stateOrName;
       }
-      return await this._es.load(merged, stream, callback, asOf, actor);
+      const target = typeof streamOrTarget === "string" ? {
+        stream: streamOrTarget,
+        actor: void 0,
+        asOf
+      } : streamOrTarget;
+      return await this._es.load(merged, target, callback);
     });
   }
   /**
@@ -4026,7 +4208,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.
@@ -4047,6 +4231,7 @@ var Act = class {
    */
   stop_correlations() {
     this._correlate.stop_polling();
+    this._autoclose?.stop();
   }
   /**
    * Cancels any pending or active settle cycle.
@@ -4430,11 +4615,18 @@ function act() {
   const states = /* @__PURE__ */ new Map();
   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
+    disclosure_predicate: (state_name) => _dp.get(state_name) ?? null,
+    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();
@@ -4446,7 +4638,7 @@ function act() {
       const event_names = Object.keys(state2.events);
       const deprecated = deprecated_event_names(event_names);
       if (deprecated.size === 0) continue;
-      state2._deprecated = deprecated;
+      _de.set(state2.name, deprecated);
       for (const name of deprecated) {
         const current = current_version_of(name, event_names);
         deprecation_summary.push({
@@ -4561,6 +4753,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);
@@ -4574,18 +4768,17 @@ function act() {
             );
           }
           const disclose = state2.disclose ?? null;
-          state2.view = (event, actor) => {
-            const fields = fields_by_event.get(event.name);
-            return fields ? pii_gate(event, fields, disclose, actor) : event;
-          };
+          state2.pii_aware = true;
+          state2.view = (event, actor) => pii_gate(
+            event,
+            fields_by_event.get(event.name) ?? [],
+            disclose,
+            actor
+          );
           state2.message = (validated) => {
             const fields = fields_by_event.get(validated.name);
             return fields ? pii_split(validated, fields) : validated;
           };
-          for (const [event_name, fields] of fields_by_event) {
-            const original = state2.patch[event_name];
-            state2.patch[event_name] = (event, s) => original(pii_merge(event, fields), s);
-          }
         }
         for (const [target, original] of batch_handlers) {
           const wrapped = async (events, stream) => {
@@ -4765,9 +4958,10 @@ function state(entry) {
             init,
             patch: default_patch,
             on: {},
-            // Step delegates initialized as identity. `act().build()`
-            // overrides on states with `sensitive(...)` events to bake in
-            // the gate / split.
+            // Step delegates initialized as identity, `pii_aware` false.
+            // `act().build()` flips both on states with `sensitive(...)`
+            // events to bake in the gate / split and gate the cache write.
+            pii_aware: false,
             view: (event) => event,
             message: (validated) => validated
           };
@@ -4828,6 +5022,24 @@ function action_builder(state2) {
       internal.disclose = disclose;
       return builder;
     },
+    autocloses(predicate) {
+      if (typeof predicate !== "function") {
+        throw new Error(
+          ".autocloses(predicate) requires a function; got " + typeof predicate
+        );
+      }
+      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;
     }
@@ -5004,6 +5216,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,
@@ -5035,6 +5250,7 @@ function write_line(writer, line) {
   log,
   port,
   projection,
+  resolveAutocloseConfig,
   scoped,
   sensitive,
   sleep,