@rotorsoft/act 0.33.0 → 0.33.2

package/dist/@types/types/schemas.d.ts

@@ -1,4 +1,4 @@
-import { z, ZodObject, ZodRawShape } from "zod";
+import { ZodObject, ZodRawShape, z } from "zod";
 /**
  * @packageDocumentation
  * @module act/types
@@ -12,16 +12,16 @@ export declare const ZodEmpty: z.ZodRecord<z.ZodString, z.ZodNever>;
 /**
  * Zod schema for an actor (user, system, etc.).
  */
-export declare const ActorSchema: z.ZodReadonly<z.ZodObject<{
+export declare const ActorSchema: z.ZodReadonly<ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
 }, z.core.$loose>>;
 /**
  * Zod schema for a target (stream and actor info).
  */
-export declare const TargetSchema: z.ZodReadonly<z.ZodObject<{
+export declare const TargetSchema: z.ZodReadonly<ZodObject<{
     stream: z.ZodString;
-    actor: z.ZodReadonly<z.ZodObject<{
+    actor: z.ZodReadonly<ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
     }, z.core.$loose>>;
@@ -30,7 +30,7 @@ export declare const TargetSchema: z.ZodReadonly<z.ZodObject<{
 /**
  * Zod schema for causation event metadata.
  */
-export declare const CausationEventSchema: z.ZodObject<{
+export declare const CausationEventSchema: ZodObject<{
     id: z.ZodNumber;
     name: z.ZodString;
     stream: z.ZodString;
@@ -38,20 +38,20 @@ export declare const CausationEventSchema: z.ZodObject<{
 /**
  * Zod schema for event metadata (correlation and causation).
  */
-export declare const EventMetaSchema: z.ZodReadonly<z.ZodObject<{
+export declare const EventMetaSchema: z.ZodReadonly<ZodObject<{
     correlation: z.ZodString;
-    causation: z.ZodObject<{
-        action: z.ZodOptional<z.ZodIntersection<z.ZodReadonly<z.ZodObject<{
+    causation: ZodObject<{
+        action: z.ZodOptional<z.ZodIntersection<z.ZodReadonly<ZodObject<{
             stream: z.ZodString;
-            actor: z.ZodReadonly<z.ZodObject<{
+            actor: z.ZodReadonly<ZodObject<{
                 id: z.ZodString;
                 name: z.ZodString;
             }, z.core.$loose>>;
             expectedVersion: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$loose>>, z.ZodObject<{
+        }, z.core.$loose>>, ZodObject<{
             name: z.ZodString;
         }, z.core.$strip>>>;
-        event: z.ZodOptional<z.ZodObject<{
+        event: z.ZodOptional<ZodObject<{
             id: z.ZodNumber;
             name: z.ZodString;
             stream: z.ZodString;
@@ -61,25 +61,25 @@ export declare const EventMetaSchema: z.ZodReadonly<z.ZodObject<{
 /**
  * Zod schema for committed event metadata (id, stream, version, created, meta).
  */
-export declare const CommittedMetaSchema: z.ZodReadonly<z.ZodObject<{
+export declare const CommittedMetaSchema: z.ZodReadonly<ZodObject<{
     id: z.ZodNumber;
     stream: z.ZodString;
     version: z.ZodNumber;
     created: z.ZodDate;
-    meta: z.ZodReadonly<z.ZodObject<{
+    meta: z.ZodReadonly<ZodObject<{
         correlation: z.ZodString;
-        causation: z.ZodObject<{
-            action: z.ZodOptional<z.ZodIntersection<z.ZodReadonly<z.ZodObject<{
+        causation: ZodObject<{
+            action: z.ZodOptional<z.ZodIntersection<z.ZodReadonly<ZodObject<{
                 stream: z.ZodString;
-                actor: z.ZodReadonly<z.ZodObject<{
+                actor: z.ZodReadonly<ZodObject<{
                     id: z.ZodString;
                     name: z.ZodString;
                 }, z.core.$loose>>;
                 expectedVersion: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$loose>>, z.ZodObject<{
+            }, z.core.$loose>>, ZodObject<{
                 name: z.ZodString;
             }, z.core.$strip>>>;
-            event: z.ZodOptional<z.ZodObject<{
+            event: z.ZodOptional<ZodObject<{
                 id: z.ZodNumber;
                 name: z.ZodString;
                 stream: z.ZodString;
@@ -101,7 +101,7 @@ export type StateSchema = Readonly<{
 /**
  * Query options for event store queries.
  */
-export declare const QuerySchema: z.ZodReadonly<z.ZodObject<{
+export declare const QuerySchema: z.ZodReadonly<ZodObject<{
     stream: z.ZodOptional<z.ZodString>;
     names: z.ZodOptional<z.ZodArray<z.ZodString>>;
     before: z.ZodOptional<z.ZodNumber>;

package/dist/@types/types/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/types/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEhD;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ,sCAAkC,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,WAAW;;;kBAMX,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;kBAOZ,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;iBAI/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;kBAQf,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;kBAQnB,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IAClE,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;CAC/B,CAAC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;kBAcX,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/types/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEhD;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ,sCAAkC,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,WAAW;;;kBAMX,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;kBAOZ,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;iBAI/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;kBAQf,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;kBAQnB,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IAClE,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;CAC/B,CAAC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;kBAcX,CAAC"}

package/dist/@types/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAiB,MAAM,KAAK,CAAC;AAI5D;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,QAAQ,MAAM,EACd,SAAS,QAAQ,CAAC,CAAC,CAAC,EACpB,SAAS,OAAO,CAAC,CAAC,CAAC,KAClB,QAAQ,CAAC,CAAC,CASZ,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GACjB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,QAAQ,QAAQ,CAAC,CAAC,CAAC,EACnB,QAAQ,OAAO,CAAC,CAAC,CAAC,EAClB,SAAS,QAAQ,CAAC,CAAC,CAAC,KACnB,QAAQ,CAAC,CAAC,GAAG,CAAC,CAGhB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,oBAEtC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAI5D;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,QAAQ,MAAM,EACd,SAAS,QAAQ,CAAC,CAAC,CAAC,EACpB,SAAS,OAAO,CAAC,CAAC,CAAC,KAClB,QAAQ,CAAC,CAAC,CASZ,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GACjB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,QAAQ,QAAQ,CAAC,CAAC,CAAC,EACnB,QAAQ,OAAO,CAAC,CAAC,CAAC,EAClB,SAAS,QAAQ,CAAC,CAAC,CAAC,KACnB,QAAQ,CAAC,CAAC,GAAG,CAAC,CAGhB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,oBAEtC"}

package/dist/{chunk-IDEYGKT4.js → chunk-AWT7TU22.js}

@@ -25,13 +25,6 @@ var InvariantError = class extends Error {
     this.name = Errors.InvariantError;
   }
 };
-var StreamClosedError = class extends Error {
-  constructor(stream) {
-    super(`Stream "${stream}" is closed (tombstoned)`);
-    this.stream = stream;
-    this.name = Errors.StreamClosedError;
-  }
-};
 var ConcurrencyError = class extends Error {
   constructor(stream, lastVersion, events, expectedVersion) {
     super(
@@ -46,6 +39,13 @@ var ConcurrencyError = class extends Error {
     this.name = Errors.ConcurrencyError;
   }
 };
+var StreamClosedError = class extends Error {
+  constructor(stream) {
+    super(`Stream "${stream}" is closed (tombstoned)`);
+    this.stream = stream;
+    this.name = Errors.StreamClosedError;
+  }
+};
 
 // src/types/schemas.ts
 import { z } from "zod";
@@ -112,8 +112,8 @@ export {
   Errors,
   ValidationError,
   InvariantError,
-  StreamClosedError,
   ConcurrencyError,
+  StreamClosedError,
   ZodEmpty,
   ActorSchema,
   TargetSchema,
@@ -124,4 +124,4 @@ export {
   Environments,
   LogLevels
 };
-//# sourceMappingURL=chunk-IDEYGKT4.js.map
+//# sourceMappingURL=chunk-AWT7TU22.js.map

package/dist/{chunk-IDEYGKT4.js.map → chunk-AWT7TU22.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/types/errors.ts","../src/types/schemas.ts","../src/types/index.ts"],"sourcesContent":["import type {\n  Actor,\n  Message,\n  Schema,\n  Schemas,\n  Snapshot,\n  Target,\n} from \"./action.js\";\n\n/**\n * @packageDocumentation\n * @module act/types\n * @category Types\n * Application error type constants and error classes for the Act Framework.\n *\n * - `ERR_VALIDATION`: Schema validation error\n * - `ERR_INVARIANT`: Invariant validation error\n * - `ERR_CONCURRENCY`: Optimistic concurrency validation error on commits\n */\nexport const Errors = {\n  ValidationError: \"ERR_VALIDATION\",\n  InvariantError: \"ERR_INVARIANT\",\n  ConcurrencyError: \"ERR_CONCURRENCY\",\n  StreamClosedError: \"ERR_STREAM_CLOSED\",\n} as const;\n\n/**\n * Thrown when an action or event payload fails Zod schema validation.\n *\n * This error indicates that data doesn't match the expected schema defined\n * for an action or event. The `details` property contains the Zod validation\n * error with specific information about what failed.\n *\n * @example Catching validation errors\n * ```typescript\n * import { ValidationError } from \"@rotorsoft/act\";\n *\n * try {\n *   await app.do(\"createUser\", target, {\n *     email: \"invalid-email\",  // Missing @ symbol\n *     age: -5                  // Negative age\n *   });\n * } catch (error) {\n *   if (error instanceof ValidationError) {\n *     console.error(\"Validation failed for:\", error.target);\n *     console.error(\"Invalid payload:\", error.payload);\n *     console.error(\"Validation details:\", error.details);\n *     // details contains Zod error with field-level info\n *   }\n * }\n * ```\n *\n * @example Logging validation details\n * ```typescript\n * try {\n *   await app.do(\"updateProfile\", target, payload);\n * } catch (error) {\n *   if (error instanceof ValidationError) {\n *     error.details.errors.forEach((err) => {\n *       console.error(`Field ${err.path.join(\".\")}: ${err.message}`);\n *     });\n *   }\n * }\n * ```\n *\n * @see {@link https://zod.dev | Zod documentation} for validation details\n */\nexport class ValidationError extends Error {\n  constructor(\n    /** The type of target being validated (e.g., \"action\", \"event\") */\n    public readonly target: string,\n    /** The invalid payload that failed validation */\n    public readonly payload: any,\n    /** Zod validation error details */\n    public readonly details: any\n  ) {\n    super(`Invalid ${target} payload`);\n    this.name = Errors.ValidationError;\n  }\n}\n\n/**\n * Thrown when a business rule (invariant) is violated during action execution.\n *\n * Invariants are conditions that must hold true for an action to succeed.\n * They're checked after loading the current state but before emitting events.\n * This error provides complete context about what action was attempted and\n * why it was rejected.\n *\n * @template TState - State schema type\n * @template TEvents - Event schemas type\n * @template TActions - Action schemas type\n * @template TKey - Action name\n * @template TActor - Actor type extending base Actor\n *\n * @example Catching invariant violations\n * ```typescript\n * import { InvariantError } from \"@rotorsoft/act\";\n *\n * try {\n *   await app.do(\"withdraw\",\n *     { stream: \"account-123\", actor: { id: \"user1\", name: \"Alice\" } },\n *     { amount: 1000 }\n *   );\n * } catch (error) {\n *   if (error instanceof InvariantError) {\n *     console.error(\"Action:\", error.action);\n *     console.error(\"Reason:\", error.description);\n *     console.error(\"Current state:\", error.snapshot.state);\n *     console.error(\"Attempted payload:\", error.payload);\n *   }\n * }\n * ```\n *\n * @example User-friendly error messages\n * ```typescript\n * try {\n *   await app.do(\"closeTicket\", target, payload);\n * } catch (error) {\n *   if (error instanceof InvariantError) {\n *     // Present friendly message to user\n *     if (error.description === \"Ticket must be open\") {\n *       return { error: \"This ticket is already closed\" };\n *     } else if (error.description === \"Not authorized\") {\n *       return { error: \"You don't have permission to close this ticket\" };\n *     }\n *   }\n * }\n * ```\n *\n * @example Logging with context\n * ```typescript\n * try {\n *   await app.do(\"transfer\", target, { to: \"account2\", amount: 500 });\n * } catch (error) {\n *   if (error instanceof InvariantError) {\n *     logger.error({\n *       action: error.action,\n *       stream: error.target.stream,\n *       actor: error.target.actor,\n *       reason: error.description,\n *       balance: error.snapshot.state.balance,\n *       attempted: error.payload.amount\n *     }, \"Invariant violation\");\n *   }\n * }\n * ```\n *\n * @see {@link Invariant} for defining business rules\n */\nexport class InvariantError<\n  TState extends Schema,\n  TEvents extends Schemas,\n  TActions extends Schemas,\n  TKey extends keyof TActions,\n  TActor extends Actor = Actor,\n> extends Error {\n  constructor(\n    /** The action that was attempted */\n    readonly action: TKey,\n    /** The action payload that was provided */\n    readonly payload: Readonly<TActions[TKey]>,\n    /** The target stream and actor context */\n    readonly target: Target<TActor>,\n    /** The current state snapshot when invariant was checked */\n    readonly snapshot: Snapshot<TState, TEvents>,\n    /** Human-readable description of why the invariant failed */\n    readonly description: string\n  ) {\n    super(`${action as string} failed invariant: ${description}`);\n    this.name = Errors.InvariantError;\n  }\n}\n\n/**\n * Thrown when optimistic concurrency control detects a conflict.\n *\n * This error occurs when trying to commit events to a stream that has been\n * modified by another process since it was last loaded. The version number\n * doesn't match expectations, indicating a concurrent modification.\n *\n * This is a normal occurrence in distributed systems and should be handled\n * by reloading the current state and retrying the action.\n *\n * @example Handling concurrency conflicts with retry\n * ```typescript\n * import { ConcurrencyError } from \"@rotorsoft/act\";\n *\n * async function transferWithRetry(from, to, amount, maxRetries = 3) {\n *   for (let attempt = 0; attempt < maxRetries; attempt++) {\n *     try {\n *       await app.do(\"transfer\",\n *         { stream: from, actor: currentUser },\n *         { to, amount }\n *       );\n *       return { success: true };\n *     } catch (error) {\n *       if (error instanceof ConcurrencyError) {\n *         if (attempt < maxRetries - 1) {\n *           console.log(`Concurrent modification detected, retrying... (${attempt + 1}/${maxRetries})`);\n *           await sleep(100 * Math.pow(2, attempt)); // Exponential backoff\n *           continue;\n *         }\n *       }\n *       throw error;\n *     }\n *   }\n *   return { success: false, reason: \"Too many concurrent modifications\" };\n * }\n * ```\n *\n * @example Logging concurrency conflicts\n * ```typescript\n * try {\n *   await app.do(\"updateInventory\", target, payload);\n * } catch (error) {\n *   if (error instanceof ConcurrencyError) {\n *     logger.warn({\n *       stream: error.stream,\n *       expectedVersion: error.expectedVersion,\n *       actualVersion: error.lastVersion,\n *       events: error.events.map(e => e.name)\n *     }, \"Concurrent modification detected\");\n *   }\n * }\n * ```\n *\n * @example User feedback for conflicts\n * ```typescript\n * try {\n *   await app.do(\"editDocument\", target, { content: newContent });\n * } catch (error) {\n *   if (error instanceof ConcurrencyError) {\n *     return {\n *       error: \"This document was modified by another user. Please refresh and try again.\",\n *       code: \"CONCURRENT_MODIFICATION\"\n *     };\n *   }\n * }\n * ```\n *\n * @see {@link Store.commit} for version checking details\n */\n/**\n * Thrown when attempting to write to a stream that has been closed\n * with a tombstone event.\n *\n * A tombstoned stream is permanently closed — no further actions can\n * be executed against it. The only way to reopen a tombstoned stream\n * is through `Act.close()` with a `restart` callback.\n *\n * @example\n * ```typescript\n * import { StreamClosedError } from \"@rotorsoft/act\";\n *\n * try {\n *   await app.do(\"updateTicket\", target, payload);\n * } catch (error) {\n *   if (error instanceof StreamClosedError) {\n *     console.error(`Stream ${error.stream} is closed`);\n *   }\n * }\n * ```\n *\n * @see {@link Act.close} for closing streams\n */\nexport class StreamClosedError extends Error {\n  constructor(\n    /** The stream that is closed */\n    public readonly stream: string\n  ) {\n    super(`Stream \"${stream}\" is closed (tombstoned)`);\n    this.name = Errors.StreamClosedError;\n  }\n}\n\nexport class ConcurrencyError extends Error {\n  constructor(\n    /** The stream that had the concurrent modification */\n    public readonly stream: string,\n    /** The actual current version in the store */\n    public readonly lastVersion: number,\n    /** The events that were being committed */\n    public readonly events: Message<Schemas, keyof Schemas>[],\n    /** The version number that was expected */\n    public readonly expectedVersion: number\n  ) {\n    // Message lists stream + event names only. Payloads remain accessible\n    // via `error.events` for callers who need them — keeping them out of\n    // the message avoids MB-scale strings on contended writes and keeps\n    // potentially-sensitive data out of log streams.\n    super(\n      `Concurrency error committing \"${events\n        .map((e) => `${stream}.${e.name}`)\n        .join(\n          \", \"\n        )}\". Expected version ${expectedVersion} but found version ${lastVersion}.`\n    );\n    this.name = Errors.ConcurrencyError;\n  }\n}\n","import { z, ZodObject, ZodRawShape } from \"zod\";\n\n/**\n * @packageDocumentation\n * @module act/types\n * @category Types\n * Zod schemas and helpers for the Act Framework.\n */\n\n/**\n * An empty Zod schema (no properties).\n */\nexport const ZodEmpty = z.record(z.string(), z.never());\n\n/**\n * Zod schema for an actor (user, system, etc.).\n */\nexport const ActorSchema = z\n  .object({\n    id: z.string(),\n    name: z.string(),\n  })\n  .loose()\n  .readonly();\n\n/**\n * Zod schema for a target (stream and actor info).\n */\nexport const TargetSchema = z\n  .object({\n    stream: z.string(),\n    actor: ActorSchema,\n    expectedVersion: z.number().optional(),\n  })\n  .loose()\n  .readonly();\n\n/**\n * Zod schema for causation event metadata.\n */\nexport const CausationEventSchema = z.object({\n  id: z.number(),\n  name: z.string(),\n  stream: z.string(),\n});\n\n/**\n * Zod schema for event metadata (correlation and causation).\n */\nexport const EventMetaSchema = z\n  .object({\n    correlation: z.string(),\n    causation: z.object({\n      action: TargetSchema.and(z.object({ name: z.string() })).optional(),\n      event: CausationEventSchema.optional(),\n    }),\n  })\n  .readonly();\n\n/**\n * Zod schema for committed event metadata (id, stream, version, created, meta).\n */\nexport const CommittedMetaSchema = z\n  .object({\n    id: z.number(),\n    stream: z.string(),\n    version: z.number(),\n    created: z.date(),\n    meta: EventMetaSchema,\n  })\n  .readonly();\n\n/**\n * Type representing the full state schema for a domain.\n * @property events - Map of event names to Zod schemas.\n * @property actions - Map of action names to Zod schemas.\n * @property state - Zod schema for the state object.\n */\nexport type StateSchema = Readonly<{\n  events: Record<string, ZodObject<ZodRawShape> | typeof ZodEmpty>;\n  actions: Record<string, ZodObject<ZodRawShape> | typeof ZodEmpty>;\n  state: ZodObject<ZodRawShape>;\n}>;\n\n/**\n * Query options for event store queries.\n */\nexport const QuerySchema = z\n  .object({\n    stream: z.string().optional(),\n    names: z.string().array().optional(),\n    before: z.number().optional(),\n    after: z.number().optional(),\n    limit: z.number().optional(),\n    created_before: z.date().optional(),\n    created_after: z.date().optional(),\n    backward: z.boolean().optional(),\n    correlation: z.string().optional(),\n    with_snaps: z.boolean().optional(),\n    stream_exact: z.boolean().optional(),\n  })\n  .readonly();\n","/**\n * @packageDocumentation\n * @module act/types\n * Barrel file for Act Framework core types.\n *\n * Re-exports all major type definitions for actions, errors, ports, reactions, registries, and schemas.\n * Also defines common environment and log level types/constants for configuration and logging.\n *\n * @remarks\n * Import from this module to access all core framework types in one place.\n */\nexport type * from \"./action.js\";\nexport * from \"./errors.js\";\nexport type * from \"./ports.js\";\nexport type * from \"./reaction.js\";\nexport type * from \"./registry.js\";\nexport * from \"./schemas.js\";\n\n/**\n * Supported runtime environments for the framework.\n * - `development`: Local development\n * - `test`: Automated testing\n * - `staging`: Pre-production\n * - `production`: Live/production\n */\nexport const Environments = [\n  \"development\",\n  \"test\",\n  \"staging\",\n  \"production\",\n] as const;\n\n/**\n * Type representing a valid environment string.\n */\nexport type Environment = (typeof Environments)[number];\n\n/**\n * Supported log levels for framework logging.\n * - `fatal`, `error`, `warn`, `info`, `debug`, `trace`\n */\nexport const LogLevels = [\n  \"fatal\",\n  \"error\",\n  \"warn\",\n  \"info\",\n  \"debug\",\n  \"trace\",\n] as const;\n\n/**\n * Type representing a valid log level string.\n */\nexport type LogLevel = (typeof LogLevels)[number];\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/types/errors.ts","../src/types/schemas.ts","../src/types/index.ts"],"sourcesContent":["import type {\n  Actor,\n  Message,\n  Schema,\n  Schemas,\n  Snapshot,\n  Target,\n} from \"./action.js\";\n\n/**\n * @packageDocumentation\n * @module act/types\n * @category Types\n * Application error type constants and error classes for the Act Framework.\n *\n * - `ERR_VALIDATION`: Schema validation error\n * - `ERR_INVARIANT`: Invariant validation error\n * - `ERR_CONCURRENCY`: Optimistic concurrency validation error on commits\n */\nexport const Errors = {\n  ValidationError: \"ERR_VALIDATION\",\n  InvariantError: \"ERR_INVARIANT\",\n  ConcurrencyError: \"ERR_CONCURRENCY\",\n  StreamClosedError: \"ERR_STREAM_CLOSED\",\n} as const;\n\n/**\n * Thrown when an action or event payload fails Zod schema validation.\n *\n * This error indicates that data doesn't match the expected schema defined\n * for an action or event. The `details` property contains the Zod validation\n * error with specific information about what failed.\n *\n * @example Catching validation errors\n * ```typescript\n * import { ValidationError } from \"@rotorsoft/act\";\n *\n * try {\n *   await app.do(\"createUser\", target, {\n *     email: \"invalid-email\",  // Missing @ symbol\n *     age: -5                  // Negative age\n *   });\n * } catch (error) {\n *   if (error instanceof ValidationError) {\n *     console.error(\"Validation failed for:\", error.target);\n *     console.error(\"Invalid payload:\", error.payload);\n *     console.error(\"Validation details:\", error.details);\n *     // details contains Zod error with field-level info\n *   }\n * }\n * ```\n *\n * @example Logging validation details\n * ```typescript\n * try {\n *   await app.do(\"updateProfile\", target, payload);\n * } catch (error) {\n *   if (error instanceof ValidationError) {\n *     error.details.errors.forEach((err) => {\n *       console.error(`Field ${err.path.join(\".\")}: ${err.message}`);\n *     });\n *   }\n * }\n * ```\n *\n * @see {@link https://zod.dev | Zod documentation} for validation details\n */\nexport class ValidationError extends Error {\n  constructor(\n    /** The type of target being validated (e.g., \"action\", \"event\") */\n    public readonly target: string,\n    /** The invalid payload that failed validation */\n    public readonly payload: any,\n    /** Zod validation error details */\n    public readonly details: any\n  ) {\n    super(`Invalid ${target} payload`);\n    this.name = Errors.ValidationError;\n  }\n}\n\n/**\n * Thrown when a business rule (invariant) is violated during action execution.\n *\n * Invariants are conditions that must hold true for an action to succeed.\n * They're checked after loading the current state but before emitting events.\n * This error provides complete context about what action was attempted and\n * why it was rejected.\n *\n * @template TState - State schema type\n * @template TEvents - Event schemas type\n * @template TActions - Action schemas type\n * @template TKey - Action name\n * @template TActor - Actor type extending base Actor\n *\n * @example Catching invariant violations\n * ```typescript\n * import { InvariantError } from \"@rotorsoft/act\";\n *\n * try {\n *   await app.do(\"withdraw\",\n *     { stream: \"account-123\", actor: { id: \"user1\", name: \"Alice\" } },\n *     { amount: 1000 }\n *   );\n * } catch (error) {\n *   if (error instanceof InvariantError) {\n *     console.error(\"Action:\", error.action);\n *     console.error(\"Reason:\", error.description);\n *     console.error(\"Current state:\", error.snapshot.state);\n *     console.error(\"Attempted payload:\", error.payload);\n *   }\n * }\n * ```\n *\n * @example User-friendly error messages\n * ```typescript\n * try {\n *   await app.do(\"closeTicket\", target, payload);\n * } catch (error) {\n *   if (error instanceof InvariantError) {\n *     // Present friendly message to user\n *     if (error.description === \"Ticket must be open\") {\n *       return { error: \"This ticket is already closed\" };\n *     } else if (error.description === \"Not authorized\") {\n *       return { error: \"You don't have permission to close this ticket\" };\n *     }\n *   }\n * }\n * ```\n *\n * @example Logging with context\n * ```typescript\n * try {\n *   await app.do(\"transfer\", target, { to: \"account2\", amount: 500 });\n * } catch (error) {\n *   if (error instanceof InvariantError) {\n *     logger.error({\n *       action: error.action,\n *       stream: error.target.stream,\n *       actor: error.target.actor,\n *       reason: error.description,\n *       balance: error.snapshot.state.balance,\n *       attempted: error.payload.amount\n *     }, \"Invariant violation\");\n *   }\n * }\n * ```\n *\n * @see {@link Invariant} for defining business rules\n */\nexport class InvariantError<\n  TState extends Schema,\n  TEvents extends Schemas,\n  TActions extends Schemas,\n  TKey extends keyof TActions,\n  TActor extends Actor = Actor,\n> extends Error {\n  constructor(\n    /** The action that was attempted */\n    readonly action: TKey,\n    /** The action payload that was provided */\n    readonly payload: Readonly<TActions[TKey]>,\n    /** The target stream and actor context */\n    readonly target: Target<TActor>,\n    /** The current state snapshot when invariant was checked */\n    readonly snapshot: Snapshot<TState, TEvents>,\n    /** Human-readable description of why the invariant failed */\n    readonly description: string\n  ) {\n    super(`${action as string} failed invariant: ${description}`);\n    this.name = Errors.InvariantError;\n  }\n}\n\n/**\n * Thrown when optimistic concurrency control detects a conflict.\n *\n * This error occurs when trying to commit events to a stream that has been\n * modified by another process since it was last loaded. The version number\n * doesn't match expectations, indicating a concurrent modification.\n *\n * This is a normal occurrence in distributed systems and should be handled\n * by reloading the current state and retrying the action.\n *\n * @example Handling concurrency conflicts with retry\n * ```typescript\n * import { ConcurrencyError } from \"@rotorsoft/act\";\n *\n * async function transferWithRetry(from, to, amount, maxRetries = 3) {\n *   for (let attempt = 0; attempt < maxRetries; attempt++) {\n *     try {\n *       await app.do(\"transfer\",\n *         { stream: from, actor: currentUser },\n *         { to, amount }\n *       );\n *       return { success: true };\n *     } catch (error) {\n *       if (error instanceof ConcurrencyError) {\n *         if (attempt < maxRetries - 1) {\n *           console.log(`Concurrent modification detected, retrying... (${attempt + 1}/${maxRetries})`);\n *           await sleep(100 * Math.pow(2, attempt)); // Exponential backoff\n *           continue;\n *         }\n *       }\n *       throw error;\n *     }\n *   }\n *   return { success: false, reason: \"Too many concurrent modifications\" };\n * }\n * ```\n *\n * @example Logging concurrency conflicts\n * ```typescript\n * try {\n *   await app.do(\"updateInventory\", target, payload);\n * } catch (error) {\n *   if (error instanceof ConcurrencyError) {\n *     logger.warn({\n *       stream: error.stream,\n *       expectedVersion: error.expectedVersion,\n *       actualVersion: error.lastVersion,\n *       events: error.events.map(e => e.name)\n *     }, \"Concurrent modification detected\");\n *   }\n * }\n * ```\n *\n * @example User feedback for conflicts\n * ```typescript\n * try {\n *   await app.do(\"editDocument\", target, { content: newContent });\n * } catch (error) {\n *   if (error instanceof ConcurrencyError) {\n *     return {\n *       error: \"This document was modified by another user. Please refresh and try again.\",\n *       code: \"CONCURRENT_MODIFICATION\"\n *     };\n *   }\n * }\n * ```\n *\n * @see {@link Store.commit} for version checking details\n */\nexport class ConcurrencyError extends Error {\n  constructor(\n    /** The stream that had the concurrent modification */\n    public readonly stream: string,\n    /** The actual current version in the store */\n    public readonly lastVersion: number,\n    /** The events that were being committed */\n    public readonly events: Message<Schemas, keyof Schemas>[],\n    /** The version number that was expected */\n    public readonly expectedVersion: number\n  ) {\n    // Message lists stream + event names only. Payloads remain accessible\n    // via `error.events` for callers who need them — keeping them out of\n    // the message avoids MB-scale strings on contended writes and keeps\n    // potentially-sensitive data out of log streams.\n    super(\n      `Concurrency error committing \"${events\n        .map((e) => `${stream}.${e.name}`)\n        .join(\n          \", \"\n        )}\". Expected version ${expectedVersion} but found version ${lastVersion}.`\n    );\n    this.name = Errors.ConcurrencyError;\n  }\n}\n\n/**\n * Thrown when attempting to write to a stream that has been closed\n * with a tombstone event.\n *\n * A tombstoned stream is permanently closed — no further actions can\n * be executed against it. The only way to reopen a tombstoned stream\n * is through `Act.close()` with a `restart` callback.\n *\n * @example\n * ```typescript\n * import { StreamClosedError } from \"@rotorsoft/act\";\n *\n * try {\n *   await app.do(\"updateTicket\", target, payload);\n * } catch (error) {\n *   if (error instanceof StreamClosedError) {\n *     console.error(`Stream ${error.stream} is closed`);\n *   }\n * }\n * ```\n *\n * @see {@link Act.close} for closing streams\n */\nexport class StreamClosedError extends Error {\n  constructor(\n    /** The stream that is closed */\n    public readonly stream: string\n  ) {\n    super(`Stream \"${stream}\" is closed (tombstoned)`);\n    this.name = Errors.StreamClosedError;\n  }\n}\n","import { ZodObject, ZodRawShape, z } from \"zod\";\n\n/**\n * @packageDocumentation\n * @module act/types\n * @category Types\n * Zod schemas and helpers for the Act Framework.\n */\n\n/**\n * An empty Zod schema (no properties).\n */\nexport const ZodEmpty = z.record(z.string(), z.never());\n\n/**\n * Zod schema for an actor (user, system, etc.).\n */\nexport const ActorSchema = z\n  .object({\n    id: z.string(),\n    name: z.string(),\n  })\n  .loose()\n  .readonly();\n\n/**\n * Zod schema for a target (stream and actor info).\n */\nexport const TargetSchema = z\n  .object({\n    stream: z.string(),\n    actor: ActorSchema,\n    expectedVersion: z.number().optional(),\n  })\n  .loose()\n  .readonly();\n\n/**\n * Zod schema for causation event metadata.\n */\nexport const CausationEventSchema = z.object({\n  id: z.number(),\n  name: z.string(),\n  stream: z.string(),\n});\n\n/**\n * Zod schema for event metadata (correlation and causation).\n */\nexport const EventMetaSchema = z\n  .object({\n    correlation: z.string(),\n    causation: z.object({\n      action: TargetSchema.and(z.object({ name: z.string() })).optional(),\n      event: CausationEventSchema.optional(),\n    }),\n  })\n  .readonly();\n\n/**\n * Zod schema for committed event metadata (id, stream, version, created, meta).\n */\nexport const CommittedMetaSchema = z\n  .object({\n    id: z.number(),\n    stream: z.string(),\n    version: z.number(),\n    created: z.date(),\n    meta: EventMetaSchema,\n  })\n  .readonly();\n\n/**\n * Type representing the full state schema for a domain.\n * @property events - Map of event names to Zod schemas.\n * @property actions - Map of action names to Zod schemas.\n * @property state - Zod schema for the state object.\n */\nexport type StateSchema = Readonly<{\n  events: Record<string, ZodObject<ZodRawShape> | typeof ZodEmpty>;\n  actions: Record<string, ZodObject<ZodRawShape> | typeof ZodEmpty>;\n  state: ZodObject<ZodRawShape>;\n}>;\n\n/**\n * Query options for event store queries.\n */\nexport const QuerySchema = z\n  .object({\n    stream: z.string().optional(),\n    names: z.string().array().optional(),\n    before: z.number().optional(),\n    after: z.number().optional(),\n    limit: z.number().optional(),\n    created_before: z.date().optional(),\n    created_after: z.date().optional(),\n    backward: z.boolean().optional(),\n    correlation: z.string().optional(),\n    with_snaps: z.boolean().optional(),\n    stream_exact: z.boolean().optional(),\n  })\n  .readonly();\n","/**\n * @packageDocumentation\n * @module act/types\n * Barrel file for Act Framework core types.\n *\n * Re-exports all major type definitions for actions, errors, ports, reactions, registries, and schemas.\n * Also defines common environment and log level types/constants for configuration and logging.\n *\n * @remarks\n * Import from this module to access all core framework types in one place.\n */\nexport type * from \"./action.js\";\nexport * from \"./errors.js\";\nexport type * from \"./ports.js\";\nexport type * from \"./reaction.js\";\nexport type * from \"./registry.js\";\nexport * from \"./schemas.js\";\n\n/**\n * Supported runtime environments for the framework.\n * - `development`: Local development\n * - `test`: Automated testing\n * - `staging`: Pre-production\n * - `production`: Live/production\n */\nexport const Environments = [\n  \"development\",\n  \"test\",\n  \"staging\",\n  \"production\",\n] as const;\n\n/**\n * Type representing a valid environment string.\n */\nexport type Environment = (typeof Environments)[number];\n\n/**\n * Supported log levels for framework logging.\n * - `fatal`, `error`, `warn`, `info`, `debug`, `trace`\n */\nexport const LogLevels = [\n  \"fatal\",\n  \"error\",\n  \"warn\",\n  \"info\",\n  \"debug\",\n  \"trace\",\n] as const;\n\n/**\n * Type representing a valid log level string.\n */\nexport type LogLevel = (typeof LogLevels)[number];\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -123,8 +123,10 @@ var ConsoleLogger = class _ConsoleLogger {
     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,
@@ -249,21 +251,27 @@ var InMemoryCache = class {
   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;
   }
@@ -296,13 +304,6 @@ var InvariantError = class extends Error {
     this.name = Errors.InvariantError;
   }
 };
-var StreamClosedError = class extends Error {
-  constructor(stream) {
-    super(`Stream "${stream}" is closed (tombstoned)`);
-    this.stream = stream;
-    this.name = Errors.StreamClosedError;
-  }
-};
 var ConcurrencyError = class extends Error {
   constructor(stream, lastVersion, events, expectedVersion) {
     super(
@@ -317,6 +318,13 @@ var ConcurrencyError = class extends Error {
     this.name = Errors.ConcurrencyError;
   }
 };
+var StreamClosedError = class extends Error {
+  constructor(stream) {
+    super(`Stream "${stream}" is closed (tombstoned)`);
+    this.stream = stream;
+    this.name = Errors.StreamClosedError;
+  }
+};
 
 // src/utils.ts
 var import_zod3 = require("zod");
@@ -906,7 +914,7 @@ var InMemoryStore = class {
 var ExitCodes = ["ERROR", "EXIT"];
 var adapters = /* @__PURE__ */ new Map();
 function port(injector) {
-  return function(adapter) {
+  return (adapter) => {
     if (!adapters.has(injector.name)) {
       const injected = injector(adapter);
       adapters.set(injector.name, injected);
@@ -972,7 +980,7 @@ process.once("unhandledRejection", async (arg) => {
 });
 
 // src/act.ts
-var import_events = __toESM(require("events"), 1);
+var import_node_events = __toESM(require("events"), 1);
 
 // src/internal/build-classify.ts
 function classifyRegistry(registry, states) {
@@ -1006,7 +1014,7 @@ function classifyRegistry(registry, states) {
 }
 
 // src/internal/close-cycle.ts
-var import_crypto = require("crypto");
+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()];
@@ -1018,7 +1026,7 @@ async function runCloseCycle(targets, deps) {
     skipped
   );
   if (!safe.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
-  const correlation = (0, import_crypto.randomUUID)();
+  const correlation = (0, import_node_crypto.randomUUID)();
   const { guarded, guardEvents } = await guardWithTombstones(
     safe,
     streamInfo,
@@ -1275,7 +1283,7 @@ var CorrelateCycle = class {
 };
 
 // src/internal/drain-cycle.ts
-var import_crypto2 = require("crypto");
+var import_node_crypto2 = require("crypto");
 
 // src/internal/drain-ratio.ts
 var RATIO_MIN = 0.2;
@@ -1297,7 +1305,7 @@ function computeLagLeadRatio(handled, lagging, leading) {
 
 // src/internal/drain-cycle.ts
 async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch, lagging, leading, eventLimit, leaseMillis) {
-  const leased = await ops.claim(lagging, leading, (0, import_crypto2.randomUUID)(), leaseMillis);
+  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 fetchMap = /* @__PURE__ */ new Map();
@@ -1698,8 +1706,8 @@ var block = (leases) => store().block(leases);
 var subscribe = (streams) => store().subscribe(streams);
 
 // src/internal/event-sourcing.ts
+var import_node_crypto3 = require("crypto");
 var import_act_patch = require("@rotorsoft/act-patch");
-var import_crypto3 = require("crypto");
 async function snap(snapshot) {
   try {
     const { id, stream, name, meta, version } = snapshot.event;
@@ -1759,7 +1767,7 @@ async function load(me, stream, callback, asOf) {
           `Skipping unknown event "${String(e.name)}" on stream "${stream}" (id=${e.id}) \u2014 no reducer in state "${me.name}"`
         );
       }
-      callback && callback({
+      callback?.({
         event,
         state: state2,
         version,
@@ -1775,6 +1783,15 @@ async function load(me, stream, callback, asOf) {
       ...cached ? { after: cached.event_id } : { with_snaps: true, ...asOf }
     }
   );
+  if (replayed > 0 && !timeTravel && event) {
+    await cache().set(stream, {
+      state: state2,
+      version,
+      event_id: event.id,
+      patches,
+      snaps
+    });
+  }
   return { event, state: state2, version, patches, snaps, cache_hit, replayed };
 }
 async function action(me, action2, target, payload, reactingTo, skipValidation = false) {
@@ -1809,7 +1826,7 @@ 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_crypto3.randomUUID)(),
+    correlation: reactingTo?.meta.correlation || (0, import_node_crypto3.randomUUID)(),
     causation: {
       action: {
         name: action2,
@@ -1859,7 +1876,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     };
   });
   const last = snapshots.at(-1);
-  const snapped = me.snap && me.snap(last);
+  const snapped = me.snap?.(last);
   cache().set(stream, {
     state: last.state,
     version: last.event.version,
@@ -2040,6 +2057,17 @@ function buildDrain(logger) {
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
 var Act = class {
+  /**
+   * Create a new Act orchestrator. Prefer the {@link act} builder over
+   * direct construction — `act()...build()` wires the registry, merges
+   * partial states, and collects batch handlers from registered slices
+   * and projections in one pass.
+   *
+   * @param registry  Schemas for every event and action across registered states
+   * @param _states   Merged map of state name → state definition
+   * @param batchHandlers Static-target projection batch handlers (target → handler)
+   * @param options   Tuning knobs — see {@link ActOptions}
+   */
   constructor(registry, _states = /* @__PURE__ */ new Map(), batchHandlers = /* @__PURE__ */ new Map(), options = {}) {
     this.registry = registry;
     this._states = _states;
@@ -2096,7 +2124,7 @@ var Act = class {
       return Promise.resolve();
     });
   }
-  _emitter = new import_events.default();
+  _emitter = new import_node_events.default();
   /** Event names with at least one registered reaction (computed at build time) */
   _reactive_events;
   /** Drain pipeline driver: armed flag, concurrency lock, adaptive ratio. */
@@ -2127,12 +2155,6 @@ var Act = class {
     this._emitter.off(event, listener);
     return this;
   }
-  /**
-   * Create a new Act orchestrator.
-   *
-   * @param registry The registry of state, event, and action schemas
-   * @param states Map of state names to their (potentially merged) state definitions
-   */
   /** Batch handlers for static-target projections (target → handler) */
   _batch_handlers;
   /** Event-sourcing handlers, optionally wrapped with trace decorators */
@@ -2278,14 +2300,9 @@ var Act = class {
    *
    * For small result sets, consider using {@link query_array} instead.
    *
-   * @param query - The query filter
-   * @param query.stream - Filter by stream ID
-   * @param query.name - Filter by event name
-   * @param query.after - Filter events after this event ID
-   * @param query.before - Filter events before this event ID
-   * @param query.created_after - Filter events after this timestamp
-   * @param query.created_before - Filter events before this timestamp
-   * @param query.limit - Maximum number of events to return
+   * @param query - Filter criteria — see {@link Query} for available fields
+   *   (`stream`, `name`, `after`, `before`, `created_after`, `created_before`,
+   *   `limit`, `with_snaps`, `stream_exact`)
    * @param callback - Optional callback invoked for each matching event
    * @returns Object with first event, last event, and total count
    *
@@ -2321,11 +2338,12 @@ var Act = class {
    * @see {@link query_array} for loading events into memory
    */
   async query(query, callback) {
-    let first = void 0, last = void 0;
+    let first;
+    let last;
     const count = await store().query((e) => {
-      !first && (first = e);
+      if (!first) first = e;
       last = e;
-      callback && callback(e);
+      callback?.(e);
     }, query);
     return { first, last, count };
   }
@@ -2376,10 +2394,8 @@ var Act = class {
    * Call `correlate()` before `drain()` to discover target streams. For a higher-level
    * API that handles debouncing, correlation, and signaling automatically, use {@link settle}.
    *
-   * @param options - Drain configuration options
-   * @param options.streamLimit - Maximum number of streams to process per cycle (default: 10)
-   * @param options.eventLimit - Maximum events to fetch per stream (default: 10)
-   * @param options.leaseMillis - Lease duration in milliseconds (default: 10000)
+   * @param options - Drain configuration — see {@link DrainOptions} for fields
+   *   (`streamLimit`, `eventLimit`, `leaseMillis`).
    * @returns Drain statistics with fetched, leased, acked, and blocked counts
    *
    * @example In tests and scripts
@@ -2414,8 +2430,8 @@ var Act = class {
    * the next drain cycle.
    *
    * @param query - Query filter to scan for new correlations
-   * @param query.after - Start scanning after this event ID (default: -1)
-   * @param query.limit - Maximum events to scan (default: 10)
+   * @param query - Scan filter — see {@link Query} for fields (typically
+   *   `{ after: <event-id>, limit: <count> }`)
    * @returns Object with newly leased streams and last scanned event ID
    *
    * @example Manual correlation
@@ -2462,9 +2478,8 @@ var Act = class {
    *
    * **Note:** Only one correlation worker can run at a time per Act instance.
    *
-   * @param query - Query filter for correlation scans
-   * @param query.after - Initial starting point (default: -1, start from beginning)
-   * @param query.limit - Events to scan per cycle (default: 100)
+   * @param query - Query filter for correlation scans — see {@link Query}
+   *   (typically `{ after: -1, limit: 100 }`)
    * @param frequency - Correlation frequency in milliseconds (default: 10000)
    * @param callback - Optional callback invoked with newly discovered streams
    * @returns `true` if worker started, `false` if already running
@@ -2631,14 +2646,11 @@ var Act = class {
    * fully catches up paginated streams (e.g. after `reset()` on a long
    * projection) without forcing callers to loop.
    *
-   * @param options - Settle configuration options
-   * @param options.debounceMs - Debounce window in milliseconds (default: 10)
-   * @param options.correlate - Query filter for correlation scans (default: `{ after: -1, limit: 100 }`)
-   * @param options.maxPasses - Cap on correlate→drain loops (default: `Infinity`).
-   *   Early-exit on no-progress means the cap only matters in pathological cases.
-   * @param options.streamLimit - Maximum streams per drain cycle (default: 10)
-   * @param options.eventLimit - Maximum events per stream (default: 10)
-   * @param options.leaseMillis - Lease duration in milliseconds (default: 10000)
+   * @param options - Settle configuration — see {@link SettleOptions} for fields:
+   *   `debounceMs` (default 10), `correlate` (default `{ after: -1, limit: 100 }`),
+   *   `maxPasses` (default `Infinity` — kill-switch for runaway loops),
+   *   `streamLimit` (default 10), `eventLimit` (default 10),
+   *   `leaseMillis` (default 10000).
    *
    * @example API mutations
    * ```typescript
@@ -2901,7 +2913,8 @@ function action_builder(state2) {
         throw new Error(`Duplicate action "${action2}"`);
       internal.actions[action2] = schema;
       function given(rules) {
-        (internal.given ??= {})[action2] = rules;
+        internal.given ??= {};
+        internal.given[action2] = rules;
         return { emit };
       }
       function emit(handler) {