@rotorsoft/act 0.40.0 → 0.42.0

package/dist/chunk-M5YFKVRV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/console-logger.ts","../src/internal/lru-map.ts","../src/adapters/in-memory-cache.ts","../src/config.ts","../src/ports.ts","../src/utils.ts","../src/adapters/in-memory-store.ts"],"sourcesContent":["/**\n * @module adapters/console-logger\n *\n * High-performance console logger inspired by pino's design:\n * - Numeric level comparison for O(1) gating\n * - stdout.write() in production for raw JSON lines (no console overhead)\n * - Colorized single-line output in development\n * - No-op method replacement when level is above threshold\n * - Child logger support with merged bindings\n */\nimport type { Logger } from \"../types/index.js\";\n\nconst LEVEL_VALUES: Record<string, number> = {\n  fatal: 60,\n  error: 50,\n  warn: 40,\n  info: 30,\n  debug: 20,\n  trace: 10,\n};\n\nconst LEVEL_COLORS: Record<string, string> = {\n  fatal: \"\\x1b[41m\\x1b[37m\", // white on red bg\n  error: \"\\x1b[31m\", // red\n  warn: \"\\x1b[33m\", // yellow\n  info: \"\\x1b[32m\", // green\n  debug: \"\\x1b[36m\", // cyan\n  trace: \"\\x1b[90m\", // gray\n};\n\nconst RESET = \"\\x1b[0m\";\n\nconst noop = () => {};\n\n/**\n * Default console logger for the Act framework.\n *\n * Production mode emits newline-delimited JSON (compatible with GCP, AWS\n * CloudWatch, Datadog, and other structured log ingestion systems).\n *\n * Development mode emits colorized, human-readable output.\n */\nexport class ConsoleLogger implements Logger {\n  level: string;\n  private readonly _pretty: boolean;\n\n  readonly fatal: Logger[\"fatal\"];\n  readonly error: Logger[\"error\"];\n  readonly warn: Logger[\"warn\"];\n  readonly info: Logger[\"info\"];\n  readonly debug: Logger[\"debug\"];\n  readonly trace: Logger[\"trace\"];\n\n  constructor(\n    options: {\n      level?: string;\n      pretty?: boolean;\n      bindings?: Record<string, unknown>;\n    } = {}\n  ) {\n    const {\n      level = \"info\",\n      pretty = process.env.NODE_ENV !== \"production\",\n      bindings,\n    } = options;\n    this._pretty = pretty;\n    this.level = level;\n\n    const threshold = LEVEL_VALUES[level] ?? 30;\n    const write = pretty\n      ? this._prettyWrite.bind(this, bindings)\n      : this._jsonWrite.bind(this, bindings);\n\n    // Assign methods — noop when level is gated (like pino's level-based replacement)\n    this.fatal = write.bind(this, \"fatal\", 60); // fatal is always enabled\n    this.error = threshold <= 50 ? write.bind(this, \"error\", 50) : noop;\n    this.warn = threshold <= 40 ? write.bind(this, \"warn\", 40) : noop;\n    this.info = threshold <= 30 ? write.bind(this, \"info\", 30) : noop;\n    this.debug = threshold <= 20 ? write.bind(this, \"debug\", 20) : noop;\n    this.trace = threshold <= 10 ? write.bind(this, \"trace\", 10) : noop;\n  }\n\n  /** No-op — `console.log` has no resources to release. */\n  async dispose(): Promise<void> {}\n\n  /** @inheritDoc */\n  child(bindings: Record<string, unknown>): Logger {\n    return new ConsoleLogger({\n      level: this.level,\n      pretty: this._pretty,\n      bindings,\n    });\n  }\n\n  private _jsonWrite(\n    bindings: Record<string, unknown> | undefined,\n    level: string,\n    _num: number,\n    objOrMsg: unknown,\n    msg?: string\n  ): void {\n    let obj: Record<string, unknown>;\n    let message: string | undefined;\n\n    if (typeof objOrMsg === \"string\") {\n      message = objOrMsg;\n      obj = {};\n    } else if (objOrMsg !== null && typeof objOrMsg === \"object\") {\n      message = msg;\n      obj = { ...(objOrMsg as Record<string, unknown>) };\n    } else {\n      message = msg;\n      obj = { value: objOrMsg };\n    }\n\n    const entry = Object.assign({ level, time: Date.now() }, bindings, obj);\n    if (message) entry.msg = message;\n\n    let line: string;\n    try {\n      line = JSON.stringify(entry);\n    } catch {\n      // Cyclic or unserializable payload — emit a minimal line rather\n      // than crash the log call site.\n      line = JSON.stringify({\n        level,\n        time: entry.time,\n        msg: message ?? \"[unserializable]\",\n        unserializable: true,\n      });\n    }\n    process.stdout.write(line + \"\\n\");\n  }\n\n  private _prettyWrite(\n    bindings: Record<string, unknown> | undefined,\n    level: string,\n    _num: number,\n    objOrMsg: unknown,\n    msg?: string\n  ): void {\n    const color = LEVEL_COLORS[level];\n    const tag = `${color}${level.toUpperCase().padEnd(5)}${RESET}`;\n    const ts = new Date().toISOString().slice(11, 23); // HH:mm:ss.SSS\n\n    let message: string;\n    let data: string | undefined;\n\n    if (typeof objOrMsg === \"string\") {\n      message = objOrMsg;\n    } else {\n      message = msg ?? \"\";\n      if (objOrMsg !== undefined && objOrMsg !== null) {\n        try {\n          data = JSON.stringify(objOrMsg);\n        } catch {\n          data = \"[unserializable]\";\n        }\n      }\n    }\n\n    const bindStr =\n      bindings && Object.keys(bindings).length\n        ? ` ${JSON.stringify(bindings)}`\n        : \"\";\n\n    const parts = [ts, tag, message, data, bindStr].filter(Boolean);\n    process.stdout.write(parts.join(\" \") + \"\\n\");\n  }\n}\n","/**\n * @module lru-map\n * @category Internal\n *\n * Tiny bounded LRU map / set built on insertion-ordered `Map`. Used to cap\n * memory in long-running orchestrators that mint large numbers of keys —\n * notably:\n *\n * - {@link InMemoryCache}: stream → state checkpoint\n * - `Act._subscribed_streams`: stream → presence (LruSet)\n *\n * Apps with millions of dynamic streams (one target per aggregate) can't\n * afford an unbounded `Set<string>` — eviction is required.\n *\n * @internal\n */\n\n/**\n * Bounded LRU map. `get()` promotes; `has()` does not. `set()` always\n * promotes and evicts the oldest entry when at capacity.\n *\n * @internal\n */\nexport class LruMap<K, V> {\n  private readonly _entries = new Map<K, V>();\n\n  constructor(private readonly _maxSize: number) {}\n\n  get(key: K): V | undefined {\n    const v = this._entries.get(key);\n    if (v === undefined) return undefined;\n    // promote: delete + re-insert moves to most-recent position\n    this._entries.delete(key);\n    this._entries.set(key, v);\n    return v;\n  }\n\n  has(key: K): boolean {\n    return this._entries.has(key);\n  }\n\n  set(key: K, value: V): void {\n    this._entries.delete(key);\n    if (this._entries.size >= this._maxSize) {\n      // size >= maxSize ≥ 1 → at least one entry exists → next().value\n      // is the oldest key (asserted with `!`).\n      const oldest = this._entries.keys().next().value!;\n      this._entries.delete(oldest);\n    }\n    this._entries.set(key, value);\n  }\n\n  delete(key: K): boolean {\n    return this._entries.delete(key);\n  }\n\n  clear(): void {\n    this._entries.clear();\n  }\n\n  get size(): number {\n    return this._entries.size;\n  }\n}\n\n/**\n * Bounded LRU set built on top of {@link LruMap}. `has()` does not promote;\n * `add()` does (re-inserting if already present, evicting the oldest at\n * capacity).\n *\n * @internal\n */\nexport class LruSet<T> {\n  private readonly _map: LruMap<T, true>;\n\n  constructor(maxSize: number) {\n    this._map = new LruMap(maxSize);\n  }\n\n  has(value: T): boolean {\n    return this._map.has(value);\n  }\n\n  add(value: T): void {\n    this._map.set(value, true);\n  }\n\n  delete(value: T): boolean {\n    return this._map.delete(value);\n  }\n\n  clear(): void {\n    this._map.clear();\n  }\n\n  get size(): number {\n    return this._map.size;\n  }\n}\n","import { LruMap } from \"../internal/lru-map.js\";\nimport type { Cache, CacheEntry, Schema } from \"../types/index.js\";\n\n/**\n * In-memory LRU cache for stream snapshots.\n *\n * Backed by an internal `LruMap` for O(1) get/set with LRU eviction.\n * Configurable `maxSize` bounds memory usage.\n *\n * @example\n * ```typescript\n * import { cache } from \"@rotorsoft/act\";\n * import { InMemoryCache } from \"@rotorsoft/act\";\n *\n * cache(new InMemoryCache({ maxSize: 500 }));\n * ```\n */\n/* eslint-disable @typescript-eslint/require-await -- async interface for Redis-compatibility */\nexport class InMemoryCache implements Cache {\n  // CacheEntry<any> lets `get<TState>` and `set<TState>` flow without casts:\n  // any is bidirectionally compatible with the per-call TState binding, while\n  // the public Cache interface still presents a typed surface to callers.\n  private readonly _entries: LruMap<string, CacheEntry<any>>;\n\n  constructor(options?: { maxSize?: number }) {\n    this._entries = new LruMap(options?.maxSize ?? 1000);\n  }\n\n  /** @inheritDoc */\n  async get<TState extends Schema>(\n    stream: string\n  ): Promise<CacheEntry<TState> | undefined> {\n    return this._entries.get(stream);\n  }\n\n  /** @inheritDoc */\n  async set<TState extends Schema>(\n    stream: string,\n    entry: CacheEntry<TState>\n  ): Promise<void> {\n    this._entries.set(stream, entry);\n  }\n\n  /** @inheritDoc */\n  async invalidate(stream: string): Promise<void> {\n    this._entries.delete(stream);\n  }\n\n  /** @inheritDoc */\n  async clear(): Promise<void> {\n    this._entries.clear();\n  }\n\n  /** @inheritDoc */\n  async dispose(): Promise<void> {\n    this._entries.clear();\n  }\n\n  /** Current number of entries held by the LRU. */\n  get size(): number {\n    return this._entries.size;\n  }\n}\n","/**\n * @packageDocumentation\n * Configuration utilities for Act Framework environment, logging, and package metadata.\n *\n * Provides type-safe configuration loading and validation using Zod schemas.\n *\n * @module config\n */\nimport * as fs from \"node:fs\";\nimport { z } from \"zod\";\nimport { log } from \"./ports.js\";\nimport {\n  type Environment,\n  Environments,\n  type LogLevel,\n  LogLevels,\n} from \"./types/index.js\";\nimport { extend } from \"./utils.js\";\n\n/**\n * Zod schema for validating package.json metadata.\n * @internal\n */\nexport const PackageSchema = z.object({\n  name: z.string().min(1),\n  version: z.string().min(1),\n  description: z.string().min(1).optional(),\n  author: z\n    .object({ name: z.string().min(1), email: z.string().optional() })\n    .optional()\n    .or(z.string().min(1))\n    .optional(),\n  license: z.string().min(1).optional(),\n  dependencies: z.record(z.string(), z.string()).optional(),\n});\n\n/**\n * Type representing the validated package.json metadata.\n *\n * @internal\n */\nexport type Package = z.infer<typeof PackageSchema>;\n\n/**\n * Fallback package metadata when `package.json` can't be read at module\n * load — happens when the framework is consumed from a CWD that doesn't\n * have one (bundled CLIs, Lambda layers, embedded scripts) or when the\n * file exists but is malformed.\n *\n * The values are deliberately synthetic so callers spot them immediately:\n * `config().name === \"act-fallback\"` is a runtime signal that the framework\n * couldn't load the host project's package.json.\n *\n * @internal\n */\nconst FALLBACK_PACKAGE: Package = {\n  name: \"act-fallback\",\n  version: \"0.0.0-fallback\",\n  description: \"Synthetic fallback — package.json could not be loaded\",\n};\n\n/**\n * Loads and parses the local package.json file as a Package object. On\n * any read or parse failure, falls back to {@link FALLBACK_PACKAGE} and\n * stashes the error so {@link config} can surface it on first access —\n * we can't call `log()` here because the logger port memoizes on first\n * call and locking it at module load defeats user injection.\n *\n * @internal\n */\nconst getPackage = (): Package => {\n  try {\n    const raw = fs.readFileSync(\"package.json\");\n    return JSON.parse(raw.toString()) as Package;\n  } catch (err) {\n    pkgLoadError = err;\n    return FALLBACK_PACKAGE;\n  }\n};\n\n/** Stashed read/parse error from {@link getPackage}, surfaced by config(). */\nlet pkgLoadError: unknown;\n\n/**\n * Zod schema for the full Act Framework configuration object.\n * Includes package metadata, environment, logging, and timing options.\n * @internal\n */\nconst BaseSchema = PackageSchema.extend({\n  env: z.enum(Environments),\n  logLevel: z.enum(LogLevels),\n  logSingleLine: z.boolean(),\n  sleepMs: z.number().int().min(0).max(5000),\n});\n\n/**\n * Type representing the validated Act Framework configuration object.\n */\nexport type Config = z.infer<typeof BaseSchema>;\n\nconst { NODE_ENV, LOG_LEVEL, LOG_SINGLE_LINE, SLEEP_MS } = process.env;\n\nconst env = (NODE_ENV || \"development\") as Environment;\nconst logLevel = (LOG_LEVEL ||\n  (NODE_ENV === \"test\"\n    ? \"fatal\"\n    : NODE_ENV === \"production\"\n      ? \"info\"\n      : \"trace\")) as LogLevel;\nconst logSingleLine = (LOG_SINGLE_LINE || \"true\") === \"true\";\nconst sleepMs = parseInt(NODE_ENV === \"test\" ? \"0\" : (SLEEP_MS ?? \"100\"), 10);\n\nconst pkg = getPackage();\n\n// Lazily validated on first call. Cannot run extend() at module load\n// because of a utils.ts <-> config.ts cycle (utils imports config for\n// sleep()'s default). Inputs are frozen after import, so the cached\n// result is stable for the life of the process.\nlet _validated: Config | undefined;\n\n/**\n * Gets the current Act Framework configuration.\n *\n * Configuration is loaded from package.json and environment variables, providing\n * type-safe access to application metadata and runtime settings.\n *\n * **Environment Variables:**\n * - `NODE_ENV`: \"development\" | \"test\" | \"staging\" | \"production\" (default: \"development\")\n * - `LOG_LEVEL`: \"fatal\" | \"error\" | \"warn\" | \"info\" | \"debug\" | \"trace\"\n * - `LOG_SINGLE_LINE`: \"true\" | \"false\" (default: \"true\")\n * - `SLEEP_MS`: Milliseconds for sleep utility (default: 100, 0 for tests)\n *\n * **Defaults by environment:**\n * - test: logLevel=\"error\", sleepMs=0\n * - production: logLevel=\"info\"\n * - development: logLevel=\"trace\"\n *\n * @returns The validated configuration object\n *\n * @example Basic usage\n * ```typescript\n * import { config } from \"@rotorsoft/act\";\n *\n * const cfg = config();\n * console.log(`App: ${cfg.name} v${cfg.version}`);\n * console.log(`Environment: ${cfg.env}`);\n * console.log(`Log level: ${cfg.logLevel}`);\n * ```\n *\n * @example Environment-specific behavior\n * ```typescript\n * import { config } from \"@rotorsoft/act\";\n *\n * const cfg = config();\n *\n * if (cfg.env === \"production\") {\n *   // Use PostgreSQL in production\n *   store(new PostgresStore(prodConfig));\n * } else {\n *   // Use in-memory store for dev/test\n *   store(new InMemoryStore());\n * }\n * ```\n *\n * @example Adjusting log levels\n * ```typescript\n * // Set via environment variable:\n * // LOG_LEVEL=debug npm start\n *\n * // Or check in code:\n * const cfg = config();\n * if (cfg.logLevel === \"trace\") {\n *   logger.trace(\"Detailed debugging enabled\");\n * }\n * ```\n *\n * @see {@link Config} for configuration type\n */\nexport const config = (): Config => {\n  if (!_validated) {\n    _validated = extend(\n      { ...pkg, env, logLevel, logSingleLine, sleepMs },\n      BaseSchema\n    );\n    if (pkgLoadError) {\n      // Surface the fallback once, after _validated is set so the\n      // recursive log() → config() call short-circuits. log() resolves\n      // through the port singleton — respects user injection and level.\n      const msg =\n        pkgLoadError instanceof Error\n          ? pkgLoadError.message\n          : typeof pkgLoadError === \"string\"\n            ? pkgLoadError\n            : \"unknown error\";\n      log().warn(\n        `[act] Could not read package.json (${msg}); using synthetic ` +\n          `name=\"${FALLBACK_PACKAGE.name}\" version=\"${FALLBACK_PACKAGE.version}\".`\n      );\n      pkgLoadError = undefined;\n    }\n  }\n  return _validated;\n};\n","import { AsyncLocalStorage } from \"node:async_hooks\";\nimport { ConsoleLogger } from \"./adapters/console-logger.js\";\nimport { InMemoryCache } from \"./adapters/in-memory-cache.js\";\nimport { InMemoryStore } from \"./adapters/in-memory-store.js\";\nimport { config } from \"./config.js\";\nimport type {\n  Cache,\n  Disposable,\n  Disposer,\n  Logger,\n  Store,\n} from \"./types/index.js\";\n\n/** Per-Act ports bag (ACT-501). Both required together — a shared cache across stores would collide on stream keys. */\nexport type Scoped = {\n  readonly store: Store;\n  readonly cache: Cache;\n};\n\n/** AsyncLocalStorage carrying the active Act's ports. Internal — not re-exported. */\nexport const scoped = new AsyncLocalStorage<Scoped>();\n\n/**\n * Port/adapter infrastructure for the Act framework.\n *\n * All infrastructure concerns (logging, storage, caching) are managed as\n * singleton adapters injected via port functions. Each port follows the same\n * pattern: first call wins with a sensible default, optional adapter injection.\n *\n * - `log()` — structured logging (default: ConsoleLogger)\n * - `store()` — event persistence (default: InMemoryStore)\n * - `cache()` — state checkpoints (default: InMemoryCache)\n * - `dispose()` — register cleanup functions for graceful shutdown\n *\n * @module ports\n */\n\n/**\n * List of exit codes for process termination. Consumed by signal handlers\n * and {@link disposeAndExit}; not part of the user-facing surface.\n *\n * @internal\n */\nexport const ExitCodes = [\"ERROR\", \"EXIT\"] as const;\n\n/**\n * Type for allowed exit codes.\n *\n * - `\"ERROR\"` — abnormal termination (uncaught exception, unhandled rejection)\n * - `\"EXIT\"` — clean shutdown (SIGINT, SIGTERM, or manual trigger)\n *\n * @internal\n */\nexport type ExitCode = (typeof ExitCodes)[number];\n\n// ---------------------------------------------------------------------------\n// Port factory\n// ---------------------------------------------------------------------------\n\n/**\n * Factory function that creates or returns the injected adapter.\n * @internal\n */\ntype Injector<Port extends Disposable> = (adapter?: Port) => Port;\n\n/** Singleton adapter registry, keyed by injector function name. */\nconst adapters = new Map<string, Disposable>();\n\n/**\n * Creates a singleton port with optional adapter injection.\n *\n * The first call initializes the adapter (using the provided adapter or the\n * injector's default). Subsequent calls return the cached singleton. Adapters\n * are disposed in reverse registration order during {@link disposeAndExit}.\n *\n * @param injector - Named function that creates the default adapter\n * @returns Port function: call with no args to get the singleton, or pass an\n *          adapter on the first call to override the default\n *\n * @example\n * ```typescript\n * const store = port(function store(adapter?: Store) {\n *   return adapter || new InMemoryStore();\n * });\n * const s = store(); // InMemoryStore\n * ```\n */\nexport function port<Port extends Disposable>(injector: Injector<Port>) {\n  return (adapter?: Port): Port => {\n    if (!adapters.has(injector.name)) {\n      const injected = injector(adapter);\n      adapters.set(injector.name, injected);\n      // log() is now in adapters (or this IS the log port we just registered),\n      // so the recursive call resolves immediately. Routing through the logger\n      // means level gating (e.g. silenced in tests at fatal) takes effect.\n      log().info(`[act] + ${injector.name}:${injected.constructor.name}`);\n    }\n    return adapters.get(injector.name) as Port;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Ports: log, store, cache\n// ---------------------------------------------------------------------------\n\n/**\n * Gets or injects the singleton logger.\n *\n * By default, Act uses a built-in {@link ConsoleLogger} that emits JSON lines\n * in production (compatible with GCP, AWS CloudWatch, Datadog) and colorized\n * output in development — zero external dependencies.\n *\n * For pino, inject a `PinoLogger` from `@rotorsoft/act-pino` before building\n * your application.\n *\n * @param adapter - Optional logger implementation to inject\n * @returns The singleton logger instance\n *\n * @example Default console logger\n * ```typescript\n * import { log } from \"@rotorsoft/act\";\n * const logger = log();\n * logger.info(\"Application started\");\n * ```\n *\n * @example Injecting pino\n * ```typescript\n * import { log } from \"@rotorsoft/act\";\n * import { PinoLogger } from \"@rotorsoft/act-pino\";\n * log(new PinoLogger({ level: \"debug\", pretty: true }));\n * ```\n *\n * @see {@link Logger} for the interface contract\n * @see {@link ConsoleLogger} for the default implementation\n */\nexport const log = port(function log(adapter?: Logger) {\n  const cfg = config();\n  return (\n    adapter ||\n    new ConsoleLogger({\n      level: cfg.logLevel,\n      pretty: cfg.env !== \"production\",\n    })\n  );\n});\n\n/**\n * Gets or injects the singleton event store.\n *\n * By default, Act uses an {@link InMemoryStore} suitable for development and\n * testing. For production, inject a persistent store like `PostgresStore` from\n * `@rotorsoft/act-pg` before building your application.\n *\n * **Important:** Store injection must happen before creating any Act instances.\n * Once set, the store cannot be changed without restarting the application.\n *\n * @param adapter - Optional store implementation to inject\n * @returns The singleton store instance\n *\n * @example Default in-memory store\n * ```typescript\n * import { store } from \"@rotorsoft/act\";\n * const s = store();\n * ```\n *\n * @example Injecting PostgreSQL\n * ```typescript\n * import { store } from \"@rotorsoft/act\";\n * import { PostgresStore } from \"@rotorsoft/act-pg\";\n *\n * store(new PostgresStore({\n *   host: \"localhost\",\n *   port: 5432,\n *   database: \"myapp\",\n *   user: \"postgres\",\n *   password: \"secret\",\n * }));\n * ```\n *\n * @see {@link Store} for the interface contract\n * @see {@link InMemoryStore} for the default implementation\n */\n// ALS check lives outside `port()` — its cache fires only once, so the\n// per-call branch on a scoped Act has to be in the public wrapper.\nconst _store = port(function store(adapter?: Store): Store {\n  return adapter ?? new InMemoryStore();\n});\n\nexport const store = ((adapter?: Store): Store => {\n  return scoped.getStore()?.store ?? _store(adapter);\n}) as (adapter?: Store) => Store;\n\n/**\n * Gets or injects the singleton cache.\n *\n * By default, Act uses an {@link InMemoryCache} (LRU, maxSize 1000). For\n * distributed deployments, inject a Redis-backed cache before building your\n * application.\n *\n * @param adapter - Optional cache implementation to inject\n * @returns The singleton cache instance\n *\n * @see {@link Cache} for the interface contract\n * @see {@link InMemoryCache} for the default implementation\n */\nconst _cache = port(function cache(adapter?: Cache) {\n  return adapter ?? new InMemoryCache();\n});\n\nexport const cache = ((adapter?: Cache): Cache => {\n  return scoped.getStore()?.cache ?? _cache(adapter);\n}) as (adapter?: Cache) => Cache;\n\n// ---------------------------------------------------------------------------\n// Disposal\n// ---------------------------------------------------------------------------\n\n/** Registered cleanup functions, executed in reverse order during shutdown. */\nconst disposers: Disposer[] = [];\n\n/**\n * Disposes all registered adapters and disposers, then exits the process.\n *\n * Execution order:\n * 1. Custom disposers (registered via {@link dispose}) — in reverse order\n * 2. Port adapters (log, store, cache) — in reverse registration order\n * 3. Adapter registry is cleared\n * 4. Process exits (skipped in test environment)\n *\n * In production, `\"ERROR\"` exits are silently ignored to avoid crashing on\n * transient failures (e.g. an uncaught promise in a non-critical path).\n *\n * @param code - Exit code: `\"EXIT\"` for clean shutdown (exit 0),\n *               `\"ERROR\"` for abnormal termination (exit 1)\n */\nexport async function disposeAndExit(code: ExitCode = \"EXIT\"): Promise<void> {\n  if (code === \"ERROR\" && config().env === \"production\") {\n    // Surface the swallow so incident triage can see it. Without this\n    // log the framework looks unresponsive after an uncaught exception\n    // in prod — exactly when operators most need a breadcrumb.\n    log().warn(\n      \"disposeAndExit('ERROR') ignored in production — process kept alive\"\n    );\n    return;\n  }\n\n  // Run sequentially in reverse registration order so a disposer can rely on\n  // later-registered disposers (and adapters on later-registered adapters)\n  // having already finished — Promise.all would race them.\n  for (const disposer of [...disposers].reverse()) {\n    await disposer();\n  }\n  for (const adapter of [...adapters.values()].reverse()) {\n    await adapter.dispose();\n    log().info(`[act] - ${adapter.constructor.name}`);\n  }\n  adapters.clear();\n  config().env !== \"test\" && process.exit(code === \"ERROR\" ? 1 : 0);\n}\n\n/**\n * Registers a cleanup function for graceful shutdown.\n *\n * Disposers are called automatically on SIGINT, SIGTERM, uncaught exceptions,\n * and unhandled rejections. They execute in reverse registration order before\n * port adapters are disposed.\n *\n * @param disposer - Async function to call during cleanup. Omit to get a\n *                   reference to {@link disposeAndExit} without registering.\n * @returns Function to manually trigger disposal and exit\n *\n * @example\n * ```typescript\n * import { dispose } from \"@rotorsoft/act\";\n *\n * const db = connectDatabase();\n * dispose(async () => await db.close());\n *\n * // In tests\n * afterAll(async () => await dispose()());\n * ```\n *\n * @see {@link disposeAndExit} for the full shutdown sequence\n */\nexport function dispose(\n  disposer?: Disposer\n): (code?: ExitCode) => Promise<void> {\n  disposer && disposers.push(disposer);\n  return disposeAndExit;\n}\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Event name used internally for snapshot events in the event store.\n * Snapshot events store a full state checkpoint, enabling efficient cold-start\n * recovery without replaying the entire event stream.\n */\nexport const SNAP_EVENT = \"__snapshot__\";\n\n/**\n * Event name used internally for tombstone events in the event store.\n * A tombstone marks a stream as permanently closed — no further writes\n * are permitted until the stream is explicitly restarted via `close()`.\n *\n * @see {@link Act.close} for the close-the-books API\n */\nexport const TOMBSTONE_EVENT = \"__tombstone__\";\n","import { prettifyError, ZodError, type ZodType } from \"zod\";\nimport { config } from \"./config.js\";\nimport { ValidationError } from \"./types/index.js\";\n\n/**\n * @module utils\n * @category Utilities\n *\n * Small utilities used across the framework:\n * - {@link validate} — parse a payload against a Zod schema, throwing\n *   {@link ValidationError} on failure.\n * - {@link extend} — validate a source object and merge into defaults.\n * - {@link sleep} — async delay (default duration from `config().sleepMs`).\n */\n\n/**\n * Parse `payload` against `schema`, returning the validated value or throwing\n * a {@link ValidationError} with prettified Zod details. When `schema` is\n * omitted, returns `payload` unchanged. The framework calls this for every\n * `app.do()` action, every emitted event, and every state init.\n *\n * @example\n * ```typescript\n * const UserSchema = z.object({ email: z.string().email() });\n * const user = validate(\"User\", { email: \"alice@example.com\" }, UserSchema);\n * ```\n *\n * @see {@link ValidationError}\n */\nexport const validate = <S>(\n  target: string,\n  payload: Readonly<S>,\n  schema?: ZodType<S>\n): Readonly<S> => {\n  try {\n    return schema ? schema.parse(payload) : payload;\n  } catch (error) {\n    if (error instanceof ZodError) {\n      throw new ValidationError(target, payload, prettifyError(error));\n    }\n    throw new ValidationError(target, payload, error);\n  }\n};\n\n/**\n * Validate `source` against `schema` and return a new object that merges\n * `source` over the optional `target` defaults. Used by {@link config} for\n * env-var-overrides-defaults patterns; safe to call elsewhere — it never\n * mutates `target`.\n *\n * @example\n * ```typescript\n * const schema = z.object({ host: z.string(), port: z.number() });\n * const cfg = extend({ port: 8080 }, schema, { host: \"localhost\", port: 80 });\n * // → { host: \"localhost\", port: 8080 }\n * ```\n *\n * @throws {@link ValidationError} if `source` fails the schema.\n */\nexport const extend = <\n  S extends Record<string, unknown>,\n  T extends Record<string, unknown>,\n>(\n  source: Readonly<S>,\n  schema: ZodType<S>,\n  target?: Readonly<T>\n): Readonly<S & T> => {\n  const value = validate(\"config\", source, schema);\n  return { ...target, ...value } as Readonly<S & T>;\n};\n\n/**\n * Pause for `ms` milliseconds (or `config().sleepMs` when omitted — `100ms`\n * in dev, `0ms` in tests). Used by adapters to simulate async I/O.\n *\n * @example\n * ```typescript\n * await sleep();      // default delay from config\n * await sleep(500);   // explicit 500ms\n * ```\n */\nexport async function sleep(ms?: number) {\n  return new Promise((resolve) => setTimeout(resolve, ms ?? config().sleepMs));\n}\n","/**\n * @packageDocumentation\n * @module act/adapters\n * In-memory event store adapter for the Act Framework.\n *\n * This adapter implements the Store interface and is suitable for development, testing, and demonstration purposes.\n * All data is stored in memory and lost on process exit.\n *\n * @category Adapters\n */\nimport { SNAP_EVENT, TOMBSTONE_EVENT } from \"../ports.js\";\nimport { ConcurrencyError } from \"../types/errors.js\";\nimport type {\n  BlockedLease,\n  Committed,\n  EventMeta,\n  Lease,\n  Message,\n  PrioritizeFilter,\n  Query,\n  QueryStreams,\n  QueryStreamsResult,\n  Schema,\n  Schemas,\n  Store,\n  StreamPosition,\n} from \"../types/index.js\";\nimport { sleep } from \"../utils.js\";\n\n/**\n * @internal\n * Represents an in-memory stream for event processing and leasing.\n */\nclass InMemoryStream {\n  private _at = -1;\n  private _retry = -1;\n  private _blocked = false;\n  private _error = \"\";\n  private _leased_by: string | undefined = undefined;\n  private _leased_until: Date | undefined = undefined;\n  private _priority = 0;\n\n  constructor(\n    readonly stream: string,\n    readonly source: string | undefined,\n    priority = 0\n  ) {\n    this._priority = priority;\n  }\n\n  get priority() {\n    return this._priority;\n  }\n\n  /**\n   * Bump the priority via {@link subscribe}: keeps the maximum across\n   * reactions so the highest-priority registrant wins.\n   */\n  bumpPriority(priority: number) {\n    if (priority > this._priority) this._priority = priority;\n  }\n\n  /**\n   * Set the priority outright via {@link prioritize}: operator\n   * runtime override that ignores the build-time `max()` invariant.\n   */\n  setPriority(priority: number) {\n    this._priority = priority;\n  }\n\n  get is_available() {\n    return (\n      !this._blocked &&\n      (!this._leased_until || this._leased_until <= new Date())\n    );\n  }\n\n  get at() {\n    return this._at;\n  }\n\n  get retry() {\n    return this._retry;\n  }\n\n  get blocked() {\n    return this._blocked;\n  }\n\n  get error() {\n    return this._error;\n  }\n\n  get leased_by() {\n    return this._leased_by;\n  }\n\n  get leased_until() {\n    return this._leased_until;\n  }\n\n  /**\n   * Attempt to lease this stream for processing.\n   * @param lease - The lease request.\n   * @param millis - Lease duration in milliseconds.\n   * @returns The granted lease or undefined if blocked.\n   */\n  lease(lease: Lease, millis: number): Lease {\n    if (millis > 0) {\n      this._leased_by = lease.by;\n      this._leased_until = new Date(Date.now() + millis);\n    }\n    this._retry = this._retry + 1;\n    return {\n      stream: this.stream,\n      source: this.source,\n      at: lease.at,\n      by: lease.by,\n      retry: this._retry,\n      lagging: lease.lagging,\n    };\n  }\n\n  /**\n   * Acknowledge completion of processing for this stream.\n   * @param lease - The lease request.\n   */\n  ack(lease: Lease) {\n    if (this._leased_by === lease.by) {\n      this._leased_by = undefined;\n      this._leased_until = undefined;\n      this._at = lease.at;\n      this._retry = -1;\n      return {\n        stream: this.stream,\n        source: this.source,\n        at: this._at,\n        by: lease.by,\n        retry: this._retry,\n        lagging: lease.lagging,\n      };\n    }\n  }\n\n  /**\n   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.\n   * @param lease - The lease request.\n   * @param error Blocked error message.\n   */\n  block(lease: Lease, error: string) {\n    if (this._leased_by === lease.by) {\n      this._blocked = true;\n      this._error = error;\n      return {\n        stream: this.stream,\n        source: this.source,\n        at: this._at,\n        by: this._leased_by,\n        retry: this._retry,\n        error: this._error,\n        lagging: lease.lagging,\n      };\n    }\n  }\n\n  /**\n   * Reset this stream's watermark and state for replay. The retry counter\n   * resets to -1 to match the constructor + ack() invariant (\"released\n   * stream\"); the next claim() bumps it to 0 (first attempt).\n   */\n  reset() {\n    this._at = -1;\n    this._retry = -1;\n    this._blocked = false;\n    this._error = \"\";\n    this._leased_by = undefined;\n    this._leased_until = undefined;\n  }\n}\n\n/**\n * In-memory event store implementation.\n *\n * This is the default store used by Act when no other store is injected.\n * It stores all events in memory and is suitable for:\n * - Development and prototyping\n * - Unit and integration testing\n * - Demonstrations and examples\n *\n * **Not suitable for production** - all data is lost when the process exits.\n * Use {@link PostgresStore} for production deployments.\n *\n * The in-memory store provides:\n * - Full {@link Store} interface implementation\n * - Optimistic concurrency control\n * - Stream leasing for distributed processing simulation\n * - Snapshot support\n * - Fast performance (no I/O overhead)\n *\n * **`Store.notify` is intentionally not implemented.** The notify hook is a\n * cross-process wake-up signal — local commits already arm the drain via\n * `do()`. An in-memory store is single-process by definition, so there is\n * no remote writer to be notified of. The {@link Act} orchestrator\n * detects the absence and falls back to the existing debounce/poll path.\n *\n * @example Using in tests\n * ```typescript\n * import { store } from \"@rotorsoft/act\";\n *\n * describe(\"Counter\", () => {\n *   beforeEach(async () => {\n *     // Reset store between tests\n *     await store().seed();\n *   });\n *\n *   it(\"increments\", async () => {\n *     await app.do(\"increment\", target, { by: 5 });\n *     const snapshot = await app.load(Counter, \"counter-1\");\n *     expect(snapshot.state.count).toBe(5);\n *   });\n * });\n * ```\n *\n * @example Explicit instantiation\n * ```typescript\n * import { InMemoryStore } from \"@rotorsoft/act\";\n *\n * const testStore = new InMemoryStore();\n * await testStore.seed();\n *\n * // Use for specific test scenarios\n * await testStore.commit(\"test-stream\", events, meta);\n * ```\n *\n * @example Querying events\n * ```typescript\n * const events: any[] = [];\n * await store().query(\n *   (event) => events.push(event),\n *   { stream: \"test-stream\" }\n * );\n * console.log(`Found ${events.length} events`);\n * ```\n *\n * @see {@link Store} for the interface definition\n * @see {@link PostgresStore} for production use\n * @see {@link store} for injecting stores\n *\n * @category Adapters\n */\nexport class InMemoryStore implements Store {\n  // stored events\n  private _events: Committed<Schemas, keyof Schemas>[] = [];\n  // stored stream positions and other metadata\n  private _streams: Map<string, InMemoryStream> = new Map();\n  // last committed version per stream — O(1) replacement for filter-on-commit\n  private _streamVersions: Map<string, number> = new Map();\n  // max non-snapshot event id per stream — drives the source-pattern probe in claim()\n  // without scanning the full event log.\n  private _maxEventIdByStream: Map<string, number> = new Map();\n  // global max non-snapshot event id — fast pre-check for source-less streams in claim()\n  private _maxNonSnapEventId = -1;\n\n  private _resetIndexes() {\n    this._events.length = 0;\n    this._streamVersions.clear();\n    this._maxEventIdByStream.clear();\n    this._maxNonSnapEventId = -1;\n  }\n\n  /**\n   * Dispose of the store and clear all events.\n   * @returns Promise that resolves when disposal is complete.\n   */\n  async dispose() {\n    await sleep();\n    this._resetIndexes();\n  }\n\n  /**\n   * Seed the store with initial data (no-op for in-memory).\n   * @returns Promise that resolves when seeding is complete.\n   */\n  async seed() {\n    await sleep();\n  }\n\n  /**\n   * Drop all data from the store.\n   * @returns Promise that resolves when the store is cleared.\n   */\n  async drop() {\n    await sleep();\n    this._resetIndexes();\n    this._streams = new Map();\n  }\n\n  private in_query<E extends Schemas>(query: Query, e: Committed<E, keyof E>) {\n    if (query.stream) {\n      if (query.stream_exact) {\n        if (e.stream !== query.stream) return false;\n      } else if (!RegExp(query.stream).test(e.stream)) return false;\n    }\n    if (query.names && !query.names.includes(e.name as string)) return false;\n    if (query.correlation && e.meta?.correlation !== query.correlation)\n      return false;\n    if (e.name === SNAP_EVENT && !query.with_snaps) return false;\n    return true;\n  }\n\n  /**\n   * Query events in the store, optionally filtered by query options.\n   * @param callback - Function to call for each event.\n   * @param query - Optional query options.\n   * @returns The number of events processed.\n   */\n  async query<E extends Schemas>(\n    callback: (event: Committed<E, keyof E>) => void,\n    query?: Query\n  ) {\n    await sleep();\n    let count = 0;\n    if (query?.backward) {\n      let i = (query?.before || this._events.length) - 1;\n      while (i >= 0) {\n        const e = this._events[i--];\n        if (query && !this.in_query(query, e)) continue;\n        if (query?.created_before && e.created >= query.created_before)\n          continue;\n        if (query.after && e.id <= query.after) break;\n        if (query.created_after && e.created <= query.created_after) break;\n        callback(e as Committed<E, keyof E>);\n        count++;\n        if (query?.limit && count >= query.limit) break;\n      }\n    } else {\n      let i = (query?.after ?? -1) + 1;\n      while (i < this._events.length) {\n        const e = this._events[i++];\n        if (query && !this.in_query(query, e)) continue;\n        if (query?.created_after && e.created <= query.created_after) continue;\n        if (query?.before && e.id >= query.before) break;\n        if (query?.created_before && e.created >= query.created_before) break;\n        callback(e as Committed<E, keyof E>);\n        count++;\n        if (query?.limit && count >= query.limit) break;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Commit one or more events to a stream.\n   * @param stream - The stream name.\n   * @param msgs - The events/messages to commit.\n   * @param meta - Event metadata.\n   * @param expectedVersion - Optional optimistic concurrency check.\n   * @returns The committed events with metadata.\n   * @throws ConcurrencyError if expectedVersion does not match.\n   */\n  async commit<E extends Schemas>(\n    stream: string,\n    msgs: Message<E, keyof E>[],\n    meta: EventMeta,\n    expectedVersion?: number\n  ) {\n    await sleep();\n    const currentVersion = this._streamVersions.get(stream) ?? -1;\n    if (\n      typeof expectedVersion === \"number\" &&\n      currentVersion !== expectedVersion\n    ) {\n      throw new ConcurrencyError(\n        stream,\n        currentVersion,\n        msgs as Message<Schemas, keyof Schemas>[],\n        expectedVersion\n      );\n    }\n\n    let version = currentVersion + 1;\n    let lastNonSnapId = -1;\n    const committed = msgs.map(({ name, data }) => {\n      const c: Committed<E, keyof E> = {\n        id: this._events.length,\n        stream,\n        version,\n        created: new Date(),\n        name,\n        data,\n        meta,\n      };\n      this._events.push(c as Committed<Schemas, keyof Schemas>);\n      if (name !== SNAP_EVENT) lastNonSnapId = c.id;\n      version++;\n      return c;\n    });\n    this._streamVersions.set(stream, version - 1);\n    if (lastNonSnapId >= 0) {\n      this._maxEventIdByStream.set(stream, lastNonSnapId);\n      // commit always assigns a fresh id from this._events.length, so any\n      // non-snap commit strictly raises the global max.\n      this._maxNonSnapEventId = lastNonSnapId;\n    }\n    return committed;\n  }\n\n  /**\n   * Atomically discovers and leases streams for processing.\n   * Fuses poll + lease into a single operation.\n   * @param lagging - Max streams from lagging frontier.\n   * @param leading - Max streams from leading frontier.\n   * @param by - Lease holder identifier.\n   * @param millis - Lease duration in milliseconds.\n   * @returns Granted leases.\n   */\n  async claim(lagging: number, leading: number, by: string, millis: number) {\n    await sleep();\n    // Cache compiled regexes — multiple subscribed streams typically share the\n    // same source pattern, and the inner loop can run thousands of times per claim.\n    const sourceRegex = new Map<string, RegExp>();\n    const getRegex = (source: string) => {\n      let re = sourceRegex.get(source);\n      if (!re) {\n        re = new RegExp(source);\n        sourceRegex.set(source, re);\n      }\n      return re;\n    };\n    const hasWork = (s: InMemoryStream): boolean => {\n      if (s.at < 0) return true;\n      if (!s.source) return s.at < this._maxNonSnapEventId;\n      const re = getRegex(s.source);\n      for (const [streamName, maxId] of this._maxEventIdByStream) {\n        if (maxId > s.at && re.test(streamName)) return true;\n      }\n      return false;\n    };\n    const available = [...this._streams.values()].filter(\n      (s) => s.is_available && hasWork(s)\n    );\n    // Lagging frontier orders by priority DESC (higher first), then by\n    // watermark ASC (most-behind first). Mirrors the PG `claim()` SQL\n    // — see `libs/act-pg/PERFORMANCE.md` for the benchmark that\n    // motivated the priority dimension.\n    const lag = available\n      .sort((a, b) => b.priority - a.priority || a.at - b.at)\n      .slice(0, lagging)\n      .map((s) => ({\n        stream: s.stream,\n        source: s.source,\n        at: s.at,\n        lagging: true,\n      }));\n    const lead = available\n      .sort((a, b) => b.at - a.at)\n      .slice(0, leading)\n      .map((s) => ({\n        stream: s.stream,\n        source: s.source,\n        at: s.at,\n        lagging: false,\n      }));\n    // deduplicate (a stream can appear in both frontiers)\n    const seen = new Set<string>();\n    const combined = [...lag, ...lead].filter((p) => {\n      if (seen.has(p.stream)) return false;\n      seen.add(p.stream);\n      return true;\n    });\n    // lease each atomically\n    return combined\n      .map((p) =>\n        this._streams.get(p.stream)?.lease({ ...p, by, retry: 0 }, millis)\n      )\n      .filter((l) => !!l);\n  }\n\n  /**\n   * Registers streams for event processing. When the same stream is\n   * resubscribed with a different priority, the **maximum** wins — so\n   * the highest-priority registered reaction sets the scheduling lane.\n   * Use {@link prioritize} for operator runtime overrides.\n   *\n   * @param streams - Streams to register with optional source + priority.\n   * @returns subscribed count and current max watermark.\n   */\n  async subscribe(\n    streams: Array<{ stream: string; source?: string; priority?: number }>\n  ) {\n    await sleep();\n    let subscribed = 0;\n    for (const { stream, source, priority = 0 } of streams) {\n      const existing = this._streams.get(stream);\n      if (existing) {\n        existing.bumpPriority(priority);\n      } else {\n        this._streams.set(stream, new InMemoryStream(stream, source, priority));\n        subscribed++;\n      }\n    }\n    let watermark = -1;\n    for (const s of this._streams.values()) {\n      if (s.at > watermark) watermark = s.at;\n    }\n    return { subscribed, watermark };\n  }\n\n  /**\n   * Acknowledge completion of processing for leased streams.\n   * @param leases - Leases to acknowledge, including last processed watermark and lease holder.\n   */\n  async ack(leases: Lease[]) {\n    await sleep();\n    return leases\n      .map((l) => this._streams.get(l.stream)?.ack(l))\n      .filter((l) => !!l);\n  }\n\n  /**\n   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.\n   * @param leases - Leases to block, including lease holder and last error message.\n   * @returns Blocked leases.\n   */\n  async block(leases: BlockedLease[]) {\n    await sleep();\n    return leases\n      .map((l) => this._streams.get(l.stream)?.block(l, l.error))\n      .filter((l) => !!l);\n  }\n\n  /**\n   * Reset watermarks for the given streams to -1, clearing retry, blocked,\n   * error, and lease state so they can be replayed from the beginning.\n   * @param streams - Stream names to reset.\n   * @returns Count of streams that were actually reset.\n   */\n  async reset(streams: string[]) {\n    await sleep();\n    let count = 0;\n    for (const name of streams) {\n      const s = this._streams.get(name);\n      if (s) {\n        s.reset();\n        count++;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Bulk-update priority of streams matching `filter`. Mirrors\n   * {@link query_streams}'s filter semantics — see {@link Store.prioritize}.\n   * Unlike {@link subscribe} (which keeps `max()` of registered\n   * priorities), this sets the priority outright — operator override\n   * for the build-time scheduling policy.\n   *\n   * @returns Count of streams whose priority changed.\n   */\n  async prioritize(filter: PrioritizeFilter, priority: number) {\n    await sleep();\n    const streamRe =\n      filter.stream && !filter.stream_exact\n        ? new RegExp(filter.stream)\n        : undefined;\n    const sourceRe =\n      filter.source && !filter.source_exact\n        ? new RegExp(filter.source)\n        : undefined;\n    let count = 0;\n    for (const s of this._streams.values()) {\n      if (filter.stream !== undefined) {\n        if (\n          filter.stream_exact\n            ? s.stream !== filter.stream\n            : !streamRe!.test(s.stream)\n        )\n          continue;\n      }\n      if (filter.source !== undefined) {\n        if (s.source === undefined) continue;\n        if (\n          filter.source_exact\n            ? s.source !== filter.source\n            : !sourceRe!.test(s.source)\n        )\n          continue;\n      }\n      if (filter.blocked !== undefined && s.blocked !== filter.blocked)\n        continue;\n      if (s.priority !== priority) {\n        s.setPriority(priority);\n        count++;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Streams registered subscription positions to the callback, ordered by\n   * stream name. Returns the highest event id in the store and the count\n   * of positions emitted.\n   */\n  async query_streams(\n    callback: (position: StreamPosition) => void,\n    query?: QueryStreams\n  ): Promise<QueryStreamsResult> {\n    await sleep();\n    const limit = query?.limit ?? 100;\n    const after = query?.after;\n    const blocked = query?.blocked;\n    const streamRe =\n      query?.stream && !query.stream_exact\n        ? new RegExp(query.stream)\n        : undefined;\n    const sourceRe =\n      query?.source && !query.source_exact\n        ? new RegExp(query.source)\n        : undefined;\n\n    const sorted = [...this._streams.values()].sort((a, b) =>\n      a.stream.localeCompare(b.stream)\n    );\n\n    let count = 0;\n    for (const s of sorted) {\n      if (after !== undefined && s.stream <= after) continue;\n      if (query?.stream !== undefined) {\n        if (\n          query.stream_exact\n            ? s.stream !== query.stream\n            : !streamRe!.test(s.stream)\n        )\n          continue;\n      }\n      if (query?.source !== undefined) {\n        if (s.source === undefined) continue;\n        if (\n          query.source_exact\n            ? s.source !== query.source\n            : !sourceRe!.test(s.source)\n        )\n          continue;\n      }\n      if (blocked !== undefined && s.blocked !== blocked) continue;\n      callback({\n        stream: s.stream,\n        source: s.source,\n        at: s.at,\n        retry: s.retry,\n        blocked: s.blocked,\n        error: s.error,\n        priority: s.priority,\n        leased_by: s.leased_by,\n        leased_until: s.leased_until,\n      });\n      count++;\n      if (count >= limit) break;\n    }\n    return { maxEventId: this._events.length - 1, count };\n  }\n\n  /**\n   * Atomically truncates streams and seeds each with a snapshot or tombstone.\n   * @param targets - Streams to truncate with optional snapshot state and meta.\n   * @returns Map keyed by stream name, each entry with `deleted` count and `committed` event.\n   */\n  async truncate(\n    targets: Array<{\n      stream: string;\n      snapshot?: Schema;\n      meta?: EventMeta;\n    }>\n  ) {\n    await sleep();\n    // Count per-stream deletions\n    const deletedCounts = new Map<string, number>();\n    const streamSet = new Set(targets.map((t) => t.stream));\n    for (const e of this._events) {\n      if (streamSet.has(e.stream)) {\n        deletedCounts.set(e.stream, (deletedCounts.get(e.stream) ?? 0) + 1);\n      }\n    }\n    this._events = this._events.filter((e) => !streamSet.has(e.stream));\n    for (const stream of streamSet) {\n      this._streams.delete(stream);\n      this._streamVersions.delete(stream);\n      this._maxEventIdByStream.delete(stream);\n    }\n    const result = new Map<\n      string,\n      { deleted: number; committed: Committed<Schemas, keyof Schemas> }\n    >();\n    for (const { stream, snapshot, meta } of targets) {\n      const event: Committed<Schemas, keyof Schemas> = {\n        id: this._events.length,\n        stream,\n        version: 0,\n        created: new Date(),\n        name: snapshot !== undefined ? SNAP_EVENT : TOMBSTONE_EVENT,\n        data: snapshot ?? {},\n        meta: meta ?? { correlation: \"\", causation: {} },\n      };\n      this._events.push(event);\n      this._streamVersions.set(stream, 0);\n      if (event.name !== SNAP_EVENT) {\n        this._maxEventIdByStream.set(stream, event.id);\n      }\n      result.set(stream, {\n        deleted: deletedCounts.get(stream) ?? 0,\n        committed: event,\n      });\n    }\n    // Recompute global max from the per-stream index — deletions may have\n    // dropped the previous max, while new tombstones may have raised it.\n    let max = -1;\n    for (const id of this._maxEventIdByStream.values()) if (id > max) max = id;\n    this._maxNonSnapEventId = max;\n    return result;\n  }\n}\n"],"mappings":"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","names":["log","store","cache"]}

