@rotorsoft/act 0.37.0 → 0.39.0

package/dist/index.js

@@ -1,3 +1,24 @@
+import {
+  ConsoleLogger,
+  ExitCodes,
+  InMemoryCache,
+  InMemoryStore,
+  LruSet,
+  PackageSchema,
+  SNAP_EVENT,
+  TOMBSTONE_EVENT,
+  cache,
+  config,
+  dispose,
+  disposeAndExit,
+  extend,
+  log,
+  port,
+  scoped,
+  sleep,
+  store,
+  validate
+} from "./chunk-RHS57BUR.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -14,844 +35,7 @@ import {
   ValidationError,
   ZodEmpty
 } from "./chunk-AGWZY6YT.js";
-
-// src/adapters/console-logger.ts
-var LEVEL_VALUES = {
-  fatal: 60,
-  error: 50,
-  warn: 40,
-  info: 30,
-  debug: 20,
-  trace: 10
-};
-var LEVEL_COLORS = {
-  fatal: "\x1B[41m\x1B[37m",
-  // white on red bg
-  error: "\x1B[31m",
-  // red
-  warn: "\x1B[33m",
-  // yellow
-  info: "\x1B[32m",
-  // green
-  debug: "\x1B[36m",
-  // cyan
-  trace: "\x1B[90m"
-  // gray
-};
-var RESET = "\x1B[0m";
-var noop = () => {
-};
-var ConsoleLogger = class _ConsoleLogger {
-  level;
-  _pretty;
-  fatal;
-  error;
-  warn;
-  info;
-  debug;
-  trace;
-  constructor(options = {}) {
-    const {
-      level = "info",
-      pretty = process.env.NODE_ENV !== "production",
-      bindings
-    } = options;
-    this._pretty = pretty;
-    this.level = level;
-    const threshold = LEVEL_VALUES[level] ?? 30;
-    const write = pretty ? this._prettyWrite.bind(this, bindings) : this._jsonWrite.bind(this, bindings);
-    this.fatal = write.bind(this, "fatal", 60);
-    this.error = threshold <= 50 ? write.bind(this, "error", 50) : noop;
-    this.warn = threshold <= 40 ? write.bind(this, "warn", 40) : noop;
-    this.info = threshold <= 30 ? write.bind(this, "info", 30) : noop;
-    this.debug = threshold <= 20 ? write.bind(this, "debug", 20) : noop;
-    this.trace = threshold <= 10 ? write.bind(this, "trace", 10) : noop;
-  }
-  /** No-op — `console.log` has no resources to release. */
-  async dispose() {
-  }
-  /** @inheritDoc */
-  child(bindings) {
-    return new _ConsoleLogger({
-      level: this.level,
-      pretty: this._pretty,
-      bindings
-    });
-  }
-  _jsonWrite(bindings, level, _num, objOrMsg, msg) {
-    let obj;
-    let message;
-    if (typeof objOrMsg === "string") {
-      message = objOrMsg;
-      obj = {};
-    } else if (objOrMsg !== null && typeof objOrMsg === "object") {
-      message = msg;
-      obj = { ...objOrMsg };
-    } else {
-      message = msg;
-      obj = { value: objOrMsg };
-    }
-    const entry = Object.assign({ level, time: Date.now() }, bindings, obj);
-    if (message) entry.msg = message;
-    let line;
-    try {
-      line = JSON.stringify(entry);
-    } catch {
-      line = JSON.stringify({
-        level,
-        time: entry.time,
-        msg: message ?? "[unserializable]",
-        unserializable: true
-      });
-    }
-    process.stdout.write(line + "\n");
-  }
-  _prettyWrite(bindings, level, _num, objOrMsg, msg) {
-    const color = LEVEL_COLORS[level];
-    const tag = `${color}${level.toUpperCase().padEnd(5)}${RESET}`;
-    const ts = (/* @__PURE__ */ new Date()).toISOString().slice(11, 23);
-    let message;
-    let data;
-    if (typeof objOrMsg === "string") {
-      message = objOrMsg;
-    } else {
-      message = msg ?? "";
-      if (objOrMsg !== void 0 && objOrMsg !== null) {
-        try {
-          data = JSON.stringify(objOrMsg);
-        } catch {
-          data = "[unserializable]";
-        }
-      }
-    }
-    const bindStr = bindings && Object.keys(bindings).length ? ` ${JSON.stringify(bindings)}` : "";
-    const parts = [ts, tag, message, data, bindStr].filter(Boolean);
-    process.stdout.write(parts.join(" ") + "\n");
-  }
-};
-
-// src/lru-map.ts
-var LruMap = class {
-  constructor(_maxSize) {
-    this._maxSize = _maxSize;
-  }
-  _entries = /* @__PURE__ */ new Map();
-  get(key) {
-    const v = this._entries.get(key);
-    if (v === void 0) return void 0;
-    this._entries.delete(key);
-    this._entries.set(key, v);
-    return v;
-  }
-  has(key) {
-    return this._entries.has(key);
-  }
-  set(key, value) {
-    this._entries.delete(key);
-    if (this._entries.size >= this._maxSize) {
-      const oldest = this._entries.keys().next().value;
-      this._entries.delete(oldest);
-    }
-    this._entries.set(key, value);
-  }
-  delete(key) {
-    return this._entries.delete(key);
-  }
-  clear() {
-    this._entries.clear();
-  }
-  get size() {
-    return this._entries.size;
-  }
-};
-var LruSet = class {
-  _map;
-  constructor(maxSize) {
-    this._map = new LruMap(maxSize);
-  }
-  has(value) {
-    return this._map.has(value);
-  }
-  add(value) {
-    this._map.set(value, true);
-  }
-  delete(value) {
-    return this._map.delete(value);
-  }
-  clear() {
-    this._map.clear();
-  }
-  get size() {
-    return this._map.size;
-  }
-};
-
-// src/adapters/in-memory-cache.ts
-var InMemoryCache = class {
-  // CacheEntry<any> lets `get<TState>` and `set<TState>` flow without casts:
-  // any is bidirectionally compatible with the per-call TState binding, while
-  // the public Cache interface still presents a typed surface to callers.
-  _entries;
-  constructor(options) {
-    this._entries = new LruMap(options?.maxSize ?? 1e3);
-  }
-  /** @inheritDoc */
-  async get(stream) {
-    return this._entries.get(stream);
-  }
-  /** @inheritDoc */
-  async set(stream, entry) {
-    this._entries.set(stream, entry);
-  }
-  /** @inheritDoc */
-  async invalidate(stream) {
-    this._entries.delete(stream);
-  }
-  /** @inheritDoc */
-  async clear() {
-    this._entries.clear();
-  }
-  /** @inheritDoc */
-  async dispose() {
-    this._entries.clear();
-  }
-  /** Current number of entries held by the LRU. */
-  get size() {
-    return this._entries.size;
-  }
-};
-
-// src/utils.ts
-import { prettifyError, ZodError } from "zod";
-
-// src/config.ts
-import * as fs from "fs";
-import { z } from "zod";
-var PackageSchema = z.object({
-  name: z.string().min(1),
-  version: z.string().min(1),
-  description: z.string().min(1).optional(),
-  author: z.object({ name: z.string().min(1), email: z.string().optional() }).optional().or(z.string().min(1)).optional(),
-  license: z.string().min(1).optional(),
-  dependencies: z.record(z.string(), z.string()).optional()
-});
-var FALLBACK_PACKAGE = {
-  name: "act-fallback",
-  version: "0.0.0-fallback",
-  description: "Synthetic fallback \u2014 package.json could not be loaded"
-};
-var getPackage = () => {
-  try {
-    const raw = fs.readFileSync("package.json");
-    return JSON.parse(raw.toString());
-  } catch (err) {
-    pkgLoadError = err;
-    return FALLBACK_PACKAGE;
-  }
-};
-var pkgLoadError;
-var BaseSchema = PackageSchema.extend({
-  env: z.enum(Environments),
-  logLevel: z.enum(LogLevels),
-  logSingleLine: z.boolean(),
-  sleepMs: z.number().int().min(0).max(5e3)
-});
-var { NODE_ENV, LOG_LEVEL, LOG_SINGLE_LINE, SLEEP_MS } = process.env;
-var env = NODE_ENV || "development";
-var logLevel = LOG_LEVEL || (NODE_ENV === "test" ? "fatal" : NODE_ENV === "production" ? "info" : "trace");
-var logSingleLine = (LOG_SINGLE_LINE || "true") === "true";
-var sleepMs = parseInt(NODE_ENV === "test" ? "0" : SLEEP_MS ?? "100", 10);
-var pkg = getPackage();
-var _validated;
-var config = () => {
-  if (!_validated) {
-    _validated = extend(
-      { ...pkg, env, logLevel, logSingleLine, sleepMs },
-      BaseSchema
-    );
-    if (pkgLoadError) {
-      const msg = pkgLoadError instanceof Error ? pkgLoadError.message : typeof pkgLoadError === "string" ? pkgLoadError : "unknown error";
-      log().warn(
-        `[act] Could not read package.json (${msg}); using synthetic name="${FALLBACK_PACKAGE.name}" version="${FALLBACK_PACKAGE.version}".`
-      );
-      pkgLoadError = void 0;
-    }
-  }
-  return _validated;
-};
-
-// src/utils.ts
-var validate = (target, payload, schema) => {
-  try {
-    return schema ? schema.parse(payload) : payload;
-  } catch (error) {
-    if (error instanceof ZodError) {
-      throw new ValidationError(target, payload, prettifyError(error));
-    }
-    throw new ValidationError(target, payload, error);
-  }
-};
-var extend = (source, schema, target) => {
-  const value = validate("config", source, schema);
-  return { ...target, ...value };
-};
-async function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms ?? config().sleepMs));
-}
-
-// src/adapters/in-memory-store.ts
-var InMemoryStream = class {
-  constructor(stream, source, priority = 0) {
-    this.stream = stream;
-    this.source = source;
-    this._priority = priority;
-  }
-  _at = -1;
-  _retry = -1;
-  _blocked = false;
-  _error = "";
-  _leased_by = void 0;
-  _leased_until = void 0;
-  _priority = 0;
-  get priority() {
-    return this._priority;
-  }
-  /**
-   * Bump the priority via {@link subscribe}: keeps the maximum across
-   * reactions so the highest-priority registrant wins.
-   */
-  bumpPriority(priority) {
-    if (priority > this._priority) this._priority = priority;
-  }
-  /**
-   * Set the priority outright via {@link prioritize}: operator
-   * runtime override that ignores the build-time `max()` invariant.
-   */
-  setPriority(priority) {
-    this._priority = priority;
-  }
-  get is_available() {
-    return !this._blocked && (!this._leased_until || this._leased_until <= /* @__PURE__ */ new Date());
-  }
-  get at() {
-    return this._at;
-  }
-  get retry() {
-    return this._retry;
-  }
-  get blocked() {
-    return this._blocked;
-  }
-  get error() {
-    return this._error;
-  }
-  get leased_by() {
-    return this._leased_by;
-  }
-  get leased_until() {
-    return this._leased_until;
-  }
-  /**
-   * Attempt to lease this stream for processing.
-   * @param lease - The lease request.
-   * @param millis - Lease duration in milliseconds.
-   * @returns The granted lease or undefined if blocked.
-   */
-  lease(lease, millis) {
-    if (millis > 0) {
-      this._leased_by = lease.by;
-      this._leased_until = new Date(Date.now() + millis);
-    }
-    this._retry = this._retry + 1;
-    return {
-      stream: this.stream,
-      source: this.source,
-      at: lease.at,
-      by: lease.by,
-      retry: this._retry,
-      lagging: lease.lagging
-    };
-  }
-  /**
-   * Acknowledge completion of processing for this stream.
-   * @param lease - The lease request.
-   */
-  ack(lease) {
-    if (this._leased_by === lease.by) {
-      this._leased_by = void 0;
-      this._leased_until = void 0;
-      this._at = lease.at;
-      this._retry = -1;
-      return {
-        stream: this.stream,
-        source: this.source,
-        at: this._at,
-        by: lease.by,
-        retry: this._retry,
-        lagging: lease.lagging
-      };
-    }
-  }
-  /**
-   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
-   * @param lease - The lease request.
-   * @param error Blocked error message.
-   */
-  block(lease, error) {
-    if (this._leased_by === lease.by) {
-      this._blocked = true;
-      this._error = error;
-      return {
-        stream: this.stream,
-        source: this.source,
-        at: this._at,
-        by: this._leased_by,
-        retry: this._retry,
-        error: this._error,
-        lagging: lease.lagging
-      };
-    }
-  }
-  /**
-   * Reset this stream's watermark and state for replay. The retry counter
-   * resets to -1 to match the constructor + ack() invariant ("released
-   * stream"); the next claim() bumps it to 0 (first attempt).
-   */
-  reset() {
-    this._at = -1;
-    this._retry = -1;
-    this._blocked = false;
-    this._error = "";
-    this._leased_by = void 0;
-    this._leased_until = void 0;
-  }
-};
-var InMemoryStore = class {
-  // stored events
-  _events = [];
-  // stored stream positions and other metadata
-  _streams = /* @__PURE__ */ new Map();
-  // last committed version per stream — O(1) replacement for filter-on-commit
-  _streamVersions = /* @__PURE__ */ new Map();
-  // max non-snapshot event id per stream — drives the source-pattern probe in claim()
-  // without scanning the full event log.
-  _maxEventIdByStream = /* @__PURE__ */ new Map();
-  // global max non-snapshot event id — fast pre-check for source-less streams in claim()
-  _maxNonSnapEventId = -1;
-  _resetIndexes() {
-    this._events.length = 0;
-    this._streamVersions.clear();
-    this._maxEventIdByStream.clear();
-    this._maxNonSnapEventId = -1;
-  }
-  /**
-   * Dispose of the store and clear all events.
-   * @returns Promise that resolves when disposal is complete.
-   */
-  async dispose() {
-    await sleep();
-    this._resetIndexes();
-  }
-  /**
-   * Seed the store with initial data (no-op for in-memory).
-   * @returns Promise that resolves when seeding is complete.
-   */
-  async seed() {
-    await sleep();
-  }
-  /**
-   * Drop all data from the store.
-   * @returns Promise that resolves when the store is cleared.
-   */
-  async drop() {
-    await sleep();
-    this._resetIndexes();
-    this._streams = /* @__PURE__ */ new Map();
-  }
-  in_query(query, e) {
-    if (query.stream) {
-      if (query.stream_exact) {
-        if (e.stream !== query.stream) return false;
-      } else if (!RegExp(`^${query.stream}$`).test(e.stream)) return false;
-    }
-    if (query.names && !query.names.includes(e.name)) return false;
-    if (query.correlation && e.meta?.correlation !== query.correlation)
-      return false;
-    if (e.name === SNAP_EVENT && !query.with_snaps) return false;
-    return true;
-  }
-  /**
-   * Query events in the store, optionally filtered by query options.
-   * @param callback - Function to call for each event.
-   * @param query - Optional query options.
-   * @returns The number of events processed.
-   */
-  async query(callback, query) {
-    await sleep();
-    let count = 0;
-    if (query?.backward) {
-      let i = (query?.before || this._events.length) - 1;
-      while (i >= 0) {
-        const e = this._events[i--];
-        if (query && !this.in_query(query, e)) continue;
-        if (query?.created_before && e.created >= query.created_before)
-          continue;
-        if (query.after && e.id <= query.after) break;
-        if (query.created_after && e.created <= query.created_after) break;
-        callback(e);
-        count++;
-        if (query?.limit && count >= query.limit) break;
-      }
-    } else {
-      let i = (query?.after ?? -1) + 1;
-      while (i < this._events.length) {
-        const e = this._events[i++];
-        if (query && !this.in_query(query, e)) continue;
-        if (query?.created_after && e.created <= query.created_after) continue;
-        if (query?.before && e.id >= query.before) break;
-        if (query?.created_before && e.created >= query.created_before) break;
-        callback(e);
-        count++;
-        if (query?.limit && count >= query.limit) break;
-      }
-    }
-    return count;
-  }
-  /**
-   * Commit one or more events to a stream.
-   * @param stream - The stream name.
-   * @param msgs - The events/messages to commit.
-   * @param meta - Event metadata.
-   * @param expectedVersion - Optional optimistic concurrency check.
-   * @returns The committed events with metadata.
-   * @throws ConcurrencyError if expectedVersion does not match.
-   */
-  async commit(stream, msgs, meta, expectedVersion) {
-    await sleep();
-    const currentVersion = this._streamVersions.get(stream) ?? -1;
-    if (typeof expectedVersion === "number" && currentVersion !== expectedVersion) {
-      throw new ConcurrencyError(
-        stream,
-        currentVersion,
-        msgs,
-        expectedVersion
-      );
-    }
-    let version = currentVersion + 1;
-    let lastNonSnapId = -1;
-    const committed = msgs.map(({ name, data }) => {
-      const c = {
-        id: this._events.length,
-        stream,
-        version,
-        created: /* @__PURE__ */ new Date(),
-        name,
-        data,
-        meta
-      };
-      this._events.push(c);
-      if (name !== SNAP_EVENT) lastNonSnapId = c.id;
-      version++;
-      return c;
-    });
-    this._streamVersions.set(stream, version - 1);
-    if (lastNonSnapId >= 0) {
-      this._maxEventIdByStream.set(stream, lastNonSnapId);
-      this._maxNonSnapEventId = lastNonSnapId;
-    }
-    return committed;
-  }
-  /**
-   * Atomically discovers and leases streams for processing.
-   * Fuses poll + lease into a single operation.
-   * @param lagging - Max streams from lagging frontier.
-   * @param leading - Max streams from leading frontier.
-   * @param by - Lease holder identifier.
-   * @param millis - Lease duration in milliseconds.
-   * @returns Granted leases.
-   */
-  async claim(lagging, leading, by, millis) {
-    await sleep();
-    const sourceRegex = /* @__PURE__ */ new Map();
-    const getRegex = (source) => {
-      let re = sourceRegex.get(source);
-      if (!re) {
-        re = new RegExp(source);
-        sourceRegex.set(source, re);
-      }
-      return re;
-    };
-    const hasWork = (s) => {
-      if (s.at < 0) return true;
-      if (!s.source) return s.at < this._maxNonSnapEventId;
-      const re = getRegex(s.source);
-      for (const [streamName, maxId] of this._maxEventIdByStream) {
-        if (maxId > s.at && re.test(streamName)) return true;
-      }
-      return false;
-    };
-    const available = [...this._streams.values()].filter(
-      (s) => s.is_available && hasWork(s)
-    );
-    const lag = available.sort((a, b) => b.priority - a.priority || a.at - b.at).slice(0, lagging).map((s) => ({
-      stream: s.stream,
-      source: s.source,
-      at: s.at,
-      lagging: true
-    }));
-    const lead = available.sort((a, b) => b.at - a.at).slice(0, leading).map((s) => ({
-      stream: s.stream,
-      source: s.source,
-      at: s.at,
-      lagging: false
-    }));
-    const seen = /* @__PURE__ */ new Set();
-    const combined = [...lag, ...lead].filter((p) => {
-      if (seen.has(p.stream)) return false;
-      seen.add(p.stream);
-      return true;
-    });
-    return combined.map(
-      (p) => this._streams.get(p.stream)?.lease({ ...p, by, retry: 0 }, millis)
-    ).filter((l) => !!l);
-  }
-  /**
-   * Registers streams for event processing. When the same stream is
-   * resubscribed with a different priority, the **maximum** wins — so
-   * the highest-priority registered reaction sets the scheduling lane.
-   * Use {@link prioritize} for operator runtime overrides.
-   *
-   * @param streams - Streams to register with optional source + priority.
-   * @returns subscribed count and current max watermark.
-   */
-  async subscribe(streams) {
-    await sleep();
-    let subscribed = 0;
-    for (const { stream, source, priority = 0 } of streams) {
-      const existing = this._streams.get(stream);
-      if (existing) {
-        existing.bumpPriority(priority);
-      } else {
-        this._streams.set(stream, new InMemoryStream(stream, source, priority));
-        subscribed++;
-      }
-    }
-    let watermark = -1;
-    for (const s of this._streams.values()) {
-      if (s.at > watermark) watermark = s.at;
-    }
-    return { subscribed, watermark };
-  }
-  /**
-   * Acknowledge completion of processing for leased streams.
-   * @param leases - Leases to acknowledge, including last processed watermark and lease holder.
-   */
-  async ack(leases) {
-    await sleep();
-    return leases.map((l) => this._streams.get(l.stream)?.ack(l)).filter((l) => !!l);
-  }
-  /**
-   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
-   * @param leases - Leases to block, including lease holder and last error message.
-   * @returns Blocked leases.
-   */
-  async block(leases) {
-    await sleep();
-    return leases.map((l) => this._streams.get(l.stream)?.block(l, l.error)).filter((l) => !!l);
-  }
-  /**
-   * Reset watermarks for the given streams to -1, clearing retry, blocked,
-   * error, and lease state so they can be replayed from the beginning.
-   * @param streams - Stream names to reset.
-   * @returns Count of streams that were actually reset.
-   */
-  async reset(streams) {
-    await sleep();
-    let count = 0;
-    for (const name of streams) {
-      const s = this._streams.get(name);
-      if (s) {
-        s.reset();
-        count++;
-      }
-    }
-    return count;
-  }
-  /**
-   * Bulk-update priority of streams matching `filter`. Mirrors
-   * {@link query_streams}'s filter semantics — see {@link Store.prioritize}.
-   * Unlike {@link subscribe} (which keeps `max()` of registered
-   * priorities), this sets the priority outright — operator override
-   * for the build-time scheduling policy.
-   *
-   * @returns Count of streams whose priority changed.
-   */
-  async prioritize(filter, priority) {
-    await sleep();
-    const streamRe = filter.stream && !filter.stream_exact ? new RegExp(`^${filter.stream}$`) : void 0;
-    const sourceRe = filter.source && !filter.source_exact ? new RegExp(`^${filter.source}$`) : void 0;
-    let count = 0;
-    for (const s of this._streams.values()) {
-      if (filter.stream !== void 0) {
-        if (filter.stream_exact ? s.stream !== filter.stream : !streamRe.test(s.stream))
-          continue;
-      }
-      if (filter.source !== void 0) {
-        if (s.source === void 0) continue;
-        if (filter.source_exact ? s.source !== filter.source : !sourceRe.test(s.source))
-          continue;
-      }
-      if (filter.blocked !== void 0 && s.blocked !== filter.blocked)
-        continue;
-      if (s.priority !== priority) {
-        s.setPriority(priority);
-        count++;
-      }
-    }
-    return count;
-  }
-  /**
-   * Streams registered subscription positions to the callback, ordered by
-   * stream name. Returns the highest event id in the store and the count
-   * of positions emitted.
-   */
-  async query_streams(callback, query) {
-    await sleep();
-    const limit = query?.limit ?? 100;
-    const after = query?.after;
-    const blocked = query?.blocked;
-    const streamRe = query?.stream && !query.stream_exact ? new RegExp(`^${query.stream}$`) : void 0;
-    const sourceRe = query?.source && !query.source_exact ? new RegExp(`^${query.source}$`) : void 0;
-    const sorted = [...this._streams.values()].sort(
-      (a, b) => a.stream.localeCompare(b.stream)
-    );
-    let count = 0;
-    for (const s of sorted) {
-      if (after !== void 0 && s.stream <= after) continue;
-      if (query?.stream !== void 0) {
-        if (query.stream_exact ? s.stream !== query.stream : !streamRe.test(s.stream))
-          continue;
-      }
-      if (query?.source !== void 0) {
-        if (s.source === void 0) continue;
-        if (query.source_exact ? s.source !== query.source : !sourceRe.test(s.source))
-          continue;
-      }
-      if (blocked !== void 0 && s.blocked !== blocked) continue;
-      callback({
-        stream: s.stream,
-        source: s.source,
-        at: s.at,
-        retry: s.retry,
-        blocked: s.blocked,
-        error: s.error,
-        priority: s.priority,
-        leased_by: s.leased_by,
-        leased_until: s.leased_until
-      });
-      count++;
-      if (count >= limit) break;
-    }
-    return { maxEventId: this._events.length - 1, count };
-  }
-  /**
-   * Atomically truncates streams and seeds each with a snapshot or tombstone.
-   * @param targets - Streams to truncate with optional snapshot state and meta.
-   * @returns Map keyed by stream name, each entry with `deleted` count and `committed` event.
-   */
-  async truncate(targets) {
-    await sleep();
-    const deletedCounts = /* @__PURE__ */ new Map();
-    const streamSet = new Set(targets.map((t) => t.stream));
-    for (const e of this._events) {
-      if (streamSet.has(e.stream)) {
-        deletedCounts.set(e.stream, (deletedCounts.get(e.stream) ?? 0) + 1);
-      }
-    }
-    this._events = this._events.filter((e) => !streamSet.has(e.stream));
-    for (const stream of streamSet) {
-      this._streams.delete(stream);
-      this._streamVersions.delete(stream);
-      this._maxEventIdByStream.delete(stream);
-    }
-    const result = /* @__PURE__ */ new Map();
-    for (const { stream, snapshot, meta } of targets) {
-      const event = {
-        id: this._events.length,
-        stream,
-        version: 0,
-        created: /* @__PURE__ */ new Date(),
-        name: snapshot !== void 0 ? SNAP_EVENT : TOMBSTONE_EVENT,
-        data: snapshot ?? {},
-        meta: meta ?? { correlation: "", causation: {} }
-      };
-      this._events.push(event);
-      this._streamVersions.set(stream, 0);
-      if (event.name !== SNAP_EVENT) {
-        this._maxEventIdByStream.set(stream, event.id);
-      }
-      result.set(stream, {
-        deleted: deletedCounts.get(stream) ?? 0,
-        committed: event
-      });
-    }
-    let max = -1;
-    for (const id of this._maxEventIdByStream.values()) if (id > max) max = id;
-    this._maxNonSnapEventId = max;
-    return result;
-  }
-};
-
-// src/ports.ts
-var ExitCodes = ["ERROR", "EXIT"];
-var adapters = /* @__PURE__ */ new Map();
-function port(injector) {
-  return (adapter) => {
-    if (!adapters.has(injector.name)) {
-      const injected = injector(adapter);
-      adapters.set(injector.name, injected);
-      log().info(`[act] + ${injector.name}:${injected.constructor.name}`);
-    }
-    return adapters.get(injector.name);
-  };
-}
-var log = port(function log2(adapter) {
-  const cfg = config();
-  return adapter || new ConsoleLogger({
-    level: cfg.logLevel,
-    pretty: cfg.env !== "production"
-  });
-});
-var store = port(function store2(adapter) {
-  return adapter || new InMemoryStore();
-});
-var cache = port(function cache2(adapter) {
-  return adapter || new InMemoryCache();
-});
-var disposers = [];
-async function disposeAndExit(code = "EXIT") {
-  if (code === "ERROR" && config().env === "production") {
-    log().warn(
-      "disposeAndExit('ERROR') ignored in production \u2014 process kept alive"
-    );
-    return;
-  }
-  for (const disposer of [...disposers].reverse()) {
-    await disposer();
-  }
-  for (const adapter of [...adapters.values()].reverse()) {
-    await adapter.dispose();
-    log().info(`[act] - ${adapter.constructor.name}`);
-  }
-  adapters.clear();
-  config().env !== "test" && process.exit(code === "ERROR" ? 1 : 0);
-}
-function dispose(disposer) {
-  disposer && disposers.push(disposer);
-  return disposeAndExit;
-}
-var SNAP_EVENT = "__snapshot__";
-var TOMBSTONE_EVENT = "__tombstone__";
+import "./chunk-5WRI5ZAA.js";
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -2031,6 +1215,7 @@ var Act = class {
     this.registry = registry;
     this._states = _states;
     this._batch_handlers = batchHandlers;
+    this._scoped = options.scoped ? (fn) => scoped.run(options.scoped, fn) : (fn) => fn();
     this._es = buildEs(this._logger);
     this._cd = buildDrain(this._logger);
     this._handle = buildHandle({
@@ -2076,14 +1261,8 @@ var Act = class {
       },
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
-    this._notify_disposer = this._wireNotify();
-    dispose(async () => {
-      this._emitter.removeAllListeners();
-      this.stop_correlations();
-      this.stop_settling();
-      const disposer = await this._notify_disposer;
-      if (disposer) await disposer();
-    });
+    this._notify_disposer = this._wireNotify(options.scoped?.store ?? store());
+    dispose(() => this.shutdown());
   }
   _emitter = new EventEmitter();
   /** Event names with at least one registered reaction (computed at build time) */
@@ -2145,6 +1324,11 @@ var Act = class {
   _event_to_state;
   /** Logger resolved at construction time (after user port configuration) */
   _logger = log();
+  /** Wraps a public-method body so internal `store()`/`cache()` resolve to the
+   * per-Act ports (ACT-501). No-op when the Act is unscoped — so the singleton
+   * path keeps reading fresh `store()`/`cache()` per call, which matters for
+   * tests that dispose and re-seed mid-suite. */
+  _scoped;
   /** Pre-bound IAct methods reused across drain cycles. Only `do` varies per
    * payload (it captures the triggering event for reactingTo auto-inject). */
   _bound_do = this.do.bind(this);
@@ -2154,15 +1338,38 @@ var Act = class {
   /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
   _handle;
   _handle_batch;
+  /** True after the first `shutdown()` call. Guards idempotency. */
+  _shutdown_promise;
+  /**
+   * Per-instance teardown: remove lifecycle listeners, stop the
+   * correlation worker, cancel any pending settle cycle, and tear
+   * down the cross-process notify subscription.
+   *
+   * Idempotent — repeated calls return the same promise. Registered
+   * automatically with the global `dispose()` registry at construction,
+   * so process-wide `dispose()()` covers it; test helpers (or operators
+   * that mint short-lived Acts) call it explicitly for prompt cleanup.
+   */
+  shutdown() {
+    if (!this._shutdown_promise) {
+      this._shutdown_promise = (async () => {
+        this._emitter.removeAllListeners();
+        this.stop_correlations();
+        this.stop_settling();
+        const disposer = await this._notify_disposer;
+        if (disposer) await disposer();
+      })();
+    }
+    return this._shutdown_promise;
+  }
   /**
    * Subscribe to {@link Store.notify} when both the store and the
    * registry support it. Returns the disposer (or `undefined` when no
    * subscription was made). Errors during subscription are logged but
    * never thrown — `notify` is a hint, not a contract.
    */
-  async _wireNotify() {
+  async _wireNotify(s) {
     if (this._reactive_events.size === 0) return void 0;
-    const s = store();
     if (!s.notify) return void 0;
     try {
       return await s.notify((notification) => {
@@ -2266,35 +1473,39 @@ var Act = class {
    * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
    */
   async do(action2, target, payload, reactingTo, skipValidation = false) {
-    const snapshots = await this._es.action(
-      this.registry.actions[action2],
-      action2,
-      target,
-      payload,
-      reactingTo,
-      skipValidation
-    );
-    if (this._reactive_events.size > 0) {
-      for (const snap2 of snapshots) {
-        if (snap2.event?.name && this._reactive_events.has(snap2.event.name)) {
-          this._drain.arm();
-          break;
+    return this._scoped(async () => {
+      const snapshots = await this._es.action(
+        this.registry.actions[action2],
+        action2,
+        target,
+        payload,
+        reactingTo,
+        skipValidation
+      );
+      if (this._reactive_events.size > 0) {
+        for (const snap2 of snapshots) {
+          if (snap2.event?.name && this._reactive_events.has(snap2.event.name)) {
+            this._drain.arm();
+            break;
+          }
         }
       }
-    }
-    this.emit("committed", snapshots);
-    return snapshots;
+      this.emit("committed", snapshots);
+      return snapshots;
+    });
   }
   async load(stateOrName, stream, callback, asOf) {
-    let merged;
-    if (typeof stateOrName === "string") {
-      const found = this._states.get(stateOrName);
-      if (!found) throw new Error(`State "${stateOrName}" not found`);
-      merged = found;
-    } else {
-      merged = this._states.get(stateOrName.name) || stateOrName;
-    }
-    return await this._es.load(merged, stream, callback, asOf);
+    return this._scoped(async () => {
+      let merged;
+      if (typeof stateOrName === "string") {
+        const found = this._states.get(stateOrName);
+        if (!found) throw new Error(`State "${stateOrName}" not found`);
+        merged = found;
+      } else {
+        merged = this._states.get(stateOrName.name) || stateOrName;
+      }
+      return await this._es.load(merged, stream, callback, asOf);
+    });
   }
   /**
    * Queries the event store for events matching a filter.
@@ -2343,14 +1554,16 @@ var Act = class {
    * @see {@link query_array} for loading events into memory
    */
   async query(query, callback) {
-    let first;
-    let last;
-    const count = await store().query((e) => {
-      if (!first) first = e;
-      last = e;
-      callback?.(e);
-    }, query);
-    return { first, last, count };
+    return this._scoped(async () => {
+      let first;
+      let last;
+      const count = await store().query((e) => {
+        if (!first) first = e;
+        last = e;
+        callback?.(e);
+      }, query);
+      return { first, last, count };
+    });
   }
   /**
    * Queries the event store and returns all matching events in memory.
@@ -2379,9 +1592,11 @@ var Act = class {
    * @see {@link query} for large result sets
    */
   async query_array(query) {
-    const events = [];
-    await store().query((e) => events.push(e), query);
-    return events;
+    return this._scoped(async () => {
+      const events = [];
+      await store().query((e) => events.push(e), query);
+      return events;
+    });
   }
   /**
    * Processes pending reactions by draining uncommitted events from the event store.
@@ -2421,7 +1636,7 @@ var Act = class {
    * @see {@link start_correlations} for automatic correlation
    */
   async drain(options = {}) {
-    return this._drain.drain(options);
+    return this._scoped(() => this._drain.drain(options));
   }
   /**
    * Discovers and registers new streams dynamically based on reaction resolvers.
@@ -2469,7 +1684,7 @@ var Act = class {
    * @see {@link stop_correlations} to stop automatic correlation
    */
   async correlate(query = { after: -1, limit: 10 }) {
-    return this._correlate.correlate(query);
+    return this._scoped(() => this._correlate.correlate(query));
   }
   /**
    * Starts automatic periodic correlation worker for discovering new streams.
@@ -2590,9 +1805,11 @@ var Act = class {
    * @see {@link settle} for the debounced full-catch-up loop
    */
   async reset(streams) {
-    const count = await store().reset(streams);
-    if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
-    return count;
+    return this._scoped(async () => {
+      const count = await store().reset(streams);
+      if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
+      return count;
+    });
   }
   /**
    * Bulk-update scheduling priority for streams matching `filter`.
@@ -2633,7 +1850,7 @@ var Act = class {
    * @see {@link claim} for how priority biases scheduling
    */
   async prioritize(filter, priority) {
-    return store().prioritize(filter, priority);
+    return this._scoped(() => store().prioritize(filter, priority));
   }
   /**
    * Close the books — guard, archive, truncate, and optionally restart streams.
@@ -2670,16 +1887,18 @@ var Act = class {
    */
   async close(targets) {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
-    await this.correlate({ limit: 1e3 });
-    const result = await runCloseCycle(targets, {
-      reactiveEventsSize: this._reactive_events.size,
-      eventToState: this._event_to_state,
-      load: this._es.load,
-      tombstone: this._es.tombstone,
-      logger: this._logger
+    return this._scoped(async () => {
+      await this.correlate({ limit: 1e3 });
+      const result = await runCloseCycle(targets, {
+        reactiveEventsSize: this._reactive_events.size,
+        eventToState: this._event_to_state,
+        load: this._es.load,
+        tombstone: this._es.tombstone,
+        logger: this._logger
+      });
+      this.emit("closed", result);
+      return result;
     });
-    this.emit("closed", result);
-    return result;
   }
   /**
    * Debounced, non-blocking correlate→drain cycle.
@@ -2733,6 +1952,41 @@ function act() {
   };
   const pendingProjections = [];
   const batchHandlers = /* @__PURE__ */ new Map();
+  let _built = false;
+  const finalizeDeprecations = () => {
+    const deprecationSummary = [];
+    for (const state2 of states.values()) {
+      const eventNames = Object.keys(state2.events);
+      const deprecated = deprecatedEventNames(eventNames);
+      if (deprecated.size === 0) continue;
+      state2._deprecated = deprecated;
+      for (const name of deprecated) {
+        const current = currentVersionOf(name, eventNames);
+        deprecationSummary.push({
+          stateName: state2.name,
+          deprecated: name,
+          current
+        });
+      }
+      for (const [actionName, handler] of Object.entries(state2.on)) {
+        const staticTarget = handler?._staticEmit;
+        if (staticTarget && deprecated.has(staticTarget)) {
+          const current = currentVersionOf(staticTarget, eventNames);
+          throw new Error(
+            `Action "${actionName}" in state "${state2.name}" emits deprecated event "${staticTarget}". A newer version exists: "${current}". Update the .emit() call to target the current version. The reducer (.patch) for "${staticTarget}" stays as-is \u2014 historical events still need it.`
+          );
+        }
+      }
+    }
+    if (deprecationSummary.length > 0) {
+      const list = deprecationSummary.map(
+        (d) => `"${d.deprecated}" (current: "${d.current}", state: "${d.stateName}")`
+      ).join(", ");
+      log().info(
+        `Act registered ${deprecationSummary.length} deprecated event(s): ${list}. These are legacy versions kept for the read path. Consider truncating closed streams via app.close() when feasible to reduce historical event load. See docs/docs/architecture/event-schema-evolution.md.`
+      );
+    }
+  };
   const builder = {
     withState: (state2) => {
       registerState(state2, states, registry.actions, registry.events);
@@ -2776,41 +2030,13 @@ function act() {
       }
     }),
     build: (options) => {
-      for (const proj of pendingProjections) {
-        mergeProjection(proj, registry.events);
-        registerBatchHandler(proj, batchHandlers);
-      }
-      const deprecationSummary = [];
-      for (const state2 of states.values()) {
-        const eventNames = Object.keys(state2.events);
-        const deprecated = deprecatedEventNames(eventNames);
-        if (deprecated.size === 0) continue;
-        state2._deprecated = deprecated;
-        for (const name of deprecated) {
-          const current = currentVersionOf(name, eventNames);
-          deprecationSummary.push({
-            stateName: state2.name,
-            deprecated: name,
-            current
-          });
-        }
-        for (const [actionName, handler] of Object.entries(state2.on)) {
-          const staticTarget = handler?._staticEmit;
-          if (staticTarget && deprecated.has(staticTarget)) {
-            const current = currentVersionOf(staticTarget, eventNames);
-            throw new Error(
-              `Action "${actionName}" in state "${state2.name}" emits deprecated event "${staticTarget}". A newer version exists: "${current}". Update the .emit() call to target the current version. The reducer (.patch) for "${staticTarget}" stays as-is \u2014 historical events still need it.`
-            );
-          }
+      if (!_built) {
+        for (const proj of pendingProjections) {
+          mergeProjection(proj, registry.events);
+          registerBatchHandler(proj, batchHandlers);
         }
-      }
-      if (deprecationSummary.length > 0) {
-        const list = deprecationSummary.map(
-          (d) => `"${d.deprecated}" (current: "${d.current}", state: "${d.stateName}")`
-        ).join(", ");
-        log().info(
-          `Act registered ${deprecationSummary.length} deprecated event(s): ${list}. These are legacy versions kept for the read path. Consider truncating closed streams via app.close() when feasible to reduce historical event load. See docs/docs/architecture/event-schema-evolution.md.`
-        );
+        finalizeDeprecations();
+        _built = true;
       }
       return new Act(
         registry,
@@ -3053,6 +2279,7 @@ export {
   log,
   port,
   projection,
+  scoped,
   sleep,
   slice,
   state,