@rotorsoft/act 1.10.1 → 1.10.2

package/dist/{chunk-BY5JPOZR.js.map → chunk-NGVWJXEF.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/types/errors.ts","../src/types/schemas.ts","../src/internal/sensitive.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  NonRetryableError: \"ERR_NON_RETRYABLE\",\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  /** 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  constructor(target: string, payload: any, details: any) {\n    super(`Invalid ${target} payload`);\n    this.name = Errors.ValidationError;\n    this.target = target;\n    this.payload = payload;\n    this.details = details;\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  /** 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  constructor(\n    action: TKey,\n    payload: Readonly<TActions[TKey]>,\n    target: Target<TActor>,\n    snapshot: Snapshot<TState, TEvents>,\n    description: string\n  ) {\n    super(`${action as string} failed invariant: ${description}`);\n    this.name = Errors.InvariantError;\n    this.action = action;\n    this.payload = payload;\n    this.target = target;\n    this.snapshot = snapshot;\n    this.description = description;\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  /** 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  constructor(\n    stream: string,\n    lastVersion: number,\n    events: Message<Schemas, keyof Schemas>[],\n    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    this.stream = stream;\n    this.lastVersion = lastVersion;\n    this.events = events;\n    this.expectedVersion = expectedVersion;\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  /** The stream that is closed */\n  public readonly stream: string;\n\n  constructor(stream: string) {\n    super(`Stream \"${stream}\" is closed (tombstoned)`);\n    this.name = Errors.StreamClosedError;\n    this.stream = stream;\n  }\n}\n\n/**\n * Thrown by a reaction handler to signal that the failure is permanent\n * and the drain pipeline should block the stream immediately, without\n * consuming the rest of the `maxRetries` budget.\n *\n * The drain finalizer detects `instanceof NonRetryableError` and forces\n * `block = options.blockOnError` regardless of `lease.retry`. When\n * `blockOnError` is `false`, behavior is unchanged (drain keeps retrying\n * forever) — the class never overrides the operator's explicit \"never\n * block\" choice.\n *\n * Use this for failures the handler *knows* won't get better on retry:\n * a 4xx from a webhook, a `ZodError` on malformed input, a \"user\n * deleted\" 404 from a downstream API. Use regular `Error` (or a\n * subclass) for transient failures so the existing retry-with-backoff\n * loop applies.\n *\n * @example Wrapping a permanent downstream error\n * ```typescript\n * import { NonRetryableError } from \"@rotorsoft/act\";\n *\n * .on(\"OrderConfirmed\")\n *   .do(async (event) => {\n *     const res = await fetch(url, ...);\n *     if (res.status >= 400 && res.status < 500) {\n *       throw new NonRetryableError(\n *         `webhook ${url} responded ${res.status}`,\n *         { cause: await res.text() }\n *       );\n *     }\n *     if (!res.ok) throw new Error(`webhook ${url} responded ${res.status}`);\n *   })\n * ```\n *\n * @example Marking validation failures as non-retryable\n * ```typescript\n * .on(\"PaymentReceived\")\n *   .do(async (event) => {\n *     const parsed = Schema.safeParse(event.data);\n *     if (!parsed.success) {\n *       throw new NonRetryableError(\"payment payload failed validation\", {\n *         cause: parsed.error,\n *       });\n *     }\n *     // ... handle parsed payload\n *   })\n * ```\n */\nexport class NonRetryableError extends Error {\n  /** The original failure, if any. Mirrors the standard `Error.cause` shape. */\n  public override readonly cause?: unknown;\n\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message);\n    this.name = Errors.NonRetryableError;\n    this.cause = options?.cause;\n  }\n}\n","import { type ZodObject, type ZodRawShape, z } from \"zod\";\n// Deep-path import (vs `../internal/index.js`) is deliberate — `_registry` is\n// a side-effect-free leaf, and going through the internal barrel would pull\n// tracing.ts → config.ts in at type-schema load time and crash on TDZ when a\n// test imports a public schema before config is initialized.\nimport { _registry } from \"../internal/sensitive.js\";\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 * Sentinel placed in `event.data[field]` when the caller isn't authorized to\n * see the sensitive field — either `.discloses(predicate)` returned `false`,\n * or no predicate was declared (framework default-deny). Recoverable: a\n * properly-authorized read returns the plaintext.\n *\n * Part of the sensitive-data foundation (#855 / epic #566).\n */\nexport { REDACTED, SHREDDED } from \"../internal/sensitive.js\";\n\n/**\n * Mark a Zod schema as sensitive. Returns the same schema instance — the\n * marker is registered out-of-band so the static type is preserved and the\n * call site reads as a pure annotation.\n *\n * Idempotent: re-wrapping an already-sensitive schema is a no-op.\n *\n * The marker is what the orchestrator inspects to split event payloads into\n * `data` + `pii` on commit, gate reads via `.discloses`, and strip handler\n * payloads. Part of the sensitive-data foundation (#855 / epic #566).\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { state, sensitive } from \"@rotorsoft/act\";\n *\n * const UserRegistered = z.object({\n *   email: sensitive(z.string()),\n *   name: sensitive(z.string()),\n *   plan: z.enum([\"free\", \"pro\"]),  // not sensitive — stays in events.data\n * });\n * ```\n *\n * @param schema - The Zod schema to mark sensitive.\n * @returns The same schema instance, unmodified at the type level.\n */\nexport function sensitive<T extends z.ZodType>(schema: T): T {\n  _registry.add(schema, { sensitive: true });\n  return schema;\n}\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 * @module sensitive\n * @category Internal\n *\n * Internal mechanics for the sensitive-data foundation (#855 / epic #566).\n * The public surface (`sensitive(zodType)`) lives at `libs/act/src/sensitive.ts`\n * and re-exports `REDACTED` / `SHREDDED` from here; this module holds the\n * registry plus the helpers the orchestrator calls during commit, load, and\n * handler dispatch.\n *\n * - `_registry` — process-global `z.registry<{ sensitive: true }>()`. Public\n *   `sensitive()` adds to it; the helpers in this module read it.\n * - `pii_fields(schema)` — walk a Zod schema's top-level shape, return the\n *   keys marked via `sensitive(...)`.\n * - `pii_merge(event, fields)` — produce the reducer view (pii merged\n *   into data; `[SHREDDED]` if pii column is null).\n * - `pii_gate(event, fields, predicate, actor)` — produce the external\n *   view: plaintext when authorized, `[REDACTED]` when not, `[SHREDDED]`\n *   when the underlying pii column is null.\n * - `pii_strip(event, fields)` — remove sensitive keys entirely\n *   before invoking projection / reaction handlers.\n *\n * @internal\n */\n\nimport { z } from \"zod\";\nimport type { Actor, Committed, Schemas } from \"../types/index.js\";\n\n/**\n * Sentinel placed in `event.data[field]` when the caller isn't authorized to\n * see the sensitive field — either `.discloses(predicate)` returned `false`,\n * or no predicate was declared (framework default-deny). Recoverable: a\n * properly-authorized read returns the plaintext.\n *\n * Re-exported from `libs/act/src/sensitive.ts` as part of the public surface.\n */\nexport const REDACTED = \"[REDACTED]\" as const;\n\n/**\n * Sentinel placed in `event.data[field]` when the underlying PII payload has\n * been wiped via `Store.forget_pii(stream)` — the row's pii column is `NULL`\n * and the original plaintext is gone forever. Irrecoverable.\n *\n * Re-exported from `libs/act/src/sensitive.ts` as part of the public surface.\n */\nexport const SHREDDED = \"[SHREDDED]\" as const;\n\n/**\n * Process-global registry holding every Zod schema marked sensitive. Backed\n * by a `WeakMap`, so wrapper-created instances (`.optional()`, `.nullable()`,\n * `.default()`) that chain off a marked schema produce *new* schema instances\n * the registry doesn't track; the field walker handles those via unwrap.\n *\n * Exported so the public `sensitive(zodType)` wrapper can call `_registry.add`.\n * Underscore prefix marks \"framework-private, don't touch from user code.\"\n *\n * @internal\n */\nexport const _registry = z.registry<{ sensitive: true }>();\n\n/**\n * True when the given schema was marked via `sensitive(...)`.\n *\n * Walks through Zod wrapper layers (`.optional()`, `.nullable()`,\n * `.default()`, `.readonly()`) by following `_def.innerType` until it reaches\n * a non-wrapper schema, then checks the registry. Wrappers create new schema\n * instances; the marker lives on the *inner* schema the user wrapped, so we\n * test that one.\n *\n * @internal\n */\nfunction is_pii(schema: z.ZodType): boolean {\n  let cur: z.ZodType = schema;\n  while (true) {\n    if (_registry.has(cur)) return true;\n    const inner = (cur as { _def?: { innerType?: z.ZodType } })._def?.innerType;\n    if (!inner || inner === cur) return false;\n    cur = inner;\n  }\n}\n\n/**\n * Derive the list of sensitive field names from an event's Zod schema.\n *\n * Walks the top-level shape of a `z.object({...})` and returns the keys whose\n * schema (after unwrapping optional/nullable/default wrappers) was marked via\n * `sensitive(...)`. Returns an empty array for non-object schemas or events\n * with no sensitive fields — the common-case zero-cost path.\n *\n * Only the top-level shape is walked. Sensitive fields nested inside a\n * `z.object` declared inside the event payload would require recursive\n * descent; that's deferred until a real callsite needs it.\n *\n * @internal — consumed by the registry's `sensitive_fields(event_name)` lookup.\n */\nexport function pii_fields(schema: z.ZodType): readonly string[] {\n  const shape = (schema as { shape?: Record<string, z.ZodType> }).shape;\n  if (!shape || typeof shape !== \"object\") return [];\n  const fields: string[] = [];\n  for (const key of Object.keys(shape)) {\n    if (is_pii(shape[key])) fields.push(key);\n  }\n  return fields;\n}\n\n/**\n * Split an emitted event's `data` into `data` (non-sensitive) + `pii`\n * (sensitive) using the field list precomputed at build time. Used by the\n * State's `_pii_split` decorator just before `Store.commit`.\n *\n * Single forward pass over `Object.keys(validated)` — same shape as the\n * spread-and-delete-free implementation in slice 3, just hoisted out of the\n * orchestrator hot path so it's only invoked when the State actually has a\n * sensitive event.\n *\n * @internal\n */\nexport function pii_split(\n  emitted: { name: unknown; data: unknown },\n  fields: readonly string[]\n): { name: unknown; data: unknown; pii: Record<string, unknown> } {\n  const rec = emitted.data as Record<string, unknown>;\n  const clean: Record<string, unknown> = {};\n  const pii: Record<string, unknown> = {};\n  for (const k of Object.keys(rec)) {\n    if (fields.includes(k)) pii[k] = rec[k];\n    else clean[k] = rec[k];\n  }\n  return { name: emitted.name, data: clean, pii };\n}\n\n/**\n * Build the **reducer view** of a committed event — sensitive fields merged\n * back into `data` so per-state reducers always see plaintext.\n *\n * - Event with no `pii` payload AND no schema-declared sensitive fields →\n *   return the event unchanged (zero-cost path).\n * - Event with a `pii` payload → merge into `data` (plaintext for the reducer).\n * - Event whose schema *declares* sensitive fields but `pii` is null/undefined\n *   (post-`forget_pii`) → substitute {@link SHREDDED} for each declared field.\n *\n * Used inside `load()` before invoking the reducer chain. Reducer-visible PII\n * is by design — the reducer is the source of truth for derived state. The\n * external view returned to callers is separately gated by {@link pii_gate}.\n *\n * @internal\n */\nexport function pii_merge<\n  TEvents extends Schemas,\n  TKey extends keyof TEvents & string,\n>(\n  event: Committed<TEvents, TKey>,\n  fields: readonly string[]\n): Committed<TEvents, TKey> {\n  // Contract: `fields` is non-empty. Callers (the State's `_pii_merge`\n  // decorator) filter on `fields_by_event.get(name)` before invocation, so the\n  // empty-fields short-circuit lives at the caller, not here.\n  const data = event.data as Record<string, unknown>;\n  const pii = event.pii;\n  if (pii != null) {\n    return {\n      ...event,\n      data: { ...data, ...pii } as Committed<TEvents, TKey>[\"data\"],\n    };\n  }\n  // Schema declared sensitive fields but the pii payload is gone — shredded.\n  const shredded: Record<string, unknown> = { ...data };\n  for (const f of fields) shredded[f] = SHREDDED;\n  return {\n    ...event,\n    data: shredded as Committed<TEvents, TKey>[\"data\"],\n  };\n}\n\n/**\n * Build the **external view** of a committed event — the form returned by\n * `load()`, `query()`, `query_array()`, and the snapshot in `do()`'s reply.\n *\n * - Event with no schema-declared sensitive fields → returned unchanged\n *   (zero-cost path).\n * - Event whose `pii` payload is null/undefined AND schema declares sensitive\n *   fields → substitute {@link SHREDDED} for each declared field. Irrecoverable,\n *   so no predicate check.\n * - Event with a `pii` payload, predicate returns `true` → merge `pii` into\n *   `data` (plaintext).\n * - Event with a `pii` payload, predicate returns `false` OR no predicate\n *   declared (framework default-deny) → substitute {@link REDACTED} for each\n *   declared field.\n *\n * @internal\n */\nexport function pii_gate<\n  TEvents extends Schemas,\n  TKey extends keyof TEvents & string,\n>(\n  event: Committed<TEvents, TKey>,\n  fields: readonly string[],\n  predicate: ((event: any, actor: Actor) => boolean) | null,\n  actor: Actor | undefined\n): Committed<TEvents, TKey> {\n  // Contract: `fields` is non-empty. The State's `_pii_gate` decorator\n  // filters on `fields_by_event.get(name)` before invocation.\n  const data = event.data as Record<string, unknown>;\n  if (event.pii == null) {\n    const shredded: Record<string, unknown> = { ...data };\n    for (const f of fields) shredded[f] = SHREDDED;\n    return {\n      ...event,\n      data: shredded as Committed<TEvents, TKey>[\"data\"],\n    };\n  }\n  // Plaintext path requires both an actor AND a predicate that allows. Missing\n  // either → default-deny → REDACTED.\n  const allowed = !!actor && !!predicate && predicate(event, actor);\n  if (allowed) {\n    return {\n      ...event,\n      data: {\n        ...data,\n        ...(event.pii as Record<string, unknown>),\n      } as Committed<TEvents, TKey>[\"data\"],\n    };\n  }\n  const redacted: Record<string, unknown> = { ...data };\n  for (const f of fields) redacted[f] = REDACTED;\n  return {\n    ...event,\n    data: redacted as Committed<TEvents, TKey>[\"data\"],\n  };\n}\n\n/**\n * Build the **handler view** — sensitive keys removed entirely from `data`\n * and the `pii` field dropped from the event. Used before invoking projection\n * handlers and reaction handlers, which never see PII by framework rule.\n *\n * Different from {@link pii_gate} (which substitutes {@link REDACTED} or\n * {@link SHREDDED}) — projection tables and reaction sinks shouldn't even\n * structurally observe the keys, so a handler that mistakenly writes\n * `event.data.email` into a column would get `undefined`, not a sentinel\n * string that looks like real data. The strictness is deliberate.\n *\n * Reactions that genuinely need PII (e.g. a welcome-email reaction reading\n * `email`) opt back in by explicitly calling `app.load(stream, { actor:\n * system_actor })` inside the handler — pulling PII through the gate at the\n * call site makes the security-relevant path visible in code review.\n *\n * @internal\n */\nexport function pii_strip<\n  TEvents extends Schemas,\n  TKey extends keyof TEvents & string,\n>(\n  event: Committed<TEvents, TKey>,\n  fields: readonly string[]\n): Committed<TEvents, TKey> {\n  // Contract: `fields` is non-empty. `build_handle` / `build_handle_batch`\n  // filter on `fields.length > 0` before invocation.\n  const data = event.data as Record<string, unknown>;\n  const stripped: Record<string, unknown> = {};\n  for (const k of Object.keys(data)) {\n    if (!fields.includes(k)) stripped[k] = data[k];\n  }\n  const { pii: _drop_pii, ...rest } = event as Committed<TEvents, TKey> & {\n    pii?: unknown;\n  };\n  return {\n    ...rest,\n    data: stripped as Committed<TEvents, TKey>[\"data\"],\n  } as Committed<TEvents, TKey>;\n}\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 type * from \"./audit.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":["z","z"]}
+{"version":3,"sources":["../src/types/errors.ts","../src/types/schemas.ts","../src/internal/sensitive.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  NonRetryableError: \"ERR_NON_RETRYABLE\",\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  /** 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  constructor(target: string, payload: any, details: any) {\n    super(`Invalid ${target} payload`);\n    this.name = Errors.ValidationError;\n    this.target = target;\n    this.payload = payload;\n    this.details = details;\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  /** 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  constructor(\n    action: TKey,\n    payload: Readonly<TActions[TKey]>,\n    target: Target<TActor>,\n    snapshot: Snapshot<TState, TEvents>,\n    description: string\n  ) {\n    super(`${action as string} failed invariant: ${description}`);\n    this.name = Errors.InvariantError;\n    this.action = action;\n    this.payload = payload;\n    this.target = target;\n    this.snapshot = snapshot;\n    this.description = description;\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  /** 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  constructor(\n    stream: string,\n    lastVersion: number,\n    events: Message<Schemas, keyof Schemas>[],\n    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    this.stream = stream;\n    this.lastVersion = lastVersion;\n    this.events = events;\n    this.expectedVersion = expectedVersion;\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  /** The stream that is closed */\n  public readonly stream: string;\n\n  constructor(stream: string) {\n    super(`Stream \"${stream}\" is closed (tombstoned)`);\n    this.name = Errors.StreamClosedError;\n    this.stream = stream;\n  }\n}\n\n/**\n * Thrown by a reaction handler to signal that the failure is permanent\n * and the drain pipeline should block the stream immediately, without\n * consuming the rest of the `maxRetries` budget.\n *\n * The drain finalizer detects `instanceof NonRetryableError` and forces\n * `block = options.blockOnError` regardless of `lease.retry`. When\n * `blockOnError` is `false`, behavior is unchanged (drain keeps retrying\n * forever) — the class never overrides the operator's explicit \"never\n * block\" choice.\n *\n * Use this for failures the handler *knows* won't get better on retry:\n * a 4xx from a webhook, a `ZodError` on malformed input, a \"user\n * deleted\" 404 from a downstream API. Use regular `Error` (or a\n * subclass) for transient failures so the existing retry-with-backoff\n * loop applies.\n *\n * @example Wrapping a permanent downstream error\n * ```typescript\n * import { NonRetryableError } from \"@rotorsoft/act\";\n *\n * .on(\"OrderConfirmed\")\n *   .do(async (event) => {\n *     const res = await fetch(url, ...);\n *     if (res.status >= 400 && res.status < 500) {\n *       throw new NonRetryableError(\n *         `webhook ${url} responded ${res.status}`,\n *         { cause: await res.text() }\n *       );\n *     }\n *     if (!res.ok) throw new Error(`webhook ${url} responded ${res.status}`);\n *   })\n * ```\n *\n * @example Marking validation failures as non-retryable\n * ```typescript\n * .on(\"PaymentReceived\")\n *   .do(async (event) => {\n *     const parsed = Schema.safeParse(event.data);\n *     if (!parsed.success) {\n *       throw new NonRetryableError(\"payment payload failed validation\", {\n *         cause: parsed.error,\n *       });\n *     }\n *     // ... handle parsed payload\n *   })\n * ```\n */\nexport class NonRetryableError extends Error {\n  /** The original failure, if any. Mirrors the standard `Error.cause` shape. */\n  public override readonly cause?: unknown;\n\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message);\n    this.name = Errors.NonRetryableError;\n    this.cause = options?.cause;\n  }\n}\n","import { type ZodObject, type ZodRawShape, z } from \"zod\";\n// Deep-path import (vs `../internal/index.js`) is deliberate — `_registry` is\n// a side-effect-free leaf, and going through the internal barrel would pull\n// tracing.ts → config.ts in at type-schema load time and crash on TDZ when a\n// test imports a public schema before config is initialized.\nimport { _registry } from \"../internal/sensitive.js\";\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 * Sentinel placed in `event.data[field]` when the caller isn't authorized to\n * see the sensitive field — either `.discloses(predicate)` returned `false`,\n * or no predicate was declared (framework default-deny). Recoverable: a\n * properly-authorized read returns the plaintext.\n *\n * Part of the sensitive-data foundation (#855 / epic #566).\n */\nexport { REDACTED, SHREDDED } from \"../internal/sensitive.js\";\n\n/**\n * Mark a Zod schema as sensitive. Returns the same schema instance — the\n * marker is registered out-of-band so the static type is preserved and the\n * call site reads as a pure annotation.\n *\n * Idempotent: re-wrapping an already-sensitive schema is a no-op.\n *\n * The marker is what the orchestrator inspects to split event payloads into\n * `data` + `pii` on commit, gate reads via `.discloses`, and strip handler\n * payloads. Part of the sensitive-data foundation (#855 / epic #566).\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { state, sensitive } from \"@rotorsoft/act\";\n *\n * const UserRegistered = z.object({\n *   email: sensitive(z.string()),\n *   name: sensitive(z.string()),\n *   plan: z.enum([\"free\", \"pro\"]),  // not sensitive — stays in events.data\n * });\n * ```\n *\n * @param schema - The Zod schema to mark sensitive.\n * @returns The same schema instance, unmodified at the type level.\n */\nexport function sensitive<T extends z.ZodType>(schema: T): T {\n  _registry.add(schema, { sensitive: true });\n  return schema;\n}\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 * @module sensitive\n * @category Internal\n *\n * Internal mechanics for the sensitive-data foundation (#855 / epic #566).\n * The public surface (`sensitive(zodType)`) lives at `libs/act/src/sensitive.ts`\n * and re-exports `REDACTED` / `SHREDDED` from here; this module holds the\n * registry plus the helpers the orchestrator calls during commit, load, and\n * handler dispatch.\n *\n * - `_registry` — process-global `z.registry<{ sensitive: true }>()`. Public\n *   `sensitive()` adds to it; the helpers in this module read it.\n * - `pii_fields(schema)` — walk a Zod schema's top-level shape, return the\n *   keys marked via `sensitive(...)`.\n * - `pii_merge(event, fields)` — produce the reducer view (pii merged\n *   into data; `[SHREDDED]` if pii column is null).\n * - `pii_gate(event, fields, predicate, actor)` — produce the external\n *   view: plaintext when authorized, `[REDACTED]` when not, `[SHREDDED]`\n *   when the underlying pii column is null.\n * - `pii_strip(event, fields)` — remove sensitive keys entirely\n *   before invoking projection / reaction handlers.\n *\n * @internal\n */\n\nimport { z } from \"zod\";\nimport type { Actor, Committed, Schemas } from \"../types/index.js\";\n\n/**\n * Sentinel placed in `event.data[field]` when the caller isn't authorized to\n * see the sensitive field — either `.discloses(predicate)` returned `false`,\n * or no predicate was declared (framework default-deny). Recoverable: a\n * properly-authorized read returns the plaintext.\n *\n * Re-exported from `libs/act/src/sensitive.ts` as part of the public surface.\n */\nexport const REDACTED = \"[REDACTED]\" as const;\n\n/**\n * Sentinel placed in `event.data[field]` when the underlying PII payload has\n * been wiped via `Store.forget_pii(stream)` — the row's pii column is `NULL`\n * and the original plaintext is gone forever. Irrecoverable.\n *\n * Re-exported from `libs/act/src/sensitive.ts` as part of the public surface.\n */\nexport const SHREDDED = \"[SHREDDED]\" as const;\n\n/**\n * Process-global registry holding every Zod schema marked sensitive. Backed\n * by a `WeakMap`, so wrapper-created instances (`.optional()`, `.nullable()`,\n * `.default()`) that chain off a marked schema produce *new* schema instances\n * the registry doesn't track; the field walker handles those via unwrap.\n *\n * Exported so the public `sensitive(zodType)` wrapper can call `_registry.add`.\n * Underscore prefix marks \"framework-private, don't touch from user code.\"\n *\n * @internal\n */\nexport const _registry = z.registry<{ sensitive: true }>();\n\n/**\n * True when the given schema was marked via `sensitive(...)`.\n *\n * Walks through Zod wrapper layers (`.optional()`, `.nullable()`,\n * `.default()`, `.readonly()`) by following `_def.innerType` until it reaches\n * a non-wrapper schema, then checks the registry. Wrappers create new schema\n * instances; the marker lives on the *inner* schema the user wrapped, so we\n * test that one.\n *\n * @internal\n */\nfunction is_pii(schema: z.ZodType): boolean {\n  let cur: z.ZodType = schema;\n  while (true) {\n    if (_registry.has(cur)) return true;\n    const inner = (cur as { _def?: { innerType?: z.ZodType } })._def?.innerType;\n    if (!inner || inner === cur) return false;\n    cur = inner;\n  }\n}\n\n/**\n * Derive the list of sensitive field names from an event's Zod schema.\n *\n * Walks the top-level shape of a `z.object({...})` and returns the keys whose\n * schema (after unwrapping optional/nullable/default wrappers) was marked via\n * `sensitive(...)`. Returns an empty array for non-object schemas or events\n * with no sensitive fields — the common-case zero-cost path.\n *\n * Only the top-level shape is walked. Sensitive fields nested inside a\n * `z.object` declared inside the event payload would require recursive\n * descent; that's deferred until a real callsite needs it.\n *\n * @internal — consumed by the registry's `sensitive_fields(event_name)` lookup.\n */\nexport function pii_fields(schema: z.ZodType): readonly string[] {\n  const shape = (schema as { shape?: Record<string, z.ZodType> }).shape;\n  if (!shape || typeof shape !== \"object\") return [];\n  const fields: string[] = [];\n  for (const key of Object.keys(shape)) {\n    if (is_pii(shape[key])) fields.push(key);\n  }\n  return fields;\n}\n\n/**\n * Split an emitted event's `data` into `data` (non-sensitive) + `pii`\n * (sensitive) using the field list precomputed at build time. Used by the\n * State's `_pii_split` decorator just before `Store.commit`.\n *\n * Single forward pass over `Object.keys(validated)` — same shape as the\n * spread-and-delete-free implementation in slice 3, just hoisted out of the\n * orchestrator hot path so it's only invoked when the State actually has a\n * sensitive event.\n *\n * @internal\n */\nexport function pii_split<TName, TData extends Record<string, unknown>>(\n  emitted: { name: TName; data: TData },\n  fields: readonly string[]\n): { name: TName; data: TData; pii: Record<string, unknown> } {\n  const data = { ...emitted.data };\n  const pii: Record<string, unknown> = {};\n  for (const f of fields) {\n    if (f in data) {\n      pii[f] = data[f];\n      delete data[f];\n    }\n  }\n  return { name: emitted.name, data, pii };\n}\n\n/**\n * Build the **external view** of a committed event — the form returned by\n * `load()`, `query()`, `query_array()`, and the snapshot in `do()`'s reply.\n *\n * - Event with no schema-declared sensitive fields → returned unchanged\n *   (zero-cost path).\n * - Event whose `pii` payload is null/undefined AND schema declares sensitive\n *   fields → substitute {@link SHREDDED} for each declared field. Irrecoverable,\n *   so no predicate check.\n * - Event with a `pii` payload, predicate returns `true` → merge `pii` into\n *   `data` (plaintext).\n * - Event with a `pii` payload, predicate returns `false` OR no predicate\n *   declared (framework default-deny) → substitute {@link REDACTED} for each\n *   declared field.\n *\n * @internal\n */\nexport function pii_gate<TEvents extends Schemas, TKey extends keyof TEvents>(\n  event: Committed<TEvents, TKey>,\n  fields: readonly string[],\n  predicate: ((event: any, actor: Actor) => boolean) | null,\n  actor: Actor | undefined\n): Committed<TEvents, TKey> {\n  if (fields.length === 0) return event;\n  const data = event.data as Record<string, unknown>;\n  if (event.pii == null) {\n    const shredded: Record<string, unknown> = { ...data };\n    for (const f of fields) shredded[f] = SHREDDED;\n    return {\n      ...event,\n      data: shredded as Committed<TEvents, TKey>[\"data\"],\n    };\n  }\n  // Plaintext path requires both an actor AND a predicate that allows. Missing\n  // either → default-deny → REDACTED.\n  const allowed = !!actor && !!predicate && predicate(event, actor);\n  if (allowed) {\n    return {\n      ...event,\n      data: {\n        ...data,\n        ...(event.pii as Record<string, unknown>),\n      } as Committed<TEvents, TKey>[\"data\"],\n    };\n  }\n  const redacted: Record<string, unknown> = { ...data };\n  for (const f of fields) redacted[f] = REDACTED;\n  return {\n    ...event,\n    data: redacted as Committed<TEvents, TKey>[\"data\"],\n  };\n}\n\n/**\n * Build the **handler view** — sensitive keys removed entirely from `data`\n * and the `pii` field dropped from the event. Used before invoking projection\n * handlers and reaction handlers, which never see PII by framework rule.\n *\n * Different from {@link pii_gate} (which substitutes {@link REDACTED} or\n * {@link SHREDDED}) — projection tables and reaction sinks shouldn't even\n * structurally observe the keys, so a handler that mistakenly writes\n * `event.data.email` into a column would get `undefined`, not a sentinel\n * string that looks like real data. The strictness is deliberate.\n *\n * Reactions that genuinely need PII (e.g. a welcome-email reaction reading\n * `email`) opt back in by explicitly calling `app.load(stream, { actor:\n * system_actor })` inside the handler — pulling PII through the gate at the\n * call site makes the security-relevant path visible in code review.\n *\n * @internal\n */\nexport function pii_strip<\n  TEvents extends Schemas,\n  TKey extends keyof TEvents & string,\n>(\n  event: Committed<TEvents, TKey>,\n  fields: readonly string[]\n): Committed<TEvents, TKey> {\n  // Contract: `fields` is non-empty. `build_handle` / `build_handle_batch`\n  // filter on `fields.length > 0` before invocation.\n  const data = event.data as Record<string, unknown>;\n  const stripped: Record<string, unknown> = {};\n  for (const k of Object.keys(data)) {\n    if (!fields.includes(k)) stripped[k] = data[k];\n  }\n  const { pii: _drop_pii, ...rest } = event as Committed<TEvents, TKey> & {\n    pii?: unknown;\n  };\n  return {\n    ...rest,\n    data: stripped as Committed<TEvents, TKey>[\"data\"],\n  } as Committed<TEvents, TKey>;\n}\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 type * from \"./audit.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":["z","z"]}

package/dist/index.cjs

@@ -416,32 +416,18 @@ function pii_fields(schema) {
   return fields;
 }
 function pii_split(emitted, fields) {
-  const rec = emitted.data;
-  const clean = {};
+  const data = { ...emitted.data };
   const pii = {};
-  for (const k of Object.keys(rec)) {
-    if (fields.includes(k)) pii[k] = rec[k];
-    else clean[k] = rec[k];
+  for (const f of fields) {
+    if (f in data) {
+      pii[f] = data[f];
+      delete data[f];
+    }
   }
-  return { name: emitted.name, data: clean, pii };
-}
-function pii_merge(event, fields) {
-  const data = event.data;
-  const pii = event.pii;
-  if (pii != null) {
-    return {
-      ...event,
-      data: { ...data, ...pii }
-    };
-  }
-  const shredded = { ...data };
-  for (const f of fields) shredded[f] = SHREDDED;
-  return {
-    ...event,
-    data: shredded
-  };
+  return { name: emitted.name, data, pii };
 }
 function pii_gate(event, fields, predicate, actor) {
+  if (fields.length === 0) return event;
   const data = event.data;
   if (event.pii == null) {
     const shredded = { ...data };
@@ -2020,7 +2006,7 @@ async function load_restart_seeds(guarded, target_map, stream_info, event_to_sta
         );
         return;
       }
-      const snap2 = await load2(owner_state, stream);
+      const snap2 = await load2(owner_state, { stream });
       seed_states.set(stream, snap2.state);
     })
   );