package/dist/index.cjs

@@ -190,7 +190,7 @@ var ConsoleLogger = class _ConsoleLogger {
   }
 };
 
-// src/lru-map.ts
+// src/internal/lru-map.ts
 var LruMap = class {
   constructor(_maxSize) {
     this._maxSize = _maxSize;
@@ -1090,7 +1090,6 @@ function classifyRegistry(registry, states) {
 }
 
 // src/internal/close-cycle.ts
-var import_node_crypto = require("crypto");
 async function runCloseCycle(targets, deps) {
   const targetMap = new Map(targets.map((t) => [t.stream, t]));
   const streams = [...targetMap.keys()];
@@ -1102,11 +1101,10 @@ async function runCloseCycle(targets, deps) {
     skipped
   );
   if (!safe.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
-  const correlation = (0, import_node_crypto.randomUUID)();
   const { guarded, guardEvents } = await guardWithTombstones(
     safe,
     streamInfo,
-    correlation,
+    deps.correlation,
     deps.tombstone,
     skipped
   );
@@ -1124,7 +1122,7 @@ async function runCloseCycle(targets, deps) {
     guarded,
     seedStates,
     guardEvents,
-    correlation
+    deps.correlation
   );
   return { truncated, skipped };
 }
@@ -1365,6 +1363,30 @@ 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 defaultCorrelator = ({ 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 closeCorrelation(correlator, actor) {
+  return correlator({
+    state: "$close",
+    action: "close",
+    stream: "$close",
+    actor
+  });
+}
+
 // src/internal/drain-cycle.ts
 var import_node_crypto2 = require("crypto");
 
@@ -1387,10 +1409,20 @@ function computeLagLeadRatio(handled, lagging, leading) {
 }
 
 // src/internal/drain-cycle.ts
-async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch, lagging, leading, eventLimit, leaseMillis) {
+async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch, lagging, leading, eventLimit, leaseMillis, isDeferred) {
   const leased = await ops.claim(lagging, leading, (0, import_node_crypto2.randomUUID)(), leaseMillis);
   if (!leased.length) return void 0;
-  const fetched = await ops.fetch(leased, eventLimit);
+  const active = isDeferred ? leased.filter((l) => !isDeferred(l.stream)) : leased;
+  if (!active.length) {
+    return {
+      leased,
+      fetched: [],
+      handled: [],
+      acked: [],
+      blocked: []
+    };
+  }
+  const fetched = await ops.fetch(active, eventLimit);
   const fetchMap = /* @__PURE__ */ new Map();
   const fetch_window_at = fetched.reduce(
     (max, { at, events }) => Math.max(max, events.at(-1)?.id || at),
@@ -1409,7 +1441,7 @@ async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch,
     fetchMap.set(stream, { fetch: f, payloads });
   }
   const handled = await Promise.all(
-    leased.map((lease) => {
+    active.map((lease) => {
       const entry = fetchMap.get(lease.stream);
       const at = entry.fetch.events.at(-1)?.id || fetch_window_at;
       const { payloads } = entry;
@@ -1441,6 +1473,15 @@ var DrainController = class {
   _armed = false;
   _locked = false;
   _ratio = 0.5;
+  /**
+   * Per-stream backoff: `stream → nextAttemptAt` (ms since epoch). Set by
+   * `_finalize` via `HandleResult.nextAttemptAt`; 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).
+   */
+  _backoff = /* @__PURE__ */ new Map();
+  /** Timer re-arming drain at the earliest pending `nextAttemptAt`. */
+  _backoffTimer;
   /**
    * Signal that a commit (or reset / cold-start) may have produced work.
    * Subsequent `drain()` calls will run the pipeline; once the pipeline
@@ -1453,6 +1494,32 @@ var DrainController = class {
   get armed() {
     return this._armed;
   }
+  /** Returns true when `stream` is currently within a backoff window. */
+  isDeferred = (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.
+   */
+  scheduleBackoffWake() {
+    if (this._backoffTimer) clearTimeout(this._backoffTimer);
+    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._backoffTimer = setTimeout(() => {
+      this._backoffTimer = 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._backoffTimer.unref();
+  }
   /** Run one drain pass. Short-circuits when not armed or already running. */
   async drain({
     streamLimit = 10,
@@ -1474,7 +1541,8 @@ var DrainController = class {
         lagging,
         leading,
         eventLimit,
-        leaseMillis
+        leaseMillis,
+        this._backoff.size > 0 ? this.isDeferred : void 0
       );
       if (!cycle) {
         this._armed = false;
@@ -1482,6 +1550,14 @@ var DrainController = class {
       }
       const { leased, fetched, handled, acked, blocked } = cycle;
       this._ratio = computeLagLeadRatio(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 h of handled) {
+        if (h.nextAttemptAt !== void 0 && !h.block) {
+          this._backoff.set(h.lease.stream, h.nextAttemptAt);
+        }
+      }
+      if (this._backoff.size > 0) this.scheduleBackoffWake();
       if (acked.length) this.deps.onAcked(acked);
       if (blocked.length) this.deps.onBlocked(blocked);
       const hasErrors = handled.some(({ error }) => error);
@@ -1676,6 +1752,27 @@ var _this_ = ({ stream }) => ({
   target: stream
 });
 
+// src/internal/backoff.ts
+function computeBackoffDelay(retry, opts) {
+  if (!opts || opts.baseMs <= 0) return 0;
+  const r = Math.max(0, retry);
+  let delay;
+  switch (opts.strategy) {
+    case "fixed":
+      delay = opts.baseMs;
+      break;
+    case "linear":
+      delay = opts.baseMs * (r + 1);
+      break;
+    case "exponential":
+      delay = opts.baseMs * 2 ** r;
+      if (opts.maxMs !== void 0) delay = Math.min(delay, opts.maxMs);
+      break;
+  }
+  if (opts.jitter) delay = delay * (0.5 + Math.random());
+  return Math.max(0, Math.floor(delay));
+}
+
 // src/internal/reactions.ts
 function finalize(lease, handled, at, error, options, logger) {
   if (!error) return { lease, handled, at };
@@ -1683,12 +1780,14 @@ function finalize(lease, handled, at, error, options, logger) {
   const block2 = lease.retry >= options.maxRetries && options.blockOnError;
   if (block2)
     logger.error(`Blocking ${lease.stream} after ${lease.retry} retries.`);
+  const nextAttemptAt = !block2 && options.backoff ? Date.now() + computeBackoffDelay(lease.retry, options.backoff) : void 0;
   return {
     lease,
     handled,
     at,
     error: handled === 0 ? error.message : void 0,
-    block: block2
+    block: block2,
+    nextAttemptAt
   };
 }
 function buildHandle(deps) {
@@ -1830,7 +1929,6 @@ var block = (leases) => store2().block(leases);
 var subscribe = (streams) => store2().subscribe(streams);
 
 // src/internal/event-sourcing.ts
-var import_node_crypto3 = require("crypto");
 var import_act_patch = require("@rotorsoft/act-patch");
 async function snap(snapshot) {
   try {
@@ -1918,7 +2016,7 @@ async function load(me, stream, callback, asOf) {
   }
   return { event, state: state2, version, patches, snaps, cache_hit, replayed };
 }
-async function action(me, action2, target, payload, reactingTo, skipValidation = false) {
+async function action(me, action2, target, payload, reactingTo, skipValidation = false, correlator = defaultCorrelator) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
   const validated = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
@@ -1964,7 +2062,12 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     data: skipValidation ? data : validate(name, data, me.events[name])
   }));
   const meta = {
-    correlation: reactingTo?.meta.correlation || (0, import_node_crypto3.randomUUID)(),
+    correlation: reactingTo?.meta.correlation || correlator({
+      action: action2,
+      state: me.name,
+      stream,
+      actor: target.actor
+    }),
     causation: {
       action: {
         name: action2,
@@ -2068,12 +2171,21 @@ var traced = (inner, exit, entry) => (async (...args) => {
   exit?.(result, ...args);
   return result;
 });
-function buildEs(logger) {
+function buildEs(logger, correlator = defaultCorrelator) {
+  const boundAction = (me, actionName, target, payload, reactingTo, skipValidation = false) => action(
+    me,
+    actionName,
+    target,
+    payload,
+    reactingTo,
+    skipValidation,
+    correlator
+  );
   if (logger.level !== "trace") {
     return {
       snap,
       load,
-      action,
+      action: boundAction,
       tombstone
     };
   }
@@ -2103,7 +2215,7 @@ function buildEs(logger) {
       );
     }),
     action: traced(
-      action,
+      boundAction,
       (snapshots, _me, _action, target) => {
         const committed = snapshots.filter((s) => s.event);
         if (committed.length) {
@@ -2211,7 +2323,8 @@ var Act = class {
     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._correlator = options.correlator ?? defaultCorrelator;
+    this._es = buildEs(this._logger, this._correlator);
     this._cd = buildDrain(this._logger);
     this._handle = buildHandle({
       logger: this._logger,
@@ -2324,6 +2437,13 @@ var Act = class {
    * path keeps reading fresh `store()`/`cache()` per call, which matters for
    * tests that dispose and re-seed mid-suite. */
   _scoped;
+  /**
+   * Correlation-id generator for originating actions. Bound at
+   * construction from `options.correlator ?? defaultCorrelator`. The
+   * `do()` path passes this into the `_es.action` closure; close-cycle
+   * uses it via {@link closeCorrelation}.
+   */
+  _correlator;
   /** 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);
@@ -2884,12 +3004,14 @@ var Act = class {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
     return this._scoped(async () => {
       await this.correlate({ limit: 1e3 });
+      const closeActor = { id: "$close", name: "close" };
       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
+        logger: this._logger,
+        correlation: closeCorrelation(this._correlator, closeActor)
       });
       this.emit("closed", result);
       return result;
@@ -3008,7 +3130,8 @@ function act() {
           resolver: _this_,
           options: {
             blockOnError: options?.blockOnError ?? true,
-            maxRetries: options?.maxRetries ?? 3
+            maxRetries: options?.maxRetries ?? 3,
+            backoff: options?.backoff
           }
         };
         if (!handler.name)
@@ -3134,7 +3257,8 @@ function slice() {
           resolver: _this_,
           options: {
             blockOnError: options?.blockOnError ?? true,
-            maxRetries: options?.maxRetries ?? 3
+            maxRetries: options?.maxRetries ?? 3,
+            backoff: options?.backoff
           }
         };
         if (!handler.name)