@rotorsoft/act 1.9.0 → 1.10.0

package/dist/index.cjs

@@ -51,6 +51,8 @@ __export(index_exports, {
   NonRetryableError: () => NonRetryableError,
   PackageSchema: () => PackageSchema,
   QuerySchema: () => QuerySchema,
+  REDACTED: () => REDACTED,
+  SHREDDED: () => SHREDDED,
   SNAP_EVENT: () => SNAP_EVENT,
   StreamClosedError: () => StreamClosedError,
   TOMBSTONE_EVENT: () => TOMBSTONE_EVENT,
@@ -67,6 +69,7 @@ __export(index_exports, {
   port: () => port,
   projection: () => projection,
   scoped: () => scoped,
+  sensitive: () => sensitive,
   sleep: () => sleep,
   slice: () => slice,
   state: () => state,
@@ -380,55 +383,150 @@ var NonRetryableError = class extends Error {
 };
 
 // src/utils.ts
-var import_zod3 = require("zod");
+var import_zod4 = require("zod");
 
 // src/config.ts
 var fs = __toESM(require("fs"), 1);
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 
 // src/types/schemas.ts
+var import_zod2 = require("zod");
+
+// src/internal/sensitive.ts
 var import_zod = require("zod");
-var ZodEmpty = import_zod.z.record(import_zod.z.string(), import_zod.z.never());
-var ActorSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  name: import_zod.z.string()
+var REDACTED = "[REDACTED]";
+var SHREDDED = "[SHREDDED]";
+var _registry = import_zod.z.registry();
+function is_pii(schema) {
+  let cur = schema;
+  while (true) {
+    if (_registry.has(cur)) return true;
+    const inner = cur._def?.innerType;
+    if (!inner || inner === cur) return false;
+    cur = inner;
+  }
+}
+function pii_fields(schema) {
+  const shape = schema.shape;
+  if (!shape || typeof shape !== "object") return [];
+  const fields = [];
+  for (const key of Object.keys(shape)) {
+    if (is_pii(shape[key])) fields.push(key);
+  }
+  return fields;
+}
+function pii_split(emitted, fields) {
+  const rec = emitted.data;
+  const clean = {};
+  const pii = {};
+  for (const k of Object.keys(rec)) {
+    if (fields.includes(k)) pii[k] = rec[k];
+    else clean[k] = rec[k];
+  }
+  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
+  };
+}
+function pii_gate(event, fields, predicate, actor) {
+  const data = event.data;
+  if (event.pii == null) {
+    const shredded = { ...data };
+    for (const f of fields) shredded[f] = SHREDDED;
+    return {
+      ...event,
+      data: shredded
+    };
+  }
+  const allowed = !!actor && !!predicate && predicate(event, actor);
+  if (allowed) {
+    return {
+      ...event,
+      data: {
+        ...data,
+        ...event.pii
+      }
+    };
+  }
+  const redacted = { ...data };
+  for (const f of fields) redacted[f] = REDACTED;
+  return {
+    ...event,
+    data: redacted
+  };
+}
+function pii_strip(event, fields) {
+  const data = event.data;
+  const stripped = {};
+  for (const k of Object.keys(data)) {
+    if (!fields.includes(k)) stripped[k] = data[k];
+  }
+  const { pii: _drop_pii, ...rest } = event;
+  return {
+    ...rest,
+    data: stripped
+  };
+}
+
+// src/types/schemas.ts
+var ZodEmpty = import_zod2.z.record(import_zod2.z.string(), import_zod2.z.never());
+function sensitive(schema) {
+  _registry.add(schema, { sensitive: true });
+  return schema;
+}
+var ActorSchema = import_zod2.z.object({
+  id: import_zod2.z.string(),
+  name: import_zod2.z.string()
 }).loose().readonly();
-var TargetSchema = import_zod.z.object({
-  stream: import_zod.z.string(),
+var TargetSchema = import_zod2.z.object({
+  stream: import_zod2.z.string(),
   actor: ActorSchema,
-  expectedVersion: import_zod.z.number().optional()
+  expectedVersion: import_zod2.z.number().optional()
 }).loose().readonly();
-var CausationEventSchema = import_zod.z.object({
-  id: import_zod.z.number(),
-  name: import_zod.z.string(),
-  stream: import_zod.z.string()
+var CausationEventSchema = import_zod2.z.object({
+  id: import_zod2.z.number(),
+  name: import_zod2.z.string(),
+  stream: import_zod2.z.string()
 });
-var EventMetaSchema = import_zod.z.object({
-  correlation: import_zod.z.string(),
-  causation: import_zod.z.object({
-    action: TargetSchema.and(import_zod.z.object({ name: import_zod.z.string() })).optional(),
+var EventMetaSchema = import_zod2.z.object({
+  correlation: import_zod2.z.string(),
+  causation: import_zod2.z.object({
+    action: TargetSchema.and(import_zod2.z.object({ name: import_zod2.z.string() })).optional(),
     event: CausationEventSchema.optional()
   })
 }).readonly();
-var CommittedMetaSchema = import_zod.z.object({
-  id: import_zod.z.number(),
-  stream: import_zod.z.string(),
-  version: import_zod.z.number(),
-  created: import_zod.z.date(),
+var CommittedMetaSchema = import_zod2.z.object({
+  id: import_zod2.z.number(),
+  stream: import_zod2.z.string(),
+  version: import_zod2.z.number(),
+  created: import_zod2.z.date(),
   meta: EventMetaSchema
 }).readonly();
-var QuerySchema = import_zod.z.object({
-  stream: import_zod.z.string().optional(),
-  names: import_zod.z.string().array().optional(),
-  before: import_zod.z.number().optional(),
-  after: import_zod.z.number().optional(),
-  limit: import_zod.z.number().optional(),
-  created_before: import_zod.z.date().optional(),
-  created_after: import_zod.z.date().optional(),
-  backward: import_zod.z.boolean().optional(),
-  correlation: import_zod.z.string().optional(),
-  with_snaps: import_zod.z.boolean().optional(),
-  stream_exact: import_zod.z.boolean().optional()
+var QuerySchema = import_zod2.z.object({
+  stream: import_zod2.z.string().optional(),
+  names: import_zod2.z.string().array().optional(),
+  before: import_zod2.z.number().optional(),
+  after: import_zod2.z.number().optional(),
+  limit: import_zod2.z.number().optional(),
+  created_before: import_zod2.z.date().optional(),
+  created_after: import_zod2.z.date().optional(),
+  backward: import_zod2.z.boolean().optional(),
+  correlation: import_zod2.z.string().optional(),
+  with_snaps: import_zod2.z.boolean().optional(),
+  stream_exact: import_zod2.z.boolean().optional()
 }).readonly();
 
 // src/types/index.ts
@@ -448,13 +546,13 @@ var LogLevels = [
 ];
 
 // src/config.ts
-var PackageSchema = import_zod2.z.object({
-  name: import_zod2.z.string().min(1),
-  version: import_zod2.z.string().min(1),
-  description: import_zod2.z.string().min(1).optional(),
-  author: import_zod2.z.object({ name: import_zod2.z.string().min(1), email: import_zod2.z.string().optional() }).optional().or(import_zod2.z.string().min(1)).optional(),
-  license: import_zod2.z.string().min(1).optional(),
-  dependencies: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).optional()
+var PackageSchema = import_zod3.z.object({
+  name: import_zod3.z.string().min(1),
+  version: import_zod3.z.string().min(1),
+  description: import_zod3.z.string().min(1).optional(),
+  author: import_zod3.z.object({ name: import_zod3.z.string().min(1), email: import_zod3.z.string().optional() }).optional().or(import_zod3.z.string().min(1)).optional(),
+  license: import_zod3.z.string().min(1).optional(),
+  dependencies: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.string()).optional()
 });
 var FALLBACK_PACKAGE = {
   name: "act-fallback",
@@ -472,10 +570,10 @@ var getPackage = () => {
 };
 var pkgLoadError;
 var BaseSchema = PackageSchema.extend({
-  env: import_zod2.z.enum(Environments),
-  logLevel: import_zod2.z.enum(LogLevels),
-  logSingleLine: import_zod2.z.boolean(),
-  sleepMs: import_zod2.z.number().int().min(0).max(5e3)
+  env: import_zod3.z.enum(Environments),
+  logLevel: import_zod3.z.enum(LogLevels),
+  logSingleLine: import_zod3.z.boolean(),
+  sleepMs: import_zod3.z.number().int().min(0).max(5e3)
 });
 var { NODE_ENV, LOG_LEVEL, LOG_SINGLE_LINE, SLEEP_MS } = process.env;
 var env = NODE_ENV || "development";
@@ -506,8 +604,8 @@ var validate = (target, payload, schema) => {
   try {
     return schema ? schema.parse(payload) : payload;
   } catch (error) {
-    if (error instanceof import_zod3.ZodError) {
-      throw new ValidationError(target, payload, (0, import_zod3.prettifyError)(error));
+    if (error instanceof import_zod4.ZodError) {
+      throw new ValidationError(target, payload, (0, import_zod4.prettifyError)(error));
     }
     throw new ValidationError(target, payload, error);
   }
@@ -2334,7 +2432,7 @@ async function scan(source, opts = {}, callback) {
     }
   };
 }
-async function load(me, stream, callback, asOf) {
+async function load(me, stream, callback, asOf, actor) {
   const timeTravel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
   const cached = timeTravel ? void 0 : await cache2().get(stream);
   const cache_hit = !!cached;
@@ -2346,15 +2444,16 @@ async function load(me, stream, callback, asOf) {
   let event;
   await store2().query(
     (e) => {
-      event = e;
       version = e.version;
+      const typed = e;
+      event = me.view(typed, actor);
       if (e.name === SNAP_EVENT) {
         state2 = e.data;
         snaps++;
         patches = 0;
         replayed++;
       } else if (me.patch[e.name]) {
-        state2 = (0, import_act_patch.patch)(state2, me.patch[e.name](event, state2));
+        state2 = (0, import_act_patch.patch)(state2, me.patch[e.name](typed, state2));
         patches++;
         replayed++;
       } else if (e.name !== TOMBSTONE_EVENT) {
@@ -2397,7 +2496,13 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
   const maxRetries = opts?.maxRetries ?? 0;
   for (let attempt = 0; ; attempt++) {
     try {
-      const snapshot = await load(me, stream);
+      const snapshot = await load(
+        me,
+        stream,
+        void 0,
+        void 0,
+        target.actor
+      );
       if (snapshot.event?.name === TOMBSTONE_EVENT)
         throw new StreamClosedError(stream);
       const expected = expectedVersion ?? snapshot.event?.version;
@@ -2434,10 +2539,10 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
           }
         }
       }
-      const emitted = tuples.map(([name, data]) => ({
-        name,
-        data: skipValidation ? data : validate(name, data, me.events[name])
-      }));
+      const emitted = tuples.map(([name, data]) => {
+        const validated2 = skipValidation ? data : validate(name, data, me.events[name]);
+        return me.message({ name, data: validated2 });
+      });
       const meta = {
         correlation: reactingTo?.meta.correlation || correlator({
           action: action2,
@@ -2449,8 +2554,8 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
           action: {
             name: action2,
             ...target
-            // payload intentionally omitted: it can be large or contain PII,
-            // and callers correlate via the correlation id when they need it.
+            // payload intentionally omitted from causation metadata —
+            // callers correlate via the correlation id when they need it.
           },
           event: reactingTo ? {
             id: reactingTo.id,
@@ -2483,7 +2588,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
         state2 = (0, import_act_patch.patch)(state2, p);
         patches++;
         return {
-          event,
+          event: me.view(event, target.actor),
           state: state2,
           version: event.version,
           patches,
@@ -2568,7 +2673,7 @@ var traced = (inner, exit, entry) => (async (...args) => {
   return result;
 });
 function buildEs(logger, correlator = defaultCorrelator) {
-  const boundAction = (me, actionName, target, payload, reactingTo, skipValidation = false) => action(
+  const bound_action = (me, actionName, target, payload, reactingTo, skipValidation = false) => action(
     me,
     actionName,
     target,
@@ -2581,7 +2686,7 @@ function buildEs(logger, correlator = defaultCorrelator) {
     return {
       snap,
       load,
-      action: boundAction,
+      action: bound_action,
       tombstone
     };
   }
@@ -2611,7 +2716,7 @@ function buildEs(logger, correlator = defaultCorrelator) {
       );
     }),
     action: traced(
-      boundAction,
+      bound_action,
       (snapshots, _me, _action, target) => {
         const committed = snapshots.filter((s) => s.event);
         if (committed.length) {
@@ -2904,7 +3009,7 @@ var DrainController = class {
 };
 
 // src/internal/merge.ts
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 function baseTypeName(zodType) {
   let t = zodType;
   while (typeof t.unwrap === "function") {
@@ -2913,7 +3018,7 @@ function baseTypeName(zodType) {
   return t.constructor.name;
 }
 function mergeSchemas(existing, incoming, stateName) {
-  if (existing instanceof import_zod4.ZodObject && incoming instanceof import_zod4.ZodObject) {
+  if (existing instanceof import_zod5.ZodObject && incoming instanceof import_zod5.ZodObject) {
     const existingShape = existing.shape;
     const incomingShape = incoming.shape;
     for (const key of Object.keys(incomingShape)) {
@@ -3068,7 +3173,14 @@ function finalize(lease, handled, at, error, options, logger, failed_at) {
   };
 }
 function buildHandle(deps) {
-  const { logger, boundDo, boundLoad, boundQuery, boundQueryArray } = deps;
+  const {
+    logger,
+    bound_do,
+    bound_load,
+    bound_query,
+    bound_query_array,
+    bound_forget
+  } = deps;
   return async (lease, payloads) => {
     if (payloads.length === 0) return { lease, handled: 0, acked_at: lease.at };
     const stream = lease.stream;
@@ -3077,14 +3189,15 @@ function buildHandle(deps) {
     if (lease.retry > 0)
       logger.warn(`Retrying ${stream}@${at} (${lease.retry}).`);
     const scopedApp = {
-      do: boundDo,
-      load: boundLoad,
-      query: boundQuery,
-      query_array: boundQueryArray
+      do: bound_do,
+      load: bound_load,
+      query: bound_query,
+      query_array: bound_query_array,
+      forget: bound_forget
     };
     for (const payload of payloads) {
       const { event, handler } = payload;
-      scopedApp.do = (action2, target, actionPayload, reactingTo, skipValidation) => boundDo(
+      scopedApp.do = (action2, target, actionPayload, reactingTo, skipValidation) => bound_do(
         action2,
         target,
         actionPayload,
@@ -3113,7 +3226,9 @@ function buildHandle(deps) {
 function buildHandleBatch(logger) {
   return async (lease, payloads, batchHandler) => {
     const stream = lease.stream;
-    const events = payloads.map((p) => p.event);
+    const events = payloads.map(
+      (p) => p.event
+    );
     const options = payloads[0].options;
     if (lease.retry > 0)
       logger.warn(`Retrying batch ${stream}@${events[0].id} (${lease.retry}).`);
@@ -3296,6 +3411,7 @@ var Act = class {
   _bound_load = this.load.bind(this);
   _bound_query = this.query.bind(this);
   _bound_query_array = this.query_array.bind(this);
+  _bound_forget = this.forget.bind(this);
   /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
   _handle;
   _handle_batch;
@@ -3341,10 +3457,11 @@ var Act = class {
     this._cd = buildDrain(this._logger);
     this._handle = buildHandle({
       logger: this._logger,
-      boundDo: this._bound_do,
-      boundLoad: this._bound_load,
-      boundQuery: this._bound_query,
-      boundQueryArray: this._bound_query_array
+      bound_do: this._bound_do,
+      bound_load: this._bound_load,
+      bound_query: this._bound_query,
+      bound_query_array: this._bound_query_array,
+      bound_forget: this._bound_forget
     });
     this._handle_batch = buildHandleBatch(this._logger);
     const {
@@ -3576,7 +3693,7 @@ var Act = class {
       return snapshots;
     });
   }
-  async load(stateOrName, stream, callback, asOf) {
+  async load(stateOrName, stream, callback, asOf, actor) {
     return this._scoped(async () => {
       let merged;
       if (typeof stateOrName === "string") {
@@ -3586,7 +3703,7 @@ var Act = class {
       } else {
         merged = this._states.get(stateOrName.name) || stateOrName;
       }
-      return await this._es.load(merged, stream, callback, asOf);
+      return await this._es.load(merged, stream, callback, asOf, actor);
     });
   }
   /**
@@ -3680,6 +3797,34 @@ var Act = class {
       return events;
     });
   }
+  /**
+   * Wipe the sensitive-data payload for every event on the stream — see
+   * {@link IAct.forget}. Application-level half of #566.
+   *
+   * Throws on adapters without `Store.forget_pii`, invalidates the cache
+   * entry for the stream, emits the `forgotten` lifecycle event with the
+   * row count. Idempotent: a second call returns `{eventCount: 0}` and
+   * does NOT re-emit.
+   *
+   * @param stream - Target stream.
+   * @returns `{eventCount}` — number of events whose PII column was wiped.
+   */
+  async forget(stream) {
+    return this._scoped(async () => {
+      const s = store2();
+      if (!s.forget_pii) {
+        throw new Error(
+          `Store does not implement forget_pii \u2014 adapter cannot comply with sensitive-data erasure. Use an adapter that declares pii_isolation: true (e.g. @rotorsoft/act on the in-memory store).`
+        );
+      }
+      const eventCount = await s.forget_pii(stream);
+      await cache2().invalidate(stream);
+      if (eventCount > 0) {
+        this.emit("forgotten", { stream, at: /* @__PURE__ */ new Date(), eventCount });
+      }
+      return { eventCount };
+    });
+  }
   /**
    * Processes pending reactions by draining uncommitted events from the event store.
    *
@@ -4280,9 +4425,13 @@ function validateLaneReferences(registry, lanes) {
 }
 function act() {
   const states = /* @__PURE__ */ new Map();
+  const _sf = /* @__PURE__ */ new Map();
+  const _dp = /* @__PURE__ */ new Map();
   const registry = {
     actions: {},
-    events: {}
+    events: {},
+    sensitive_fields: (eventName) => _sf.get(eventName) ?? [],
+    disclosure_predicate: (stateName) => _dp.get(stateName) ?? null
   };
   const pendingProjections = [];
   const batchHandlers = /* @__PURE__ */ new Map();
@@ -4393,6 +4542,58 @@ function act() {
         }
         finalizeDeprecations();
         validateLaneReferences(registry, lanes);
+        for (const [eventName, reg] of Object.entries(
+          registry.events
+        )) {
+          const fields = pii_fields(reg.schema);
+          if (fields.length === 0) continue;
+          _sf.set(eventName, fields);
+          for (const [name, reaction] of reg.reactions) {
+            const inner = reaction.handler;
+            const wrapped = (event, stream, app) => inner(pii_strip(event, fields), stream, app);
+            Object.defineProperty(wrapped, "name", { value: inner.name });
+            reaction.handler = wrapped;
+            reg.reactions.set(name, reaction);
+          }
+        }
+        for (const state2 of states.values()) {
+          if (state2.disclose) _dp.set(state2.name, state2.disclose);
+          const fields_by_event = /* @__PURE__ */ new Map();
+          for (const eventName of Object.keys(state2.events)) {
+            const fields = _sf.get(eventName);
+            if (fields) fields_by_event.set(eventName, fields);
+          }
+          if (fields_by_event.size === 0) continue;
+          if (state2.snap) {
+            const offending = [...fields_by_event.keys()];
+            throw new Error(
+              `State "${state2.name}" cannot snapshot \u2014 events {${offending.join(", ")}} carry sensitive fields. Snapshots write derived state into __snapshot__.data, which forget_pii cannot reach. Remove .snap() or remove sensitive(...) markers.`
+            );
+          }
+          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.message = (validated) => {
+            const fields = fields_by_event.get(validated.name);
+            return fields ? pii_split(validated, fields) : validated;
+          };
+          for (const [eventName, fields] of fields_by_event) {
+            const original = state2.patch[eventName];
+            state2.patch[eventName] = (event, s) => original(pii_merge(event, fields), s);
+          }
+        }
+        for (const [target, original] of batchHandlers) {
+          const wrapped = async (events, stream) => {
+            const stripped = events.map((e) => {
+              const f = _sf.get(e.name);
+              return f ? pii_strip(e, f) : e;
+            });
+            return original(stripped, stream);
+          };
+          batchHandlers.set(target, wrapped);
+        }
         _built = true;
       }
       return new Act(
@@ -4560,7 +4761,12 @@ function state(entry) {
             name,
             init,
             patch: defaultPatch,
-            on: {}
+            on: {},
+            // Step delegates initialized as identity. `act().build()`
+            // overrides on states with `sensitive(...)` events to bake in
+            // the gate / split.
+            view: (event) => event,
+            message: (validated) => validated
           };
           const builder = action_builder(internal);
           return Object.assign(builder, {
@@ -4612,6 +4818,10 @@ function action_builder(state2) {
       internal.snap = snap2;
       return builder;
     },
+    discloses(disclose) {
+      internal.disclose = disclose;
+      return builder;
+    },
     build() {
       return internal;
     }
@@ -4802,6 +5012,8 @@ function writeLine(writer, line) {
   NonRetryableError,
   PackageSchema,
   QuerySchema,
+  REDACTED,
+  SHREDDED,
   SNAP_EVENT,
   StreamClosedError,
   TOMBSTONE_EVENT,
@@ -4818,6 +5030,7 @@ function writeLine(writer, line) {
   port,
   projection,
   scoped,
+  sensitive,
   sleep,
   slice,
   state,