@@ -2384,7 +2370,6 @@ async function scan(source, opts = {}, callback) {
           migrated = {
             ...event,
             name: migration.to,
-            // biome-ignore lint/suspicious/noExplicitAny: migration target shape is caller-defined
             data: new_data
           };
           migrated_count++;
@@ -2433,39 +2418,37 @@ async function scan(source, opts = {}, callback) {
     }
   };
 }
-async function load(me, stream, callback, asOf, actor) {
+async function load(me, target, callback) {
+  const { stream, actor, asOf } = target;
   const time_travel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
   const cached = time_travel ? void 0 : await cache2().get(stream);
   const cache_hit = !!cached;
   let state2 = cached?.state ?? (me.init ? me.init() : {});
   let patches = cached?.patches ?? 0;
   let snaps = cached?.snaps ?? 0;
-  let version = cached?.version ?? -1;
   let replayed = 0;
   let event;
   await store2().query(
-    (e) => {
-      version = e.version;
-      const typed = e;
-      event = me.view(typed, actor);
-      if (e.name === SNAP_EVENT) {
-        state2 = e.data;
+    (raw) => {
+      event = me.view(raw, actor);
+      if (event.name === SNAP_EVENT) {
+        state2 = event.data;
         snaps++;
         patches = 0;
         replayed++;
-      } else if (me.patch[e.name]) {
-        state2 = (0, import_act_patch.patch)(state2, me.patch[e.name](typed, state2));
+      } else if (me.patch[event.name]) {
+        state2 = (0, import_act_patch.patch)(state2, me.patch[event.name](event, state2));
         patches++;
         replayed++;
-      } else if (e.name !== TOMBSTONE_EVENT) {
+      } else if (event.name !== TOMBSTONE_EVENT) {
         log().warn(
-          `Skipping unknown event "${String(e.name)}" on stream "${stream}" (id=${e.id}) \u2014 no reducer in state "${me.name}"`
+          `Skipping unknown event "${String(event.name)}" on stream "${stream}" (id=${event.id}) \u2014 no reducer in state "${me.name}"`
         );
       }
       callback?.({
         event,
         state: state2,
-        version,
+        version: event.version,
         patches,
         snaps,
         cache_hit,
@@ -2478,39 +2461,43 @@ async function load(me, stream, callback, asOf, actor) {
       ...cached ? { after: cached.event_id } : { with_snaps: true, ...asOf }
     }
   );
-  if (replayed > 0 && !time_travel && event) {
+  if (replayed > 0 && !time_travel && event && !me.pii_aware) {
     await cache2().set(stream, {
       state: state2,
-      version,
+      version: event.version,
       event_id: event.id,
       patches,
       snaps
     });
   }
-  return { event, state: state2, version, patches, snaps, cache_hit, replayed };
+  return {
+    event,
+    state: state2,
+    version: event?.version ?? cached?.version ?? -1,
+    patches,
+    snaps,
+    cache_hit,
+    replayed
+  };
 }
-async function action(me, action2, target, payload, reactingTo, skipValidation = false, correlator = default_correlator) {
+async function action(me, action2, target, payload, options) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
-  const validated = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
+  const reactingTo = options?.reactingTo;
+  const correlator = options?.correlator ?? default_correlator;
+  const validated = validate(action2, payload, me.actions[action2]);
   const opts = me.options?.[action2];
   const max_retries = opts?.maxRetries ?? 0;
   for (let attempt = 0; ; attempt++) {
     try {
-      const snapshot = await load(
-        me,
-        stream,
-        void 0,
-        void 0,
-        target.actor
-      );
+      const snapshot = await load(me, { stream, actor: target.actor });
       if (snapshot.event?.name === TOMBSTONE_EVENT)
         throw new StreamClosedError(stream);
       const expected = expectedVersion ?? snapshot.event?.version;
       if (me.given) {
         const invariants = me.given[action2] || [];
-        invariants.forEach(({ valid, description }) => {
-          if (!valid(snapshot.state, actor))
+        invariants.forEach(({ valid: valid2, description }) => {
+          if (!valid2(snapshot.state, actor))
             throw new InvariantError(
               action2,
               validated,
@@ -2526,24 +2513,11 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
         return [snapshot];
       }
       const tuples = Array.isArray(result[0]) ? result : [result];
-      const deprecated = me._deprecated;
-      if (deprecated && deprecated.size > 0) {
-        const me_ = me;
-        const warned = me_._warned ?? (me_._warned = /* @__PURE__ */ new Set());
-        for (const [name] of tuples) {
-          const evt = name;
-          if (deprecated.has(evt) && !warned.has(evt)) {
-            warned.add(evt);
-            log().warn(
-              `Action "${String(action2)}" emitted deprecated event "${evt}". A newer version exists in the registry \u2014 update the action's .emit() to target the current version. (warned once per process)`
-            );
-          }
-        }
-      }
-      const emitted = tuples.map(([name, data]) => {
-        const validated2 = skipValidation ? data : validate(name, data, me.events[name]);
-        return me.message({ name, data: validated2 });
-      });
+      const valid = tuples.map(([name, data]) => ({
+        name,
+        data: validate(name, data, me.events[name])
+      }));
+      const emitted = valid.map((e) => me.message(e));
       const meta = {
         correlation: reactingTo?.meta.correlation || correlator({
           action: action2,
@@ -2584,12 +2558,13 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
         throw error;
       }
       let { state: state2, patches } = snapshot;
-      const snapshots = committed.map((event) => {
+      const snapshots = committed.map((row, i) => {
+        const event = { ...row, data: valid[i].data };
         const p = me.patch[event.name](event, state2);
         state2 = (0, import_act_patch.patch)(state2, p);
         patches++;
         return {
-          event: me.view(event, target.actor),
+          event,
           state: state2,
           version: event.version,
           patches,
@@ -2601,13 +2576,15 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
       });
       const last = snapshots.at(-1);
       const snapped = me.snap?.(last);
-      cache2().set(stream, {
-        state: last.state,
-        version: last.event.version,
-        event_id: last.event.id,
-        patches: snapped ? 0 : last.patches,
-        snaps: snapped ? last.snaps + 1 : last.snaps
-      }).catch((err) => log().error(err));
+      if (!me.pii_aware) {
+        cache2().set(stream, {
+          state: last.state,
+          version: last.event.version,
+          event_id: last.event.id,
+          patches: snapped ? 0 : last.patches,
+          snaps: snapped ? last.snaps + 1 : last.snaps
+        }).catch((err) => log().error(err));
+      }
       if (snapped) void snap(last);
       return snapshots;
     } catch (error) {
@@ -2674,15 +2651,7 @@ var traced = (inner, exit, entry) => (async (...args) => {
   return result;
 });
 function build_es(logger, correlator = default_correlator) {
-  const bound_action = (me, action_name, target, payload, reactingTo, skipValidation = false) => action(
-    me,
-    action_name,
-    target,
-    payload,
-    reactingTo,
-    skipValidation,
-    correlator
-  );
+  const bound_action = (me, action_name, target, payload, options) => action(me, action_name, target, payload, { correlator, ...options });
   if (logger.level !== "trace") {
     return {
       snap,
@@ -2701,7 +2670,7 @@ function build_es(logger, correlator = default_correlator) {
         )
       );
     }),
-    load: traced(load, (result, _me, stream, _cb, asOf) => {
+    load: traced(load, (result, _me, target) => {
       const stats = stats_marker(
         result.version,
         result.replayed,
@@ -2712,7 +2681,7 @@ function build_es(logger, correlator = default_correlator) {
         es_caption(
           "load",
           C_GREEN,
-          `${stream}${as_of_marker(asOf)} ${cache_marker(result.cache_hit)} ${stats}`
+          `${target.stream}${as_of_marker(target.asOf)} ${cache_marker(result.cache_hit)} ${stats}`
         )
       );
     }),
@@ -3200,13 +3169,10 @@ function build_handle(deps) {
     };
     for (const payload of payloads) {
       const { event, handler } = payload;
-      scoped_app.do = (action2, target, action_payload, reactingTo, skipValidation) => bound_do(
-        action2,
-        target,
-        action_payload,
-        reactingTo ?? event,
-        skipValidation
-      );
+      scoped_app.do = (action2, target, action_payload, options) => bound_do(action2, target, action_payload, {
+        ...options,
+        reactingTo: options?.reactingTo ?? event
+      });
       try {
         await handler(event, stream, scoped_app);
         at = event.id;
@@ -3612,8 +3578,9 @@ var Act = class {
    * @param action - The name of the action to execute
    * @param target - Target specification with stream ID and actor context
    * @param payload - Action payload matching the action's schema
-   * @param reactingTo - Optional event that triggered this action (for correlation)
-   * @param skipValidation - Skip schema validation (use carefully, for performance)
+   * @param options - Per-call dispatch options ({@link DoOptions}) —
+   *   `reactingTo` to thread correlation, `correlator` to override the
+   *   framework or orchestrator-level correlator for this call only.
    * @returns Array of snapshots for all affected states (usually one)
    *
    * @throws {ValidationError} If payload doesn't match action schema
@@ -3668,7 +3635,7 @@ var Act = class {
    *         { amount: event.data.items.length }
    *       );
    *       // To use a different correlation, pass reactingTo explicitly:
-   *       // await app.do("reduceStock", target, payload, customEvent);
+   *       // await app.do("reduceStock", target, payload, { reactingTo: customEvent });
    *     })
    *     .to("inventory-1")
    *   .build();
@@ -3678,15 +3645,14 @@ var Act = class {
    * @see {@link Snapshot} for return value structure
    * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
    */
-  async do(action2, target, payload, reactingTo, skipValidation = false) {
+  async do(action2, target, payload, options) {
     return this._scoped(async () => {
       const snapshots = await this._es.action(
         this.registry.actions[action2],
         action2,
         target,
         payload,
-        reactingTo,
-        skipValidation
+        options
       );
       if (this._reactive_events.size > 0)
         this._arm_for_event_names(
@@ -3696,7 +3662,7 @@ var Act = class {
       return snapshots;
     });
   }
-  async load(stateOrName, stream, callback, asOf, actor) {
+  async load(stateOrName, streamOrTarget, callback, asOf) {
     return this._scoped(async () => {
       let merged;
       if (typeof stateOrName === "string") {
@@ -3706,7 +3672,12 @@ var Act = class {
       } else {
         merged = this._states.get(stateOrName.name) || stateOrName;
       }
-      return await this._es.load(merged, stream, callback, asOf, actor);
+      const target = typeof streamOrTarget === "string" ? {
+        stream: streamOrTarget,
+        actor: void 0,
+        asOf
+      } : streamOrTarget;
+      return await this._es.load(merged, target, callback);
     });
   }
   /**
@@ -4430,11 +4401,14 @@ function act() {
   const states = /* @__PURE__ */ new Map();
   const _sf = /* @__PURE__ */ new Map();
   const _dp = /* @__PURE__ */ new Map();
+  const _de = /* @__PURE__ */ new Map();
+  const EMPTY_DEPRECATED = /* @__PURE__ */ new Set();
   const registry = {
     actions: {},
     events: {},
     sensitive_fields: (event_name) => _sf.get(event_name) ?? [],
-    disclosure_predicate: (state_name) => _dp.get(state_name) ?? null
+    disclosure_predicate: (state_name) => _dp.get(state_name) ?? null,
+    deprecated_events: (state_name) => _de.get(state_name) ?? EMPTY_DEPRECATED
   };
   const pending_projections = [];
   const batch_handlers = /* @__PURE__ */ new Map();
@@ -4446,7 +4420,7 @@ function act() {
       const event_names = Object.keys(state2.events);
       const deprecated = deprecated_event_names(event_names);
       if (deprecated.size === 0) continue;
-      state2._deprecated = deprecated;
+      _de.set(state2.name, deprecated);
       for (const name of deprecated) {
         const current = current_version_of(name, event_names);
         deprecation_summary.push({
@@ -4574,18 +4548,17 @@ function act() {
             );
           }
           const disclose = state2.disclose ?? null;
-          state2.view = (event, actor) => {
-            const fields = fields_by_event.get(event.name);
-            return fields ? pii_gate(event, fields, disclose, actor) : event;
-          };
+          state2.pii_aware = true;
+          state2.view = (event, actor) => pii_gate(
+            event,
+            fields_by_event.get(event.name) ?? [],
+            disclose,
+            actor
+          );
           state2.message = (validated) => {
             const fields = fields_by_event.get(validated.name);
             return fields ? pii_split(validated, fields) : validated;
           };
-          for (const [event_name, fields] of fields_by_event) {
-            const original = state2.patch[event_name];
-            state2.patch[event_name] = (event, s) => original(pii_merge(event, fields), s);
-          }
         }
         for (const [target, original] of batch_handlers) {
           const wrapped = async (events, stream) => {
@@ -4765,9 +4738,10 @@ function state(entry) {
             init,
             patch: default_patch,
             on: {},
-            // Step delegates initialized as identity. `act().build()`
-            // overrides on states with `sensitive(...)` events to bake in
-            // the gate / split.
+            // Step delegates initialized as identity, `pii_aware` false.
+            // `act().build()` flips both on states with `sensitive(...)`
+            // events to bake in the gate / split and gate the cache write.
+            pii_aware: false,
             view: (event) => event,
             message: (validated) => validated
           };