@directive-run/mutator 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# @directive-run/mutator changelog
+
+## 0.2.0
+
+### Minor Changes
+
+- [`dc4ac7b`](https://github.com/directive-run/directive/commit/dc4ac7b93007104ce4973d86fb3d6f6a5d1fcded) Thanks [@jasoncomes](https://github.com/jasoncomes)! - Add `cancellable()` HOC — auto-cancel-on-supersede for mutator handlers (R1.C v0.1)
+
+  The third BUILD CANDIDATE from the AE-review-loop innovation pass. Wrap a mutator handler with `cancellable()` to get auto-cancellation: a fresh dispatch of the same wrapped handler aborts the prior in-flight invocation, OR an optional timeout fires the abort after N ms.
+
+  ```ts
+  import { defineMutator, cancellable } from "@directive-run/mutator";
+
+  const formMutator = defineMutator<MyMutations, MyFacts>({
+    search: cancellable(
+      { supersedeOn: "self", timeoutMs: 3_000 },
+      async ({ payload, facts, signal }) => {
+        const res = await fetch(`/q?${payload.q}`, { signal });
+        facts.results = await res.json();
+      }
+    ),
+    submit: async ({ payload, facts }) => {
+      facts.values = await deps.submit(payload.values);
+    },
+  });
+  ```
+
+  **Two cancellation triggers, both opt-in:**
+
+  - `supersedeOn: 'self'` (default) — new dispatch supersedes prior
+  - `supersedeOn: 'never'` — only timeout fires; parallel runs are fine
+  - `timeoutMs: number` — abort after N ms from invocation start
+
+  **Test ergonomics.** Pass `virtualClock.setTimeout` from `@directive-run/core` via the `setTimeout` option to make timeouts fire synchronously under `clock.advanceBy(ms)` — no real-time waits.
+
+  The signal's `.reason` carries a typed `CancelReason`:
+
+  ```ts
+  type CancelReason =
+    | { kind: "superseded" }
+    | { kind: "timeout"; afterMs: number };
+  ```
+
+  **Composition.** Drops in directly to `defineMutator`'s handler map slot. Two separate `cancellable()` HOCs around different handlers do NOT cancel each other — the supersession registry is closure-scoped per call.
+
+  **v0.1 scope:** `cancellable()` is a value-layer HOC; engine-side never sees a difference between a wrapped handler and a plain async one. v0.2 will explore the timeline integration so `expect(timeline).toCancel('search')` matchers can assert against the abort stream.
+
+  9 new tests covering basic invocation, supersession (both modes), timeout (using virtualClock for determinism), supersession+timeout composition, HOC independence.
+
+## 0.1.0 — 2026-04-29
+
+Initial release.
+
+### Added — v0.2 (R1.C cancellable)
+
+- `cancellable(opts, handler)` — HOC that wraps a mutator handler with
+  auto-cancellation. Receives a `signal: AbortSignal` in the handler
+  context. Two cancellation triggers: `supersedeOn: 'self' | 'never'`
+  (default `'self'`) and `timeoutMs?: number`. The signal's `reason`
+  carries a typed `CancelReason` distinguishing `{kind:'superseded'}`
+  from `{kind:'timeout', afterMs}`. Pass `setTimeout` from
+  `virtualClock` for deterministic test timing.
+- `CancellableOptions`, `CancellableHandlerContext<F, P>`,
+  `CancelReason` type exports.
+
+### Added — v0.1
+
+- `defineMutator(handlers)` — typed builder that returns six fragments
+  (facts / events / requirements / eventHandlers / constraints /
+  resolvers) wiring a discriminated `pendingMutation` lifecycle into a
+  Directive module.
+- `mutate(kind, payload?)` — typed payload constructor for `MUTATE`
+  dispatches.
+- Single-flight concurrency model: new mutations overwrite in-flight ones
+  via the `pendingMutation` fact.
+- Error capture: thrown handlers surface on `pendingMutation.error`
+  with `status: 'failed'` (a distinct status from `'running'` so the
+  UI can disambiguate; the constraint stops firing).
+- Built on `@directive-run/core@^1.2.0` (requires `ctx.requeue` for
+  handler-cascade chains).
+
+### Known gaps
+
+- Parallel-of-same-shape mutations not supported — last-write-wins.
+- No runtime payload validation — TypeScript only at dispatch site.
+- Optimistic / snapshot-rollback support belongs to upcoming
+  `@directive-run/optimistic`; do manual rollback inside handlers for
+  now.
+
+### Why the 0.x version
+
+This package collapses a real-world boilerplate pattern but the API
+shape (six-spread vs builder vs HOC) is still being validated against
+production use. v1.0 ships once at least three external consumers have
+worn the API end-to-end.

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Sizls ∞ Jason Comes
+
+This project is dual-licensed under MIT OR Apache-2.0. You may choose
+either license. See LICENSE-APACHE for the Apache License, Version 2.0.
+
+---
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# `@directive-run/mutator`
+
+> Discriminated mutation helper for Directive — collapse the
+> `pendingAction` ceremony to a typed handler map.
+
+```sh
+npm install @directive-run/mutator
+```
+
+> **Naming heads-up:** the mutation discriminator is named **`kind`**,
+> not `type`. Directive's event dispatcher reserves `payload.type` for
+> its own event-name routing — `type` here would collide with `MUTATE`
+> and route the dispatch to a non-existent event handler. Use `kind`
+> everywhere; the typed `mutate(kind, payload)` constructor builds the
+> right shape for you.
+
+## What it solves
+
+Across the 55-cycle Minglingo XState→Directive migration, **12 modules**
+ended up with the same shape:
+
+- a nullable `pendingAction` fact holding a discriminated union
+- an event handler that sets it
+- a constraint that fires while it's non-null
+- a resolver that switches on the discriminator and clears the fact
+
+That's ~50 lines of boilerplate per module. This package contributes all
+four pieces from a single typed declaration, so you write only the
+per-variant handler bodies.
+
+## Quick start
+
+```ts
+import { createModule, createSystem, t } from '@directive-run/core';
+import { defineMutator, mutate } from '@directive-run/mutator';
+
+type FormMutations = {
+  submit: { values: FormValues };
+  cancel: {};
+  retry: { reason: string };
+};
+
+interface FormDeps {
+  submit: (values: FormValues) => Promise<FormValues>;
+}
+
+export function createFormModule(deps: FormDeps) {
+  // Idiomatic Directive: handlers close over deps from the factory scope.
+  const mut = defineMutator<FormMutations, FormFacts>({
+    submit: async ({ payload, facts }) => {
+      facts.values = await deps.submit(payload.values); // ← closure
+    },
+    cancel: ({ facts }) => { facts.values = null; },
+    retry: async ({ payload, facts }) => {
+      facts.lastRetryReason = payload.reason;
+    },
+  });
+
+  return createModule('form', {
+    schema: {
+      facts: {
+        ...mut.facts,                // → adds `pendingMutation`
+        values: t.object<FormValues>().nullable(),
+        lastRetryReason: t.string().nullable(),
+      },
+      events: { ...mut.events },     // → adds `MUTATE` event
+      requirements: { ...mut.requirements }, // → adds PROCESS_MUTATION
+    },
+    init: (f) => {
+      f.pendingMutation = null;
+      f.values = null;
+      f.lastRetryReason = null;
+    },
+    events: { ...mut.eventHandlers }, // sets pendingMutation on MUTATE
+    constraints: { ...mut.constraints },
+    resolvers: { ...mut.resolvers },
+  });
+}
+
+// Usage:
+const sys = createSystem({ module: createFormModule(deps), deps });
+sys.start();
+sys.events.MUTATE(mutate<FormMutations>('submit', { values }));
+```
+
+The `mutate(kind, payload?)` helper is a typed payload constructor.
+The `kind` argument restricts the payload shape — passing a
+wrong-shape payload is a compile error.
+
+## Anatomy
+
+`defineMutator(handlers)` returns six fragments. You spread each into the
+matching position of your `createModule` config:
+
+| Fragment | Spreads into | Contributes |
+|---|---|---|
+| `mut.facts` | `schema.facts` | `pendingMutation: t.object<DiscriminatedUnion>().nullable()` |
+| `mut.events` | `schema.events` | `MUTATE: PendingMutation<M>` |
+| `mut.requirements` | `schema.requirements` | `PROCESS_MUTATION: {}` |
+| `mut.eventHandlers` | `events:` | `MUTATE` handler that sets `pendingMutation` |
+| `mut.constraints` | `constraints:` | `pendingMutation: { when, require }` |
+| `mut.resolvers` | `resolvers:` | dispatches to the handler matching the discriminator |
+
+The total spread cost is six lines. The savings come from not writing the
+constraint/resolver/dispatch bodies yourself.
+
+## Lifecycle
+
+```
+sys.events.MUTATE({ kind, payload, status: 'pending', error: null })
+  → pendingMutation fact set to that value
+  → constraint fires (pendingMutation !== null && status === 'pending')
+  → resolver wakes
+    → marks status: 'running'
+    → looks up handler by kind
+    → calls handler({ payload, facts, deps, requeue })
+    → on success: pendingMutation = null
+    → on throw: pendingMutation.status = 'failed' + .error = message
+                (constraint stops firing — no infinite retry; UI can
+                 disambiguate "still running" from "stopped on error")
+```
+
+> `kind` (not `type`) discriminates the mutation variant. Directive's
+> own event dispatcher reserves the `type` field for its own
+> event-name routing — colliding here would route the dispatch to a
+> nonexistent event handler. `kind` keeps the two namespaces separate.
+
+A failed mutation leaves `pendingMutation` non-null with `status:
+'failed'` (a distinct status from `'running'`, so the UI can
+disambiguate "still working" from "stopped on error"). Read
+`pendingMutation.error` to surface to the UI; dispatch a fresh `MUTATE`
+to retry (which overwrites the failed fact and re-fires).
+
+**XSS warning.** `pendingMutation.error` is a plaintext `string` that
+may echo handler-thrown messages, which in turn may have interpolated
+user-controlled input. Render it via `{error}` in JSX (default-escaped)
+or `textContent` — **never** via `dangerouslySetInnerHTML`, markdown
+rendering, or any other HTML-evaluating sink. The runtime truncates
+captured errors to 500 characters as a defense in depth, but that does
+not sanitize content; only escape on render.
+
+## Concurrency
+
+The default model is single-flight — one mutation in flight at a time. If
+a new `MUTATE` arrives while a handler is running, it overwrites the fact
+and the constraint re-fires once the in-flight handler completes (which
+nulls the fact, then the new value triggers another firing).
+
+If you need parallel mutations of different shapes (e.g. `submit` AND
+`uploadFile` running concurrently), use two mutators with distinct fact
+names — one per shape. v0.1 doesn't support parallel-of-same-shape; the
+behaviour there is "last-write-wins."
+
+## Same-constraint re-fire (`requeue`)
+
+When one handler dispatches another `MUTATE` synchronously, the new
+mutation may stall behind same-flush suppression in Directive's engine.
+Call `ctx.requeue()` inside the handler to opt into a re-fire:
+
+```ts
+const mut = defineMutator<Mutations, MyFacts>({
+  step1: async ({ facts, requeue }) => {
+    facts.step1Done = true;
+    // queue step2:
+    facts.pendingMutation = mutate<Mutations>('step2');
+    requeue(); // explicit — without this, step2 may stall
+  },
+  step2: ({ facts }) => { facts.step2Done = true; },
+});
+```
+
+Most modules don't need `requeue` — the next user-event-driven `MUTATE`
+fires fine. It's specifically for handler-cascades-into-handler.
+
+See [Directive testing § same-constraint re-fire](https://docs.directive.run/testing/chained-pipelines#the-same-constraint-re-fire-stall).
+
+## Type safety
+
+The `MutationMap` generic is the source of truth. Every variant key
+becomes:
+- a possible `kind` value on `pendingMutation`
+- a payload-constrained dispatch via `mutate('key', payload)`
+- a required handler in the map (TypeScript errors if you forget one)
+- a typed `payload` argument inside that handler
+
+There is no runtime variant validation today — the type system catches
+mismatches at the dispatch site, but a malformed `MUTATE` from outside
+TypeScript (e.g. WebSocket frame) will still hit the resolver. If you
+need runtime checks, validate at the boundary before dispatch.
+
+## When NOT to use a mutator
+
+- **One-off events with no error path.** A simple `event.handle('OPEN',
+  (f) => { f.isOpen = true; })` doesn't need this — there's no async
+  work, no rollback, no error fact.
+- **Long-running streams.** Subscriptions, polls, websocket fan-in —
+  these aren't single-shot mutations. Wire them through normal events.
+- **Pure derivations.** If the result is a function of existing facts,
+  use a `derive` instead of a mutator.
+
+The mutator earns its weight when you have **multi-variant async work
+with a discriminator**. That's the 12-instance shape from the migration.
+
+## Auto-cancel on supersede (R1.C `cancellable()`)
+
+For mutations where a fresh dispatch should cancel the prior in-flight
+one — type-ahead search, debounce, throttle, request dedup — wrap
+the handler with `cancellable()`. The wrapped handler receives a
+`signal: AbortSignal` that aborts when superseded or when an
+optional timeout fires:
+
+```ts
+import { defineMutator, cancellable } from '@directive-run/mutator';
+
+const formMutator = defineMutator<MyMutations, MyFacts>({
+  search: cancellable(
+    { supersedeOn: 'self', timeoutMs: 3_000 },
+    async ({ payload, facts, signal }) => {
+      const res = await fetch(`/q?${payload.q}`, { signal });
+      facts.results = await res.json();
+    },
+  ),
+  submit: async ({ payload, facts }) => {
+    // No cancellation — plain handler.
+    facts.values = await deps.submit(payload.values);
+  },
+});
+```
+
+**Two cancellation triggers, both opt-in:**
+
+- `supersedeOn: 'self'` (default) — a new dispatch of the same
+  wrapped handler aborts the prior in-flight invocation. Set
+  `'never'` if parallel runs are fine.
+- `timeoutMs: number` — abort after N ms from invocation start.
+  Default unset (no timeout).
+
+**Test ergonomics:** pass `virtualClock.setTimeout` from
+`@directive-run/core` via the `setTimeout` option to make timeouts
+fire synchronously under `clock.advanceBy(ms)`:
+
+```ts
+import { virtualClock } from '@directive-run/core';
+const clock = virtualClock(0);
+const wrapped = cancellable(
+  { timeoutMs: 1_000, setTimeout: clock.setTimeout },
+  handler,
+);
+// In tests: clock.advanceBy(1_001) fires the timeout deterministically.
+```
+
+**The signal's `reason` carries a `CancelReason`:**
+
+```ts
+type CancelReason =
+  | { kind: 'superseded' }
+  | { kind: 'timeout'; afterMs: number };
+```
+
+Use it inside handlers to distinguish how the cancellation arrived
+(e.g. log a different message for timeouts vs supersession).
+
+## Optimistic updates + rollback
+
+A future `@directive-run/optimistic` package will integrate with this
+one — the planned `ctx.snapshot([keys])` API lets a handler snapshot
+specific facts before mutating, with automatic rollback on throw. Until
+that ships, do snapshots manually inside handlers:
+
+```ts
+submit: async ({ payload, facts, deps }) => {
+  const previous = [...facts.values]; // manual snapshot
+  facts.values = optimisticGuess(payload); // optimistic write
+  try {
+    facts.values = await deps.submit(payload);
+  } catch (err) {
+    facts.values = previous; // rollback
+    throw err; // surface to pendingMutation.error
+  }
+},
+```
+
+## See also
+
+- [Directive core](https://www.npmjs.com/package/@directive-run/core)
+- [Migrating from XState — `pendingAction` pattern](https://docs.directive.run/migrating-from-xstate#the-pendingaction-pattern-12-cycles-confirmed)
+- [Internal events](https://docs.directive.run/patterns/internal-events) — when `status` alone is enough
+- [`MIGRATION_FEEDBACK.md` items 17 + 19](https://github.com/directive-run/directive/blob/main/docs/MIGRATION_FEEDBACK.md)
+
+## License
+
+MIT OR Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var core=require('@directive-run/core');var c=500;function p(e){let n;if(e instanceof Error){let t;try{t=e.message;}catch{t="[mutator: error.message getter threw]";}n=typeof t=="string"?t:g(t);}else typeof e=="string"?n=e:n=g(e);return n.length<=c?n:`${n.slice(0,c-1)}\u2026`}function g(e){try{return String(e)}catch{return "[mutator: unstringifiable error]"}}function T(e){return {facts:{pendingMutation:core.t.object().nullable()},events:{MUTATE:void 0},requirements:{PROCESS_MUTATION:{}},eventHandlers:{MUTATE:(o,r)=>{o.pendingMutation={...r,status:"pending",error:null};}},constraints:{pendingMutation:{when:o=>o.pendingMutation!==null&&o.pendingMutation?.status==="pending",require:{type:"PROCESS_MUTATION"}}},resolvers:{mutationResolver:{requirement:"PROCESS_MUTATION",resolve:async(o,r)=>{let i=r.facts,a=i.pendingMutation;if(a===null)return;i.pendingMutation={...a,status:"running"};let M=Object.prototype.hasOwnProperty.call(e,a.kind)?e[a.kind]:void 0;if(typeof M!="function"){i.pendingMutation={...a,status:"failed",error:p(`[mutator] no handler registered for variant: ${String(a.kind)}`)};return}let f={facts:r.facts,payload:a.payload,requeue:r.requeue??(()=>{})};try{await M(f),i.pendingMutation?.status==="running"&&(i.pendingMutation=null);}catch(y){if(i.pendingMutation?.status!=="running")return;i.pendingMutation={...a,status:"failed",error:p(y)};}}}},initialPendingMutation:null}}function x(e,n){return {kind:e,payload:n??{},status:"pending",error:null}}function k(e,n){let t=e.supersedeOn??"self",u=e.timeoutMs,l=e.setTimeout??v,s;return async d=>{t==="self"&&s!==void 0&&s.abort({kind:"superseded"});let o=new AbortController;s=o;let r;typeof u=="number"&&u>0&&(r=l(()=>{o.abort({kind:"timeout",afterMs:u});},u));try{await n({facts:d.facts,payload:d.payload,requeue:d.requeue,signal:o.signal});}finally{r?.(),s===o&&(s=void 0);}}}function v(e,n){let t=globalThis.setTimeout(e,n);return ()=>globalThis.clearTimeout(t)}exports.cancellable=k;exports.defineMutator=T;exports.mutate=x;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["MAX_ERROR_LEN","truncateError","input","str","raw","safeStringCoerce","value","defineMutator","handlers","t","facts","payload","_req","ctx","factsRef","pending","handler","handlerCtx","err","mutate","kind","cancellable","opts","supersedeOn","timeoutMs","scheduleTimeout","defaultSetTimeout","priorController","controller","cancelTimeout","cb","ms","handle"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @directive-run/mutator\n *\n * Discriminated mutation helper. Collapses the manual `pendingAction`\n * ceremony — fact + event + constraint + resolver — into a typed handler\n * map.\n *\n * Background: across the 55-cycle Minglingo migration, 12 modules ended\n * up with the same shape:\n *   - a nullable `pendingAction` fact holding a discriminated union\n *   - an event that sets it\n *   - a constraint that fires on non-null\n *   - a resolver that switches on the discriminator and clears the fact\n *\n * That's ~50 lines of boilerplate per module times 12 modules. The\n * `defineMutator` helper below contributes all four pieces from a single\n * typed declaration, so a module that uses it spreads the fragments\n * into its `createModule` config and writes only the per-variant handler\n * bodies.\n *\n * @see ../README.md for the full API and a worked example.\n */\n\nimport { t } from \"@directive-run/core\";\n\n/**\n * A keyed map of variant payloads. Each key becomes a discriminator value\n * for the mutation, each value is the payload type for that variant.\n *\n * @example\n * ```ts\n * type MyMutations = {\n *   submit: { values: FormValues };\n *   cancel: {};\n *   retry: { reason: string };\n * };\n * ```\n */\nexport type MutationMap = Record<string, Record<string, unknown>>;\n\n/**\n * The shape of a `pendingMutation` fact while a mutation is queued or\n * running.\n */\nexport type PendingMutation<M extends MutationMap> = {\n  [K in keyof M]: {\n    kind: K;\n    payload: M[K];\n    /**\n     * `pending` — queued, constraint hasn't fired yet.\n     * `running` — handler is in flight.\n     * `failed` — handler threw; constraint stops firing. Caller can\n     *            inspect `error` and dispatch a fresh MUTATE to retry.\n     */\n    status: \"pending\" | \"running\" | \"failed\";\n    /**\n     * Error message from the previous run, if any. Plaintext only —\n     * NEVER render this directly via `dangerouslySetInnerHTML` or\n     * markdown. Truncated to 500 chars to bound XSS surface from\n     * thrown messages that may echo user input.\n     */\n    error: string | null;\n  };\n}[keyof M];\n\n/** Maximum length of a captured error message — bounded to limit XSS surface. */\nconst MAX_ERROR_LEN = 500;\n\n/**\n * Coerce a thrown value to a bounded plaintext string for storage on\n * `pendingMutation.error`. Defends against:\n *   - non-Error throws (`throw \"string\"`, `throw 42`, `throw {}`)\n *   - Errors with non-string `.message` (overridden numeric / Symbol /\n *     buffer); naive `.length` / `.slice` would `TypeError` otherwise\n *   - extremely long messages with attacker-influenced input\n *\n * Returns at most {@link MAX_ERROR_LEN} characters of plaintext.\n * Plaintext rendering is still the only supported path on the\n * consumer side; this is defense in depth, not an XSS sanitizer.\n *\n * (R2 sec M-R2-1.)\n */\nfunction truncateError(input: unknown): string {\n  let str: string;\n  if (input instanceof Error) {\n    // Reading `.message` is wrapped in try/catch because a maliciously\n    // constructed Error subclass may install a throwing getter on\n    // `message`. Without this guard the throw escapes truncateError →\n    // escapes the resolver's catch → propagates uncaught. (R4 backlog.)\n    let raw: unknown;\n    try {\n      raw = input.message;\n    } catch {\n      raw = \"[mutator: error.message getter threw]\";\n    }\n    str = typeof raw === \"string\" ? raw : safeStringCoerce(raw);\n  } else if (typeof input === \"string\") {\n    str = input;\n  } else {\n    str = safeStringCoerce(input);\n  }\n  if (str.length <= MAX_ERROR_LEN) return str;\n  return `${str.slice(0, MAX_ERROR_LEN - 1)}…`;\n}\n\n/** String() may throw for some Symbols + objects with hostile toString. */\nfunction safeStringCoerce(value: unknown): string {\n  try {\n    return String(value);\n  } catch {\n    return \"[mutator: unstringifiable error]\";\n  }\n}\n\n/**\n * Handler context passed to each variant handler.\n *\n * Note: `deps` is NOT in the context. This matches the Directive resolver\n * idiom — close over deps from the outer module-factory scope:\n *\n * ```ts\n * function createFormModule(deps: FormDeps) {\n *   const mut = defineMutator<FormMutations, FormFacts>({\n *     submit: async ({ payload, facts }) => {\n *       facts.values = await deps.submit(payload.values); // ← closure\n *     },\n *   });\n *   return createModule('form', { ... });\n * }\n * ```\n */\nexport interface MutatorHandlerContext<F> {\n  /** Live facts proxy. Reads are cache-tracked; writes invalidate. */\n  facts: F;\n  /**\n   * Trigger a same-constraint re-fire after this handler returns. Useful\n   * when one mutation cascades into another — without `requeue`, the next\n   * mutation would stall behind same-flush suppression.\n   *\n   * @see https://docs.directive.run/testing/chained-pipelines\n   */\n  requeue: () => void;\n}\n\n/**\n * Variant handler body. Receives the typed payload + a context; returns\n * void or a Promise. Throwing is fine — the runtime captures into\n * `pendingMutation.error` before clearing the fact.\n */\nexport type MutationHandler<\n  M extends MutationMap,\n  K extends keyof M,\n  F,\n> = keyof M[K] extends never\n  ? (ctx: MutatorHandlerContext<F>) => void | Promise<void>\n  : (\n      ctx: MutatorHandlerContext<F> & { payload: M[K] },\n    ) => void | Promise<void>;\n\n/**\n * The full handler map. Every variant in `M` MUST have a handler.\n */\nexport type MutationHandlers<M extends MutationMap, F> = {\n  [K in keyof M]: MutationHandler<M, K, F>;\n};\n\n/**\n * The fragments returned by `defineMutator`. Spread each fragment into\n * the matching position of your `createModule` config.\n *\n * @internal Shape documented for type clarity; users typically just\n * spread.\n */\nexport interface MutatorFragments<M extends MutationMap, F> {\n  /** Spread into `schema.facts`. Adds `pendingMutation`. */\n  facts: {\n    pendingMutation: ReturnType<typeof t.object>;\n  };\n  /** Spread into `schema.events`. Adds the `MUTATE` event. */\n  events: {\n    MUTATE: PendingMutation<M>;\n  };\n  /** Spread into `schema.requirements`. Adds `PROCESS_MUTATION`. */\n  requirements: {\n    PROCESS_MUTATION: Record<string, never>;\n  };\n  /** Spread into the `events` field. Sets pendingMutation on MUTATE. */\n  eventHandlers: {\n    MUTATE: (facts: F, payload: PendingMutation<M>) => void;\n  };\n  /** Spread into the `constraints` field. */\n  constraints: {\n    pendingMutation: {\n      when: (facts: F) => boolean;\n      require: { type: \"PROCESS_MUTATION\" };\n    };\n  };\n  /** Spread into the `resolvers` field. */\n  resolvers: {\n    mutationResolver: {\n      requirement: \"PROCESS_MUTATION\";\n      resolve: (\n        req: { type: \"PROCESS_MUTATION\" },\n        ctx: { facts: F },\n      ) => Promise<void>;\n    };\n  };\n  /**\n   * Convenience: the initial value for `pendingMutation`. Set this in\n   * your module's `init` if you don't use `t.X().default(...)` defaults.\n   */\n  initialPendingMutation: null;\n}\n\n/**\n * Define a mutator fragment-set for a given variant map and handlers.\n *\n * @example\n * ```ts\n * type FormMutations = {\n *   submit: { values: FormValues };\n *   cancel: {};\n * };\n *\n * // The second generic is the FACTS type (not deps). Deps are\n * // captured in closure from the surrounding scope, not passed in\n * // through the handler ctx.\n * const formMutator = defineMutator<FormMutations, FormFacts>({\n *   submit: async ({ payload, facts }) => {\n *     facts.values = await deps.submit(payload.values); // deps closes over outer scope\n *   },\n *   cancel: ({ facts }) => { facts.values = []; },\n * });\n *\n * createModule('form', {\n *   schema: {\n *     facts: { ...formMutator.facts, values: t.array<FormValues>() },\n *     events: { ...formMutator.events, REFRESH: {} },\n *     requirements: { ...formMutator.requirements },\n *   },\n *   init: (f) => { f.pendingMutation = null; f.values = []; },\n *   events: {\n *     ...formMutator.eventHandlers,\n *     REFRESH: (f) => { f.values = []; },\n *   },\n *   constraints: { ...formMutator.constraints },\n *   resolvers: { ...formMutator.resolvers },\n * });\n *\n * // Usage:\n * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));\n *\n * // Or, if constructing the payload manually, the discriminator is\n * // `kind` (NOT `type` — `type` collides with Directive's event-name\n * // dispatch convention):\n * sys.events.MUTATE({\n *   kind: 'submit',\n *   payload: { values: ... },\n *   status: 'pending',\n *   error: null,\n * });\n * ```\n *\n * The handler-bound deps are captured at `defineMutator` call time. To\n * inject deps from the caller, wrap `defineMutator` in your module\n * factory:\n *\n * ```ts\n * export function createFormModule(deps: FormDeps) {\n *   const mut = defineMutator<FormMutations, FormFacts>({\n *     submit: async ({ payload, facts }) => {\n *       facts.values = await deps.submit(payload.values);\n *     },\n *     cancel: ({ facts }) => { facts.values = []; },\n *   });\n *   return createModule('form', { ... });\n * }\n * ```\n */\nexport function defineMutator<\n  M extends MutationMap,\n  F = Record<string, unknown>,\n>(handlers: MutationHandlers<M, F>): MutatorFragments<M, F> {\n  type Pending = PendingMutation<M>;\n\n  const facts = {\n    pendingMutation: t.object<Pending>().nullable() as ReturnType<\n      typeof t.object\n    >,\n  } as MutatorFragments<M, F>[\"facts\"];\n\n  // Schema event marker — the runtime uses this for typing and devtools.\n  // Payload validation happens at dispatch time via t-schema check.\n  const events = {\n    MUTATE: undefined as unknown as Pending,\n  } as MutatorFragments<M, F>[\"events\"];\n\n  const requirements = {\n    PROCESS_MUTATION: {} as Record<string, never>,\n  } as MutatorFragments<M, F>[\"requirements\"];\n\n  const eventHandlers = {\n    MUTATE: (facts: F, payload: Pending) => {\n      // Overwrite is intentional — caller is responsible for ordering.\n      // If a previous mutation is mid-flight, the new one queues by\n      // overwriting; the in-flight handler will null the fact when it\n      // completes, then the constraint re-fires for the new one.\n      // (Same as the manual pattern across all 12 audited modules.)\n      (facts as { pendingMutation: Pending | null }).pendingMutation = {\n        ...payload,\n        status: \"pending\",\n        error: null,\n      };\n    },\n  } as MutatorFragments<M, F>[\"eventHandlers\"];\n\n  const constraints = {\n    pendingMutation: {\n      when: (facts: F) =>\n        (facts as { pendingMutation: Pending | null }).pendingMutation !==\n          null &&\n        (facts as { pendingMutation: Pending | null }).pendingMutation\n          ?.status === \"pending\",\n      require: { type: \"PROCESS_MUTATION\" } as const,\n    },\n  } as MutatorFragments<M, F>[\"constraints\"];\n\n  const resolvers = {\n    mutationResolver: {\n      requirement: \"PROCESS_MUTATION\" as const,\n      resolve: async (\n        _req: { type: \"PROCESS_MUTATION\" },\n        ctx: {\n          facts: F;\n          requeue?: () => void;\n        },\n      ) => {\n        const factsRef = ctx.facts as { pendingMutation: Pending | null };\n        const pending = factsRef.pendingMutation;\n        if (pending === null) return;\n\n        // Stamp the in-flight transition with the running status. The\n        // status itself is the supersession marker: only this resolver\n        // ever writes 'running'; the eventHandler always writes\n        // 'pending'. So if a fresh MUTATE arrives mid-flight, the\n        // post-handler check sees status: 'pending' instead of\n        // 'running' and knows to leave the new dispatch alone.\n        // (Sec M5 / DX M2.)\n        factsRef.pendingMutation = { ...pending, status: \"running\" };\n\n        // Prototype-pollution defense: only accept handlers OWNED by\n        // the user-provided map. Without this, dispatching with kind:\n        // 'constructor' / 'toString' / '__proto__' would resolve via\n        // the prototype chain and either crash or invoke an inherited\n        // function with arbitrary payload. (Sec C1.)\n        const ownsHandler = Object.prototype.hasOwnProperty.call(\n          handlers,\n          pending.kind as PropertyKey,\n        );\n        const handler = ownsHandler\n          ? (handlers as Record<string, unknown>)[pending.kind as string]\n          : undefined;\n\n        if (typeof handler !== \"function\") {\n          factsRef.pendingMutation = {\n            ...pending,\n            status: \"failed\",\n            error: truncateError(\n              `[mutator] no handler registered for variant: ${String(\n                pending.kind,\n              )}`,\n            ),\n          };\n          return;\n        }\n\n        const handlerCtx = {\n          facts: ctx.facts,\n          payload: pending.payload,\n          requeue: ctx.requeue ?? (() => {}),\n        };\n\n        try {\n          await (handler as (c: typeof handlerCtx) => Promise<void> | void)(\n            handlerCtx,\n          );\n          // Success: clear the fact ONLY if this resolver's `running`\n          // marker is still live (status === 'running'). If a fresh\n          // MUTATE arrived mid-flight via the eventHandler, the fact\n          // now has status: 'pending' — leave it alone so the next\n          // constraint fire picks it up. (Sec M5 / DX M2.)\n          if (factsRef.pendingMutation?.status === \"running\") {\n            factsRef.pendingMutation = null;\n          }\n        } catch (err) {\n          // Failure: only stamp the error if our running marker is\n          // still live. If a fresh MUTATE arrived mid-flight, the new\n          // dispatch wins; the failed mutation's error is dropped on\n          // the floor (caller wanted to move on anyway). (Sec M5.)\n          if (factsRef.pendingMutation?.status !== \"running\") return;\n          factsRef.pendingMutation = {\n            ...pending,\n            // 'failed' is a distinct status (Sec M6 / Arch C2) — UI can\n            // disambiguate \"still in flight\" from \"stopped on error\".\n            status: \"failed\",\n            // truncateError handles the unknown shape safely — non-Error\n            // throws, non-string Error.message, hostile toString. (R2\n            // sec M-R2-1.)\n            error: truncateError(err),\n          };\n        }\n      },\n    },\n  } as MutatorFragments<M, F>[\"resolvers\"];\n\n  return {\n    facts,\n    events,\n    requirements,\n    eventHandlers,\n    constraints,\n    resolvers,\n    initialPendingMutation: null,\n  };\n}\n\n/**\n * Helper for typed dispatch. Lets the caller construct a mutation payload\n * with full type narrowing — the `kind` field auto-restricts the\n * `payload` shape.\n *\n * @example\n * ```ts\n * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));\n * sys.events.MUTATE(mutate<FormMutations>('cancel'));\n * ```\n */\n// Single type parameter (M) so callers can specialize with\n// `mutate<FormMutations>(...)` without TypeScript demanding the\n// inferred K. TS's strict type-argument rules treat <M, K> as\n// \"supply both or supply neither\" — single-arg call sites failed\n// with \"Expected 2 type arguments, but got 1.\" Single-M form sidesteps\n// that while keeping payload typing tight via the `kind` lookup.\nexport function mutate<M extends MutationMap>(\n  kind: keyof M & string,\n  payload: M[typeof kind],\n): PendingMutation<M>;\nexport function mutate<M extends MutationMap>(\n  kind: keyof M & string,\n): PendingMutation<M>;\nexport function mutate<M extends MutationMap>(\n  kind: keyof M & string,\n  payload?: M[typeof kind],\n): PendingMutation<M> {\n  return {\n    kind,\n    payload: (payload ?? {}) as M[typeof kind],\n    status: \"pending\",\n    error: null,\n  } as PendingMutation<M>;\n}\n\n// ============================================================================\n// cancellable() — auto-cancel-on-supersede (R1.C v0.1)\n// ============================================================================\n\n/**\n * Options for {@link cancellable}.\n */\nexport interface CancellableOptions {\n  /**\n   * When to fire the AbortSignal that the wrapped handler receives.\n   *\n   * - `'self'` (default): a new dispatch of the SAME handler aborts the\n   *   prior in-flight invocation. The classic \"cancel previous on new\n   *   keystroke\" pattern.\n   * - `'never'`: only the timeout fires the signal; new dispatches do\n   *   NOT abort prior ones. Useful when you want a hard timeout but\n   *   parallel runs are fine.\n   */\n  supersedeOn?: \"self\" | \"never\";\n\n  /**\n   * Maximum ms a handler may run before its signal is aborted. Counted\n   * from the start of THIS invocation. Combine with `realClock` for\n   * production or pass a `setTimeout` shim for deterministic testing.\n   */\n  timeoutMs?: number;\n\n  /**\n   * Optional `setTimeout` injection. Defaults to `globalThis.setTimeout`.\n   * For deterministic tests, pass `virtualClock.setTimeout` from\n   * `@directive-run/core` so the timeout fires under\n   * `clock.advanceBy()` instead of wall-clock real time.\n   *\n   * @example\n   * ```ts\n   * import { virtualClock } from '@directive-run/core';\n   * const clock = virtualClock(0);\n   * cancellable({ timeoutMs: 1_000, setTimeout: clock.setTimeout }, handler);\n   * ```\n   */\n  setTimeout?: (cb: () => void, ms: number) => () => void;\n}\n\n/**\n * Handler context augmented with a cancellation signal.\n */\nexport interface CancellableHandlerContext<F, P> {\n  facts: F;\n  payload: P;\n  /** Aborts when a new dispatch supersedes this one OR the timeout fires. */\n  signal: AbortSignal;\n  requeue: () => void;\n}\n\n/**\n * Reason a cancellable handler's signal aborted. Stamped on\n * `signal.reason` so the handler can disambiguate.\n */\nexport type CancelReason =\n  | { kind: \"superseded\" }\n  | { kind: \"timeout\"; afterMs: number };\n\n/**\n * Wrap a mutator handler with auto-cancellation. The wrapped handler\n * receives an extra `signal: AbortSignal` in its context. Use the\n * signal to short-circuit awaitable work — pass it to `fetch(url, {\n * signal })`, watch it inside long-running loops, etc.\n *\n * Two cancellation triggers, both opt-in via {@link CancellableOptions}:\n *\n *   1. **Supersession** (default `supersedeOn: 'self'`): when a new\n *      dispatch of the same wrapped handler arrives while a prior\n *      invocation is still running, the prior signal aborts.\n *   2. **Timeout** (default `timeoutMs: undefined`, meaning no timeout):\n *      after `timeoutMs` ms from invocation start, the signal aborts.\n *\n * If a handler's signal aborts, the handler should observe the abort\n * (via `signal.aborted` or the AbortError-throwing helpers) and\n * return promptly. The signal's `reason` carries a {@link CancelReason}\n * disambiguating which trigger fired.\n *\n * Compose with {@link defineMutator} by using `cancellable()` directly\n * in the handler map:\n *\n * @example\n * ```ts\n * import { defineMutator, cancellable } from '@directive-run/mutator';\n *\n * const formMutator = defineMutator<MyMutations, MyFacts>({\n *   search: cancellable(\n *     { supersedeOn: 'self', timeoutMs: 3_000 },\n *     async ({ payload, facts, signal }) => {\n *       const res = await fetch(`/q?${payload.q}`, { signal });\n *       facts.results = await res.json();\n *     },\n *   ),\n *   submit: async ({ payload, facts }) => {\n *     // No cancellation needed for submit — plain handler.\n *     facts.values = await deps.submit(payload.values);\n *   },\n * });\n * ```\n *\n * **Idempotency note.** The wrapped handler stays a regular\n * `MutationHandler<M, K, F>` from the mutator's perspective. The\n * supersession registry is closure-scoped per `cancellable()` call —\n * two separate `cancellable(...)` HOCs around different handlers do\n * NOT cancel each other.\n *\n * **Test ergonomics.** Pass `virtualClock.setTimeout` via the\n * `setTimeout` option to make timeouts deterministic under\n * `clock.advanceBy(ms)`. Without that, timeouts use wall-clock\n * `globalThis.setTimeout` and are real-time.\n */\nexport function cancellable<F, P>(\n  opts: CancellableOptions,\n  handler: (ctx: CancellableHandlerContext<F, P>) => Promise<void> | void,\n): (ctx: { facts: F; payload: P; requeue: () => void }) => Promise<void> {\n  const supersedeOn = opts.supersedeOn ?? \"self\";\n  const timeoutMs = opts.timeoutMs;\n  const scheduleTimeout = opts.setTimeout ?? defaultSetTimeout;\n\n  // Closure-scoped supersession slot — one entry for the wrapped\n  // handler. When a new invocation arrives, the prior entry's\n  // controller aborts before the new one starts.\n  let priorController: AbortController | undefined;\n\n  return async (ctx: { facts: F; payload: P; requeue: () => void }) => {\n    // Supersession: abort the prior in-flight invocation, if any.\n    if (supersedeOn === \"self\" && priorController !== undefined) {\n      priorController.abort({ kind: \"superseded\" } satisfies CancelReason);\n    }\n\n    const controller = new AbortController();\n    priorController = controller;\n\n    // Timeout: schedule an abort after `timeoutMs`. The cancel handle\n    // returned by `scheduleTimeout` lets us clear the timer if the\n    // handler completes first (saves leaking timers under a barrage\n    // of dispatches).\n    let cancelTimeout: (() => void) | undefined;\n    if (typeof timeoutMs === \"number\" && timeoutMs > 0) {\n      cancelTimeout = scheduleTimeout(() => {\n        controller.abort({ kind: \"timeout\", afterMs: timeoutMs } satisfies CancelReason);\n      }, timeoutMs);\n    }\n\n    try {\n      await handler({\n        facts: ctx.facts,\n        payload: ctx.payload,\n        requeue: ctx.requeue,\n        signal: controller.signal,\n      });\n    } finally {\n      // Clean up: clear the timeout (if it hasn't fired) and release\n      // the supersession slot if it still belongs to this invocation.\n      cancelTimeout?.();\n      if (priorController === controller) {\n        priorController = undefined;\n      }\n    }\n  };\n}\n\n/**\n * Default `setTimeout` shim — wraps `globalThis.setTimeout` to match\n * the cancel-handle signature `cancellable()` expects.\n */\nfunction defaultSetTimeout(cb: () => void, ms: number): () => void {\n  const handle = globalThis.setTimeout(cb, ms);\n  return () => globalThis.clearTimeout(handle);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,350 @@
+import { t } from '@directive-run/core';
+
+/**
+ * @directive-run/mutator
+ *
+ * Discriminated mutation helper. Collapses the manual `pendingAction`
+ * ceremony — fact + event + constraint + resolver — into a typed handler
+ * map.
+ *
+ * Background: across the 55-cycle Minglingo migration, 12 modules ended
+ * up with the same shape:
+ *   - a nullable `pendingAction` fact holding a discriminated union
+ *   - an event that sets it
+ *   - a constraint that fires on non-null
+ *   - a resolver that switches on the discriminator and clears the fact
+ *
+ * That's ~50 lines of boilerplate per module times 12 modules. The
+ * `defineMutator` helper below contributes all four pieces from a single
+ * typed declaration, so a module that uses it spreads the fragments
+ * into its `createModule` config and writes only the per-variant handler
+ * bodies.
+ *
+ * @see ../README.md for the full API and a worked example.
+ */
+
+/**
+ * A keyed map of variant payloads. Each key becomes a discriminator value
+ * for the mutation, each value is the payload type for that variant.
+ *
+ * @example
+ * ```ts
+ * type MyMutations = {
+ *   submit: { values: FormValues };
+ *   cancel: {};
+ *   retry: { reason: string };
+ * };
+ * ```
+ */
+type MutationMap = Record<string, Record<string, unknown>>;
+/**
+ * The shape of a `pendingMutation` fact while a mutation is queued or
+ * running.
+ */
+type PendingMutation<M extends MutationMap> = {
+    [K in keyof M]: {
+        kind: K;
+        payload: M[K];
+        /**
+         * `pending` — queued, constraint hasn't fired yet.
+         * `running` — handler is in flight.
+         * `failed` — handler threw; constraint stops firing. Caller can
+         *            inspect `error` and dispatch a fresh MUTATE to retry.
+         */
+        status: "pending" | "running" | "failed";
+        /**
+         * Error message from the previous run, if any. Plaintext only —
+         * NEVER render this directly via `dangerouslySetInnerHTML` or
+         * markdown. Truncated to 500 chars to bound XSS surface from
+         * thrown messages that may echo user input.
+         */
+        error: string | null;
+    };
+}[keyof M];
+/**
+ * Handler context passed to each variant handler.
+ *
+ * Note: `deps` is NOT in the context. This matches the Directive resolver
+ * idiom — close over deps from the outer module-factory scope:
+ *
+ * ```ts
+ * function createFormModule(deps: FormDeps) {
+ *   const mut = defineMutator<FormMutations, FormFacts>({
+ *     submit: async ({ payload, facts }) => {
+ *       facts.values = await deps.submit(payload.values); // ← closure
+ *     },
+ *   });
+ *   return createModule('form', { ... });
+ * }
+ * ```
+ */
+interface MutatorHandlerContext<F> {
+    /** Live facts proxy. Reads are cache-tracked; writes invalidate. */
+    facts: F;
+    /**
+     * Trigger a same-constraint re-fire after this handler returns. Useful
+     * when one mutation cascades into another — without `requeue`, the next
+     * mutation would stall behind same-flush suppression.
+     *
+     * @see https://docs.directive.run/testing/chained-pipelines
+     */
+    requeue: () => void;
+}
+/**
+ * Variant handler body. Receives the typed payload + a context; returns
+ * void or a Promise. Throwing is fine — the runtime captures into
+ * `pendingMutation.error` before clearing the fact.
+ */
+type MutationHandler<M extends MutationMap, K extends keyof M, F> = keyof M[K] extends never ? (ctx: MutatorHandlerContext<F>) => void | Promise<void> : (ctx: MutatorHandlerContext<F> & {
+    payload: M[K];
+}) => void | Promise<void>;
+/**
+ * The full handler map. Every variant in `M` MUST have a handler.
+ */
+type MutationHandlers<M extends MutationMap, F> = {
+    [K in keyof M]: MutationHandler<M, K, F>;
+};
+/**
+ * The fragments returned by `defineMutator`. Spread each fragment into
+ * the matching position of your `createModule` config.
+ *
+ * @internal Shape documented for type clarity; users typically just
+ * spread.
+ */
+interface MutatorFragments<M extends MutationMap, F> {
+    /** Spread into `schema.facts`. Adds `pendingMutation`. */
+    facts: {
+        pendingMutation: ReturnType<typeof t.object>;
+    };
+    /** Spread into `schema.events`. Adds the `MUTATE` event. */
+    events: {
+        MUTATE: PendingMutation<M>;
+    };
+    /** Spread into `schema.requirements`. Adds `PROCESS_MUTATION`. */
+    requirements: {
+        PROCESS_MUTATION: Record<string, never>;
+    };
+    /** Spread into the `events` field. Sets pendingMutation on MUTATE. */
+    eventHandlers: {
+        MUTATE: (facts: F, payload: PendingMutation<M>) => void;
+    };
+    /** Spread into the `constraints` field. */
+    constraints: {
+        pendingMutation: {
+            when: (facts: F) => boolean;
+            require: {
+                type: "PROCESS_MUTATION";
+            };
+        };
+    };
+    /** Spread into the `resolvers` field. */
+    resolvers: {
+        mutationResolver: {
+            requirement: "PROCESS_MUTATION";
+            resolve: (req: {
+                type: "PROCESS_MUTATION";
+            }, ctx: {
+                facts: F;
+            }) => Promise<void>;
+        };
+    };
+    /**
+     * Convenience: the initial value for `pendingMutation`. Set this in
+     * your module's `init` if you don't use `t.X().default(...)` defaults.
+     */
+    initialPendingMutation: null;
+}
+/**
+ * Define a mutator fragment-set for a given variant map and handlers.
+ *
+ * @example
+ * ```ts
+ * type FormMutations = {
+ *   submit: { values: FormValues };
+ *   cancel: {};
+ * };
+ *
+ * // The second generic is the FACTS type (not deps). Deps are
+ * // captured in closure from the surrounding scope, not passed in
+ * // through the handler ctx.
+ * const formMutator = defineMutator<FormMutations, FormFacts>({
+ *   submit: async ({ payload, facts }) => {
+ *     facts.values = await deps.submit(payload.values); // deps closes over outer scope
+ *   },
+ *   cancel: ({ facts }) => { facts.values = []; },
+ * });
+ *
+ * createModule('form', {
+ *   schema: {
+ *     facts: { ...formMutator.facts, values: t.array<FormValues>() },
+ *     events: { ...formMutator.events, REFRESH: {} },
+ *     requirements: { ...formMutator.requirements },
+ *   },
+ *   init: (f) => { f.pendingMutation = null; f.values = []; },
+ *   events: {
+ *     ...formMutator.eventHandlers,
+ *     REFRESH: (f) => { f.values = []; },
+ *   },
+ *   constraints: { ...formMutator.constraints },
+ *   resolvers: { ...formMutator.resolvers },
+ * });
+ *
+ * // Usage:
+ * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));
+ *
+ * // Or, if constructing the payload manually, the discriminator is
+ * // `kind` (NOT `type` — `type` collides with Directive's event-name
+ * // dispatch convention):
+ * sys.events.MUTATE({
+ *   kind: 'submit',
+ *   payload: { values: ... },
+ *   status: 'pending',
+ *   error: null,
+ * });
+ * ```
+ *
+ * The handler-bound deps are captured at `defineMutator` call time. To
+ * inject deps from the caller, wrap `defineMutator` in your module
+ * factory:
+ *
+ * ```ts
+ * export function createFormModule(deps: FormDeps) {
+ *   const mut = defineMutator<FormMutations, FormFacts>({
+ *     submit: async ({ payload, facts }) => {
+ *       facts.values = await deps.submit(payload.values);
+ *     },
+ *     cancel: ({ facts }) => { facts.values = []; },
+ *   });
+ *   return createModule('form', { ... });
+ * }
+ * ```
+ */
+declare function defineMutator<M extends MutationMap, F = Record<string, unknown>>(handlers: MutationHandlers<M, F>): MutatorFragments<M, F>;
+/**
+ * Helper for typed dispatch. Lets the caller construct a mutation payload
+ * with full type narrowing — the `kind` field auto-restricts the
+ * `payload` shape.
+ *
+ * @example
+ * ```ts
+ * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));
+ * sys.events.MUTATE(mutate<FormMutations>('cancel'));
+ * ```
+ */
+declare function mutate<M extends MutationMap>(kind: keyof M & string, payload: M[typeof kind]): PendingMutation<M>;
+declare function mutate<M extends MutationMap>(kind: keyof M & string): PendingMutation<M>;
+/**
+ * Options for {@link cancellable}.
+ */
+interface CancellableOptions {
+    /**
+     * When to fire the AbortSignal that the wrapped handler receives.
+     *
+     * - `'self'` (default): a new dispatch of the SAME handler aborts the
+     *   prior in-flight invocation. The classic "cancel previous on new
+     *   keystroke" pattern.
+     * - `'never'`: only the timeout fires the signal; new dispatches do
+     *   NOT abort prior ones. Useful when you want a hard timeout but
+     *   parallel runs are fine.
+     */
+    supersedeOn?: "self" | "never";
+    /**
+     * Maximum ms a handler may run before its signal is aborted. Counted
+     * from the start of THIS invocation. Combine with `realClock` for
+     * production or pass a `setTimeout` shim for deterministic testing.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional `setTimeout` injection. Defaults to `globalThis.setTimeout`.
+     * For deterministic tests, pass `virtualClock.setTimeout` from
+     * `@directive-run/core` so the timeout fires under
+     * `clock.advanceBy()` instead of wall-clock real time.
+     *
+     * @example
+     * ```ts
+     * import { virtualClock } from '@directive-run/core';
+     * const clock = virtualClock(0);
+     * cancellable({ timeoutMs: 1_000, setTimeout: clock.setTimeout }, handler);
+     * ```
+     */
+    setTimeout?: (cb: () => void, ms: number) => () => void;
+}
+/**
+ * Handler context augmented with a cancellation signal.
+ */
+interface CancellableHandlerContext<F, P> {
+    facts: F;
+    payload: P;
+    /** Aborts when a new dispatch supersedes this one OR the timeout fires. */
+    signal: AbortSignal;
+    requeue: () => void;
+}
+/**
+ * Reason a cancellable handler's signal aborted. Stamped on
+ * `signal.reason` so the handler can disambiguate.
+ */
+type CancelReason = {
+    kind: "superseded";
+} | {
+    kind: "timeout";
+    afterMs: number;
+};
+/**
+ * Wrap a mutator handler with auto-cancellation. The wrapped handler
+ * receives an extra `signal: AbortSignal` in its context. Use the
+ * signal to short-circuit awaitable work — pass it to `fetch(url, {
+ * signal })`, watch it inside long-running loops, etc.
+ *
+ * Two cancellation triggers, both opt-in via {@link CancellableOptions}:
+ *
+ *   1. **Supersession** (default `supersedeOn: 'self'`): when a new
+ *      dispatch of the same wrapped handler arrives while a prior
+ *      invocation is still running, the prior signal aborts.
+ *   2. **Timeout** (default `timeoutMs: undefined`, meaning no timeout):
+ *      after `timeoutMs` ms from invocation start, the signal aborts.
+ *
+ * If a handler's signal aborts, the handler should observe the abort
+ * (via `signal.aborted` or the AbortError-throwing helpers) and
+ * return promptly. The signal's `reason` carries a {@link CancelReason}
+ * disambiguating which trigger fired.
+ *
+ * Compose with {@link defineMutator} by using `cancellable()` directly
+ * in the handler map:
+ *
+ * @example
+ * ```ts
+ * import { defineMutator, cancellable } from '@directive-run/mutator';
+ *
+ * const formMutator = defineMutator<MyMutations, MyFacts>({
+ *   search: cancellable(
+ *     { supersedeOn: 'self', timeoutMs: 3_000 },
+ *     async ({ payload, facts, signal }) => {
+ *       const res = await fetch(`/q?${payload.q}`, { signal });
+ *       facts.results = await res.json();
+ *     },
+ *   ),
+ *   submit: async ({ payload, facts }) => {
+ *     // No cancellation needed for submit — plain handler.
+ *     facts.values = await deps.submit(payload.values);
+ *   },
+ * });
+ * ```
+ *
+ * **Idempotency note.** The wrapped handler stays a regular
+ * `MutationHandler<M, K, F>` from the mutator's perspective. The
+ * supersession registry is closure-scoped per `cancellable()` call —
+ * two separate `cancellable(...)` HOCs around different handlers do
+ * NOT cancel each other.
+ *
+ * **Test ergonomics.** Pass `virtualClock.setTimeout` via the
+ * `setTimeout` option to make timeouts deterministic under
+ * `clock.advanceBy(ms)`. Without that, timeouts use wall-clock
+ * `globalThis.setTimeout` and are real-time.
+ */
+declare function cancellable<F, P>(opts: CancellableOptions, handler: (ctx: CancellableHandlerContext<F, P>) => Promise<void> | void): (ctx: {
+    facts: F;
+    payload: P;
+    requeue: () => void;
+}) => Promise<void>;
+
+export { type CancelReason, type CancellableHandlerContext, type CancellableOptions, type MutationHandler, type MutationHandlers, type MutationMap, type MutatorFragments, type MutatorHandlerContext, type PendingMutation, cancellable, defineMutator, mutate };

package/dist/index.d.ts

@@ -0,0 +1,350 @@
+import { t } from '@directive-run/core';
+
+/**
+ * @directive-run/mutator
+ *
+ * Discriminated mutation helper. Collapses the manual `pendingAction`
+ * ceremony — fact + event + constraint + resolver — into a typed handler
+ * map.
+ *
+ * Background: across the 55-cycle Minglingo migration, 12 modules ended
+ * up with the same shape:
+ *   - a nullable `pendingAction` fact holding a discriminated union
+ *   - an event that sets it
+ *   - a constraint that fires on non-null
+ *   - a resolver that switches on the discriminator and clears the fact
+ *
+ * That's ~50 lines of boilerplate per module times 12 modules. The
+ * `defineMutator` helper below contributes all four pieces from a single
+ * typed declaration, so a module that uses it spreads the fragments
+ * into its `createModule` config and writes only the per-variant handler
+ * bodies.
+ *
+ * @see ../README.md for the full API and a worked example.
+ */
+
+/**
+ * A keyed map of variant payloads. Each key becomes a discriminator value
+ * for the mutation, each value is the payload type for that variant.
+ *
+ * @example
+ * ```ts
+ * type MyMutations = {
+ *   submit: { values: FormValues };
+ *   cancel: {};
+ *   retry: { reason: string };
+ * };
+ * ```
+ */
+type MutationMap = Record<string, Record<string, unknown>>;
+/**
+ * The shape of a `pendingMutation` fact while a mutation is queued or
+ * running.
+ */
+type PendingMutation<M extends MutationMap> = {
+    [K in keyof M]: {
+        kind: K;
+        payload: M[K];
+        /**
+         * `pending` — queued, constraint hasn't fired yet.
+         * `running` — handler is in flight.
+         * `failed` — handler threw; constraint stops firing. Caller can
+         *            inspect `error` and dispatch a fresh MUTATE to retry.
+         */
+        status: "pending" | "running" | "failed";
+        /**
+         * Error message from the previous run, if any. Plaintext only —
+         * NEVER render this directly via `dangerouslySetInnerHTML` or
+         * markdown. Truncated to 500 chars to bound XSS surface from
+         * thrown messages that may echo user input.
+         */
+        error: string | null;
+    };
+}[keyof M];
+/**
+ * Handler context passed to each variant handler.
+ *
+ * Note: `deps` is NOT in the context. This matches the Directive resolver
+ * idiom — close over deps from the outer module-factory scope:
+ *
+ * ```ts
+ * function createFormModule(deps: FormDeps) {
+ *   const mut = defineMutator<FormMutations, FormFacts>({
+ *     submit: async ({ payload, facts }) => {
+ *       facts.values = await deps.submit(payload.values); // ← closure
+ *     },
+ *   });
+ *   return createModule('form', { ... });
+ * }
+ * ```
+ */
+interface MutatorHandlerContext<F> {
+    /** Live facts proxy. Reads are cache-tracked; writes invalidate. */
+    facts: F;
+    /**
+     * Trigger a same-constraint re-fire after this handler returns. Useful
+     * when one mutation cascades into another — without `requeue`, the next
+     * mutation would stall behind same-flush suppression.
+     *
+     * @see https://docs.directive.run/testing/chained-pipelines
+     */
+    requeue: () => void;
+}
+/**
+ * Variant handler body. Receives the typed payload + a context; returns
+ * void or a Promise. Throwing is fine — the runtime captures into
+ * `pendingMutation.error` before clearing the fact.
+ */
+type MutationHandler<M extends MutationMap, K extends keyof M, F> = keyof M[K] extends never ? (ctx: MutatorHandlerContext<F>) => void | Promise<void> : (ctx: MutatorHandlerContext<F> & {
+    payload: M[K];
+}) => void | Promise<void>;
+/**
+ * The full handler map. Every variant in `M` MUST have a handler.
+ */
+type MutationHandlers<M extends MutationMap, F> = {
+    [K in keyof M]: MutationHandler<M, K, F>;
+};
+/**
+ * The fragments returned by `defineMutator`. Spread each fragment into
+ * the matching position of your `createModule` config.
+ *
+ * @internal Shape documented for type clarity; users typically just
+ * spread.
+ */
+interface MutatorFragments<M extends MutationMap, F> {
+    /** Spread into `schema.facts`. Adds `pendingMutation`. */
+    facts: {
+        pendingMutation: ReturnType<typeof t.object>;
+    };
+    /** Spread into `schema.events`. Adds the `MUTATE` event. */
+    events: {
+        MUTATE: PendingMutation<M>;
+    };
+    /** Spread into `schema.requirements`. Adds `PROCESS_MUTATION`. */
+    requirements: {
+        PROCESS_MUTATION: Record<string, never>;
+    };
+    /** Spread into the `events` field. Sets pendingMutation on MUTATE. */
+    eventHandlers: {
+        MUTATE: (facts: F, payload: PendingMutation<M>) => void;
+    };
+    /** Spread into the `constraints` field. */
+    constraints: {
+        pendingMutation: {
+            when: (facts: F) => boolean;
+            require: {
+                type: "PROCESS_MUTATION";
+            };
+        };
+    };
+    /** Spread into the `resolvers` field. */
+    resolvers: {
+        mutationResolver: {
+            requirement: "PROCESS_MUTATION";
+            resolve: (req: {
+                type: "PROCESS_MUTATION";
+            }, ctx: {
+                facts: F;
+            }) => Promise<void>;
+        };
+    };
+    /**
+     * Convenience: the initial value for `pendingMutation`. Set this in
+     * your module's `init` if you don't use `t.X().default(...)` defaults.
+     */
+    initialPendingMutation: null;
+}
+/**
+ * Define a mutator fragment-set for a given variant map and handlers.
+ *
+ * @example
+ * ```ts
+ * type FormMutations = {
+ *   submit: { values: FormValues };
+ *   cancel: {};
+ * };
+ *
+ * // The second generic is the FACTS type (not deps). Deps are
+ * // captured in closure from the surrounding scope, not passed in
+ * // through the handler ctx.
+ * const formMutator = defineMutator<FormMutations, FormFacts>({
+ *   submit: async ({ payload, facts }) => {
+ *     facts.values = await deps.submit(payload.values); // deps closes over outer scope
+ *   },
+ *   cancel: ({ facts }) => { facts.values = []; },
+ * });
+ *
+ * createModule('form', {
+ *   schema: {
+ *     facts: { ...formMutator.facts, values: t.array<FormValues>() },
+ *     events: { ...formMutator.events, REFRESH: {} },
+ *     requirements: { ...formMutator.requirements },
+ *   },
+ *   init: (f) => { f.pendingMutation = null; f.values = []; },
+ *   events: {
+ *     ...formMutator.eventHandlers,
+ *     REFRESH: (f) => { f.values = []; },
+ *   },
+ *   constraints: { ...formMutator.constraints },
+ *   resolvers: { ...formMutator.resolvers },
+ * });
+ *
+ * // Usage:
+ * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));
+ *
+ * // Or, if constructing the payload manually, the discriminator is
+ * // `kind` (NOT `type` — `type` collides with Directive's event-name
+ * // dispatch convention):
+ * sys.events.MUTATE({
+ *   kind: 'submit',
+ *   payload: { values: ... },
+ *   status: 'pending',
+ *   error: null,
+ * });
+ * ```
+ *
+ * The handler-bound deps are captured at `defineMutator` call time. To
+ * inject deps from the caller, wrap `defineMutator` in your module
+ * factory:
+ *
+ * ```ts
+ * export function createFormModule(deps: FormDeps) {
+ *   const mut = defineMutator<FormMutations, FormFacts>({
+ *     submit: async ({ payload, facts }) => {
+ *       facts.values = await deps.submit(payload.values);
+ *     },
+ *     cancel: ({ facts }) => { facts.values = []; },
+ *   });
+ *   return createModule('form', { ... });
+ * }
+ * ```
+ */
+declare function defineMutator<M extends MutationMap, F = Record<string, unknown>>(handlers: MutationHandlers<M, F>): MutatorFragments<M, F>;
+/**
+ * Helper for typed dispatch. Lets the caller construct a mutation payload
+ * with full type narrowing — the `kind` field auto-restricts the
+ * `payload` shape.
+ *
+ * @example
+ * ```ts
+ * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));
+ * sys.events.MUTATE(mutate<FormMutations>('cancel'));
+ * ```
+ */
+declare function mutate<M extends MutationMap>(kind: keyof M & string, payload: M[typeof kind]): PendingMutation<M>;
+declare function mutate<M extends MutationMap>(kind: keyof M & string): PendingMutation<M>;
+/**
+ * Options for {@link cancellable}.
+ */
+interface CancellableOptions {
+    /**
+     * When to fire the AbortSignal that the wrapped handler receives.
+     *
+     * - `'self'` (default): a new dispatch of the SAME handler aborts the
+     *   prior in-flight invocation. The classic "cancel previous on new
+     *   keystroke" pattern.
+     * - `'never'`: only the timeout fires the signal; new dispatches do
+     *   NOT abort prior ones. Useful when you want a hard timeout but
+     *   parallel runs are fine.
+     */
+    supersedeOn?: "self" | "never";
+    /**
+     * Maximum ms a handler may run before its signal is aborted. Counted
+     * from the start of THIS invocation. Combine with `realClock` for
+     * production or pass a `setTimeout` shim for deterministic testing.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional `setTimeout` injection. Defaults to `globalThis.setTimeout`.
+     * For deterministic tests, pass `virtualClock.setTimeout` from
+     * `@directive-run/core` so the timeout fires under
+     * `clock.advanceBy()` instead of wall-clock real time.
+     *
+     * @example
+     * ```ts
+     * import { virtualClock } from '@directive-run/core';
+     * const clock = virtualClock(0);
+     * cancellable({ timeoutMs: 1_000, setTimeout: clock.setTimeout }, handler);
+     * ```
+     */
+    setTimeout?: (cb: () => void, ms: number) => () => void;
+}
+/**
+ * Handler context augmented with a cancellation signal.
+ */
+interface CancellableHandlerContext<F, P> {
+    facts: F;
+    payload: P;
+    /** Aborts when a new dispatch supersedes this one OR the timeout fires. */
+    signal: AbortSignal;
+    requeue: () => void;
+}
+/**
+ * Reason a cancellable handler's signal aborted. Stamped on
+ * `signal.reason` so the handler can disambiguate.
+ */
+type CancelReason = {
+    kind: "superseded";
+} | {
+    kind: "timeout";
+    afterMs: number;
+};
+/**
+ * Wrap a mutator handler with auto-cancellation. The wrapped handler
+ * receives an extra `signal: AbortSignal` in its context. Use the
+ * signal to short-circuit awaitable work — pass it to `fetch(url, {
+ * signal })`, watch it inside long-running loops, etc.
+ *
+ * Two cancellation triggers, both opt-in via {@link CancellableOptions}:
+ *
+ *   1. **Supersession** (default `supersedeOn: 'self'`): when a new
+ *      dispatch of the same wrapped handler arrives while a prior
+ *      invocation is still running, the prior signal aborts.
+ *   2. **Timeout** (default `timeoutMs: undefined`, meaning no timeout):
+ *      after `timeoutMs` ms from invocation start, the signal aborts.
+ *
+ * If a handler's signal aborts, the handler should observe the abort
+ * (via `signal.aborted` or the AbortError-throwing helpers) and
+ * return promptly. The signal's `reason` carries a {@link CancelReason}
+ * disambiguating which trigger fired.
+ *
+ * Compose with {@link defineMutator} by using `cancellable()` directly
+ * in the handler map:
+ *
+ * @example
+ * ```ts
+ * import { defineMutator, cancellable } from '@directive-run/mutator';
+ *
+ * const formMutator = defineMutator<MyMutations, MyFacts>({
+ *   search: cancellable(
+ *     { supersedeOn: 'self', timeoutMs: 3_000 },
+ *     async ({ payload, facts, signal }) => {
+ *       const res = await fetch(`/q?${payload.q}`, { signal });
+ *       facts.results = await res.json();
+ *     },
+ *   ),
+ *   submit: async ({ payload, facts }) => {
+ *     // No cancellation needed for submit — plain handler.
+ *     facts.values = await deps.submit(payload.values);
+ *   },
+ * });
+ * ```
+ *
+ * **Idempotency note.** The wrapped handler stays a regular
+ * `MutationHandler<M, K, F>` from the mutator's perspective. The
+ * supersession registry is closure-scoped per `cancellable()` call —
+ * two separate `cancellable(...)` HOCs around different handlers do
+ * NOT cancel each other.
+ *
+ * **Test ergonomics.** Pass `virtualClock.setTimeout` via the
+ * `setTimeout` option to make timeouts deterministic under
+ * `clock.advanceBy(ms)`. Without that, timeouts use wall-clock
+ * `globalThis.setTimeout` and are real-time.
+ */
+declare function cancellable<F, P>(opts: CancellableOptions, handler: (ctx: CancellableHandlerContext<F, P>) => Promise<void> | void): (ctx: {
+    facts: F;
+    payload: P;
+    requeue: () => void;
+}) => Promise<void>;
+
+export { type CancelReason, type CancellableHandlerContext, type CancellableOptions, type MutationHandler, type MutationHandlers, type MutationMap, type MutatorFragments, type MutatorHandlerContext, type PendingMutation, cancellable, defineMutator, mutate };

package/dist/index.js

@@ -0,0 +1,2 @@
+import {t}from'@directive-run/core';var c=500;function p(e){let n;if(e instanceof Error){let t;try{t=e.message;}catch{t="[mutator: error.message getter threw]";}n=typeof t=="string"?t:g(t);}else typeof e=="string"?n=e:n=g(e);return n.length<=c?n:`${n.slice(0,c-1)}\u2026`}function g(e){try{return String(e)}catch{return "[mutator: unstringifiable error]"}}function T(e){return {facts:{pendingMutation:t.object().nullable()},events:{MUTATE:void 0},requirements:{PROCESS_MUTATION:{}},eventHandlers:{MUTATE:(o,r)=>{o.pendingMutation={...r,status:"pending",error:null};}},constraints:{pendingMutation:{when:o=>o.pendingMutation!==null&&o.pendingMutation?.status==="pending",require:{type:"PROCESS_MUTATION"}}},resolvers:{mutationResolver:{requirement:"PROCESS_MUTATION",resolve:async(o,r)=>{let i=r.facts,a=i.pendingMutation;if(a===null)return;i.pendingMutation={...a,status:"running"};let M=Object.prototype.hasOwnProperty.call(e,a.kind)?e[a.kind]:void 0;if(typeof M!="function"){i.pendingMutation={...a,status:"failed",error:p(`[mutator] no handler registered for variant: ${String(a.kind)}`)};return}let f={facts:r.facts,payload:a.payload,requeue:r.requeue??(()=>{})};try{await M(f),i.pendingMutation?.status==="running"&&(i.pendingMutation=null);}catch(y){if(i.pendingMutation?.status!=="running")return;i.pendingMutation={...a,status:"failed",error:p(y)};}}}},initialPendingMutation:null}}function x(e,n){return {kind:e,payload:n??{},status:"pending",error:null}}function k(e,n){let t=e.supersedeOn??"self",u=e.timeoutMs,l=e.setTimeout??v,s;return async d=>{t==="self"&&s!==void 0&&s.abort({kind:"superseded"});let o=new AbortController;s=o;let r;typeof u=="number"&&u>0&&(r=l(()=>{o.abort({kind:"timeout",afterMs:u});},u));try{await n({facts:d.facts,payload:d.payload,requeue:d.requeue,signal:o.signal});}finally{r?.(),s===o&&(s=void 0);}}}function v(e,n){let t=globalThis.setTimeout(e,n);return ()=>globalThis.clearTimeout(t)}export{k as cancellable,T as defineMutator,x as mutate};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["MAX_ERROR_LEN","truncateError","input","str","raw","safeStringCoerce","value","defineMutator","handlers","t","facts","payload","_req","ctx","factsRef","pending","handler","handlerCtx","err","mutate","kind","cancellable","opts","supersedeOn","timeoutMs","scheduleTimeout","defaultSetTimeout","priorController","controller","cancelTimeout","cb","ms","handle"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @directive-run/mutator\n *\n * Discriminated mutation helper. Collapses the manual `pendingAction`\n * ceremony — fact + event + constraint + resolver — into a typed handler\n * map.\n *\n * Background: across the 55-cycle Minglingo migration, 12 modules ended\n * up with the same shape:\n *   - a nullable `pendingAction` fact holding a discriminated union\n *   - an event that sets it\n *   - a constraint that fires on non-null\n *   - a resolver that switches on the discriminator and clears the fact\n *\n * That's ~50 lines of boilerplate per module times 12 modules. The\n * `defineMutator` helper below contributes all four pieces from a single\n * typed declaration, so a module that uses it spreads the fragments\n * into its `createModule` config and writes only the per-variant handler\n * bodies.\n *\n * @see ../README.md for the full API and a worked example.\n */\n\nimport { t } from \"@directive-run/core\";\n\n/**\n * A keyed map of variant payloads. Each key becomes a discriminator value\n * for the mutation, each value is the payload type for that variant.\n *\n * @example\n * ```ts\n * type MyMutations = {\n *   submit: { values: FormValues };\n *   cancel: {};\n *   retry: { reason: string };\n * };\n * ```\n */\nexport type MutationMap = Record<string, Record<string, unknown>>;\n\n/**\n * The shape of a `pendingMutation` fact while a mutation is queued or\n * running.\n */\nexport type PendingMutation<M extends MutationMap> = {\n  [K in keyof M]: {\n    kind: K;\n    payload: M[K];\n    /**\n     * `pending` — queued, constraint hasn't fired yet.\n     * `running` — handler is in flight.\n     * `failed` — handler threw; constraint stops firing. Caller can\n     *            inspect `error` and dispatch a fresh MUTATE to retry.\n     */\n    status: \"pending\" | \"running\" | \"failed\";\n    /**\n     * Error message from the previous run, if any. Plaintext only —\n     * NEVER render this directly via `dangerouslySetInnerHTML` or\n     * markdown. Truncated to 500 chars to bound XSS surface from\n     * thrown messages that may echo user input.\n     */\n    error: string | null;\n  };\n}[keyof M];\n\n/** Maximum length of a captured error message — bounded to limit XSS surface. */\nconst MAX_ERROR_LEN = 500;\n\n/**\n * Coerce a thrown value to a bounded plaintext string for storage on\n * `pendingMutation.error`. Defends against:\n *   - non-Error throws (`throw \"string\"`, `throw 42`, `throw {}`)\n *   - Errors with non-string `.message` (overridden numeric / Symbol /\n *     buffer); naive `.length` / `.slice` would `TypeError` otherwise\n *   - extremely long messages with attacker-influenced input\n *\n * Returns at most {@link MAX_ERROR_LEN} characters of plaintext.\n * Plaintext rendering is still the only supported path on the\n * consumer side; this is defense in depth, not an XSS sanitizer.\n *\n * (R2 sec M-R2-1.)\n */\nfunction truncateError(input: unknown): string {\n  let str: string;\n  if (input instanceof Error) {\n    // Reading `.message` is wrapped in try/catch because a maliciously\n    // constructed Error subclass may install a throwing getter on\n    // `message`. Without this guard the throw escapes truncateError →\n    // escapes the resolver's catch → propagates uncaught. (R4 backlog.)\n    let raw: unknown;\n    try {\n      raw = input.message;\n    } catch {\n      raw = \"[mutator: error.message getter threw]\";\n    }\n    str = typeof raw === \"string\" ? raw : safeStringCoerce(raw);\n  } else if (typeof input === \"string\") {\n    str = input;\n  } else {\n    str = safeStringCoerce(input);\n  }\n  if (str.length <= MAX_ERROR_LEN) return str;\n  return `${str.slice(0, MAX_ERROR_LEN - 1)}…`;\n}\n\n/** String() may throw for some Symbols + objects with hostile toString. */\nfunction safeStringCoerce(value: unknown): string {\n  try {\n    return String(value);\n  } catch {\n    return \"[mutator: unstringifiable error]\";\n  }\n}\n\n/**\n * Handler context passed to each variant handler.\n *\n * Note: `deps` is NOT in the context. This matches the Directive resolver\n * idiom — close over deps from the outer module-factory scope:\n *\n * ```ts\n * function createFormModule(deps: FormDeps) {\n *   const mut = defineMutator<FormMutations, FormFacts>({\n *     submit: async ({ payload, facts }) => {\n *       facts.values = await deps.submit(payload.values); // ← closure\n *     },\n *   });\n *   return createModule('form', { ... });\n * }\n * ```\n */\nexport interface MutatorHandlerContext<F> {\n  /** Live facts proxy. Reads are cache-tracked; writes invalidate. */\n  facts: F;\n  /**\n   * Trigger a same-constraint re-fire after this handler returns. Useful\n   * when one mutation cascades into another — without `requeue`, the next\n   * mutation would stall behind same-flush suppression.\n   *\n   * @see https://docs.directive.run/testing/chained-pipelines\n   */\n  requeue: () => void;\n}\n\n/**\n * Variant handler body. Receives the typed payload + a context; returns\n * void or a Promise. Throwing is fine — the runtime captures into\n * `pendingMutation.error` before clearing the fact.\n */\nexport type MutationHandler<\n  M extends MutationMap,\n  K extends keyof M,\n  F,\n> = keyof M[K] extends never\n  ? (ctx: MutatorHandlerContext<F>) => void | Promise<void>\n  : (\n      ctx: MutatorHandlerContext<F> & { payload: M[K] },\n    ) => void | Promise<void>;\n\n/**\n * The full handler map. Every variant in `M` MUST have a handler.\n */\nexport type MutationHandlers<M extends MutationMap, F> = {\n  [K in keyof M]: MutationHandler<M, K, F>;\n};\n\n/**\n * The fragments returned by `defineMutator`. Spread each fragment into\n * the matching position of your `createModule` config.\n *\n * @internal Shape documented for type clarity; users typically just\n * spread.\n */\nexport interface MutatorFragments<M extends MutationMap, F> {\n  /** Spread into `schema.facts`. Adds `pendingMutation`. */\n  facts: {\n    pendingMutation: ReturnType<typeof t.object>;\n  };\n  /** Spread into `schema.events`. Adds the `MUTATE` event. */\n  events: {\n    MUTATE: PendingMutation<M>;\n  };\n  /** Spread into `schema.requirements`. Adds `PROCESS_MUTATION`. */\n  requirements: {\n    PROCESS_MUTATION: Record<string, never>;\n  };\n  /** Spread into the `events` field. Sets pendingMutation on MUTATE. */\n  eventHandlers: {\n    MUTATE: (facts: F, payload: PendingMutation<M>) => void;\n  };\n  /** Spread into the `constraints` field. */\n  constraints: {\n    pendingMutation: {\n      when: (facts: F) => boolean;\n      require: { type: \"PROCESS_MUTATION\" };\n    };\n  };\n  /** Spread into the `resolvers` field. */\n  resolvers: {\n    mutationResolver: {\n      requirement: \"PROCESS_MUTATION\";\n      resolve: (\n        req: { type: \"PROCESS_MUTATION\" },\n        ctx: { facts: F },\n      ) => Promise<void>;\n    };\n  };\n  /**\n   * Convenience: the initial value for `pendingMutation`. Set this in\n   * your module's `init` if you don't use `t.X().default(...)` defaults.\n   */\n  initialPendingMutation: null;\n}\n\n/**\n * Define a mutator fragment-set for a given variant map and handlers.\n *\n * @example\n * ```ts\n * type FormMutations = {\n *   submit: { values: FormValues };\n *   cancel: {};\n * };\n *\n * // The second generic is the FACTS type (not deps). Deps are\n * // captured in closure from the surrounding scope, not passed in\n * // through the handler ctx.\n * const formMutator = defineMutator<FormMutations, FormFacts>({\n *   submit: async ({ payload, facts }) => {\n *     facts.values = await deps.submit(payload.values); // deps closes over outer scope\n *   },\n *   cancel: ({ facts }) => { facts.values = []; },\n * });\n *\n * createModule('form', {\n *   schema: {\n *     facts: { ...formMutator.facts, values: t.array<FormValues>() },\n *     events: { ...formMutator.events, REFRESH: {} },\n *     requirements: { ...formMutator.requirements },\n *   },\n *   init: (f) => { f.pendingMutation = null; f.values = []; },\n *   events: {\n *     ...formMutator.eventHandlers,\n *     REFRESH: (f) => { f.values = []; },\n *   },\n *   constraints: { ...formMutator.constraints },\n *   resolvers: { ...formMutator.resolvers },\n * });\n *\n * // Usage:\n * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));\n *\n * // Or, if constructing the payload manually, the discriminator is\n * // `kind` (NOT `type` — `type` collides with Directive's event-name\n * // dispatch convention):\n * sys.events.MUTATE({\n *   kind: 'submit',\n *   payload: { values: ... },\n *   status: 'pending',\n *   error: null,\n * });\n * ```\n *\n * The handler-bound deps are captured at `defineMutator` call time. To\n * inject deps from the caller, wrap `defineMutator` in your module\n * factory:\n *\n * ```ts\n * export function createFormModule(deps: FormDeps) {\n *   const mut = defineMutator<FormMutations, FormFacts>({\n *     submit: async ({ payload, facts }) => {\n *       facts.values = await deps.submit(payload.values);\n *     },\n *     cancel: ({ facts }) => { facts.values = []; },\n *   });\n *   return createModule('form', { ... });\n * }\n * ```\n */\nexport function defineMutator<\n  M extends MutationMap,\n  F = Record<string, unknown>,\n>(handlers: MutationHandlers<M, F>): MutatorFragments<M, F> {\n  type Pending = PendingMutation<M>;\n\n  const facts = {\n    pendingMutation: t.object<Pending>().nullable() as ReturnType<\n      typeof t.object\n    >,\n  } as MutatorFragments<M, F>[\"facts\"];\n\n  // Schema event marker — the runtime uses this for typing and devtools.\n  // Payload validation happens at dispatch time via t-schema check.\n  const events = {\n    MUTATE: undefined as unknown as Pending,\n  } as MutatorFragments<M, F>[\"events\"];\n\n  const requirements = {\n    PROCESS_MUTATION: {} as Record<string, never>,\n  } as MutatorFragments<M, F>[\"requirements\"];\n\n  const eventHandlers = {\n    MUTATE: (facts: F, payload: Pending) => {\n      // Overwrite is intentional — caller is responsible for ordering.\n      // If a previous mutation is mid-flight, the new one queues by\n      // overwriting; the in-flight handler will null the fact when it\n      // completes, then the constraint re-fires for the new one.\n      // (Same as the manual pattern across all 12 audited modules.)\n      (facts as { pendingMutation: Pending | null }).pendingMutation = {\n        ...payload,\n        status: \"pending\",\n        error: null,\n      };\n    },\n  } as MutatorFragments<M, F>[\"eventHandlers\"];\n\n  const constraints = {\n    pendingMutation: {\n      when: (facts: F) =>\n        (facts as { pendingMutation: Pending | null }).pendingMutation !==\n          null &&\n        (facts as { pendingMutation: Pending | null }).pendingMutation\n          ?.status === \"pending\",\n      require: { type: \"PROCESS_MUTATION\" } as const,\n    },\n  } as MutatorFragments<M, F>[\"constraints\"];\n\n  const resolvers = {\n    mutationResolver: {\n      requirement: \"PROCESS_MUTATION\" as const,\n      resolve: async (\n        _req: { type: \"PROCESS_MUTATION\" },\n        ctx: {\n          facts: F;\n          requeue?: () => void;\n        },\n      ) => {\n        const factsRef = ctx.facts as { pendingMutation: Pending | null };\n        const pending = factsRef.pendingMutation;\n        if (pending === null) return;\n\n        // Stamp the in-flight transition with the running status. The\n        // status itself is the supersession marker: only this resolver\n        // ever writes 'running'; the eventHandler always writes\n        // 'pending'. So if a fresh MUTATE arrives mid-flight, the\n        // post-handler check sees status: 'pending' instead of\n        // 'running' and knows to leave the new dispatch alone.\n        // (Sec M5 / DX M2.)\n        factsRef.pendingMutation = { ...pending, status: \"running\" };\n\n        // Prototype-pollution defense: only accept handlers OWNED by\n        // the user-provided map. Without this, dispatching with kind:\n        // 'constructor' / 'toString' / '__proto__' would resolve via\n        // the prototype chain and either crash or invoke an inherited\n        // function with arbitrary payload. (Sec C1.)\n        const ownsHandler = Object.prototype.hasOwnProperty.call(\n          handlers,\n          pending.kind as PropertyKey,\n        );\n        const handler = ownsHandler\n          ? (handlers as Record<string, unknown>)[pending.kind as string]\n          : undefined;\n\n        if (typeof handler !== \"function\") {\n          factsRef.pendingMutation = {\n            ...pending,\n            status: \"failed\",\n            error: truncateError(\n              `[mutator] no handler registered for variant: ${String(\n                pending.kind,\n              )}`,\n            ),\n          };\n          return;\n        }\n\n        const handlerCtx = {\n          facts: ctx.facts,\n          payload: pending.payload,\n          requeue: ctx.requeue ?? (() => {}),\n        };\n\n        try {\n          await (handler as (c: typeof handlerCtx) => Promise<void> | void)(\n            handlerCtx,\n          );\n          // Success: clear the fact ONLY if this resolver's `running`\n          // marker is still live (status === 'running'). If a fresh\n          // MUTATE arrived mid-flight via the eventHandler, the fact\n          // now has status: 'pending' — leave it alone so the next\n          // constraint fire picks it up. (Sec M5 / DX M2.)\n          if (factsRef.pendingMutation?.status === \"running\") {\n            factsRef.pendingMutation = null;\n          }\n        } catch (err) {\n          // Failure: only stamp the error if our running marker is\n          // still live. If a fresh MUTATE arrived mid-flight, the new\n          // dispatch wins; the failed mutation's error is dropped on\n          // the floor (caller wanted to move on anyway). (Sec M5.)\n          if (factsRef.pendingMutation?.status !== \"running\") return;\n          factsRef.pendingMutation = {\n            ...pending,\n            // 'failed' is a distinct status (Sec M6 / Arch C2) — UI can\n            // disambiguate \"still in flight\" from \"stopped on error\".\n            status: \"failed\",\n            // truncateError handles the unknown shape safely — non-Error\n            // throws, non-string Error.message, hostile toString. (R2\n            // sec M-R2-1.)\n            error: truncateError(err),\n          };\n        }\n      },\n    },\n  } as MutatorFragments<M, F>[\"resolvers\"];\n\n  return {\n    facts,\n    events,\n    requirements,\n    eventHandlers,\n    constraints,\n    resolvers,\n    initialPendingMutation: null,\n  };\n}\n\n/**\n * Helper for typed dispatch. Lets the caller construct a mutation payload\n * with full type narrowing — the `kind` field auto-restricts the\n * `payload` shape.\n *\n * @example\n * ```ts\n * sys.events.MUTATE(mutate<FormMutations>('submit', { values: ... }));\n * sys.events.MUTATE(mutate<FormMutations>('cancel'));\n * ```\n */\n// Single type parameter (M) so callers can specialize with\n// `mutate<FormMutations>(...)` without TypeScript demanding the\n// inferred K. TS's strict type-argument rules treat <M, K> as\n// \"supply both or supply neither\" — single-arg call sites failed\n// with \"Expected 2 type arguments, but got 1.\" Single-M form sidesteps\n// that while keeping payload typing tight via the `kind` lookup.\nexport function mutate<M extends MutationMap>(\n  kind: keyof M & string,\n  payload: M[typeof kind],\n): PendingMutation<M>;\nexport function mutate<M extends MutationMap>(\n  kind: keyof M & string,\n): PendingMutation<M>;\nexport function mutate<M extends MutationMap>(\n  kind: keyof M & string,\n  payload?: M[typeof kind],\n): PendingMutation<M> {\n  return {\n    kind,\n    payload: (payload ?? {}) as M[typeof kind],\n    status: \"pending\",\n    error: null,\n  } as PendingMutation<M>;\n}\n\n// ============================================================================\n// cancellable() — auto-cancel-on-supersede (R1.C v0.1)\n// ============================================================================\n\n/**\n * Options for {@link cancellable}.\n */\nexport interface CancellableOptions {\n  /**\n   * When to fire the AbortSignal that the wrapped handler receives.\n   *\n   * - `'self'` (default): a new dispatch of the SAME handler aborts the\n   *   prior in-flight invocation. The classic \"cancel previous on new\n   *   keystroke\" pattern.\n   * - `'never'`: only the timeout fires the signal; new dispatches do\n   *   NOT abort prior ones. Useful when you want a hard timeout but\n   *   parallel runs are fine.\n   */\n  supersedeOn?: \"self\" | \"never\";\n\n  /**\n   * Maximum ms a handler may run before its signal is aborted. Counted\n   * from the start of THIS invocation. Combine with `realClock` for\n   * production or pass a `setTimeout` shim for deterministic testing.\n   */\n  timeoutMs?: number;\n\n  /**\n   * Optional `setTimeout` injection. Defaults to `globalThis.setTimeout`.\n   * For deterministic tests, pass `virtualClock.setTimeout` from\n   * `@directive-run/core` so the timeout fires under\n   * `clock.advanceBy()` instead of wall-clock real time.\n   *\n   * @example\n   * ```ts\n   * import { virtualClock } from '@directive-run/core';\n   * const clock = virtualClock(0);\n   * cancellable({ timeoutMs: 1_000, setTimeout: clock.setTimeout }, handler);\n   * ```\n   */\n  setTimeout?: (cb: () => void, ms: number) => () => void;\n}\n\n/**\n * Handler context augmented with a cancellation signal.\n */\nexport interface CancellableHandlerContext<F, P> {\n  facts: F;\n  payload: P;\n  /** Aborts when a new dispatch supersedes this one OR the timeout fires. */\n  signal: AbortSignal;\n  requeue: () => void;\n}\n\n/**\n * Reason a cancellable handler's signal aborted. Stamped on\n * `signal.reason` so the handler can disambiguate.\n */\nexport type CancelReason =\n  | { kind: \"superseded\" }\n  | { kind: \"timeout\"; afterMs: number };\n\n/**\n * Wrap a mutator handler with auto-cancellation. The wrapped handler\n * receives an extra `signal: AbortSignal` in its context. Use the\n * signal to short-circuit awaitable work — pass it to `fetch(url, {\n * signal })`, watch it inside long-running loops, etc.\n *\n * Two cancellation triggers, both opt-in via {@link CancellableOptions}:\n *\n *   1. **Supersession** (default `supersedeOn: 'self'`): when a new\n *      dispatch of the same wrapped handler arrives while a prior\n *      invocation is still running, the prior signal aborts.\n *   2. **Timeout** (default `timeoutMs: undefined`, meaning no timeout):\n *      after `timeoutMs` ms from invocation start, the signal aborts.\n *\n * If a handler's signal aborts, the handler should observe the abort\n * (via `signal.aborted` or the AbortError-throwing helpers) and\n * return promptly. The signal's `reason` carries a {@link CancelReason}\n * disambiguating which trigger fired.\n *\n * Compose with {@link defineMutator} by using `cancellable()` directly\n * in the handler map:\n *\n * @example\n * ```ts\n * import { defineMutator, cancellable } from '@directive-run/mutator';\n *\n * const formMutator = defineMutator<MyMutations, MyFacts>({\n *   search: cancellable(\n *     { supersedeOn: 'self', timeoutMs: 3_000 },\n *     async ({ payload, facts, signal }) => {\n *       const res = await fetch(`/q?${payload.q}`, { signal });\n *       facts.results = await res.json();\n *     },\n *   ),\n *   submit: async ({ payload, facts }) => {\n *     // No cancellation needed for submit — plain handler.\n *     facts.values = await deps.submit(payload.values);\n *   },\n * });\n * ```\n *\n * **Idempotency note.** The wrapped handler stays a regular\n * `MutationHandler<M, K, F>` from the mutator's perspective. The\n * supersession registry is closure-scoped per `cancellable()` call —\n * two separate `cancellable(...)` HOCs around different handlers do\n * NOT cancel each other.\n *\n * **Test ergonomics.** Pass `virtualClock.setTimeout` via the\n * `setTimeout` option to make timeouts deterministic under\n * `clock.advanceBy(ms)`. Without that, timeouts use wall-clock\n * `globalThis.setTimeout` and are real-time.\n */\nexport function cancellable<F, P>(\n  opts: CancellableOptions,\n  handler: (ctx: CancellableHandlerContext<F, P>) => Promise<void> | void,\n): (ctx: { facts: F; payload: P; requeue: () => void }) => Promise<void> {\n  const supersedeOn = opts.supersedeOn ?? \"self\";\n  const timeoutMs = opts.timeoutMs;\n  const scheduleTimeout = opts.setTimeout ?? defaultSetTimeout;\n\n  // Closure-scoped supersession slot — one entry for the wrapped\n  // handler. When a new invocation arrives, the prior entry's\n  // controller aborts before the new one starts.\n  let priorController: AbortController | undefined;\n\n  return async (ctx: { facts: F; payload: P; requeue: () => void }) => {\n    // Supersession: abort the prior in-flight invocation, if any.\n    if (supersedeOn === \"self\" && priorController !== undefined) {\n      priorController.abort({ kind: \"superseded\" } satisfies CancelReason);\n    }\n\n    const controller = new AbortController();\n    priorController = controller;\n\n    // Timeout: schedule an abort after `timeoutMs`. The cancel handle\n    // returned by `scheduleTimeout` lets us clear the timer if the\n    // handler completes first (saves leaking timers under a barrage\n    // of dispatches).\n    let cancelTimeout: (() => void) | undefined;\n    if (typeof timeoutMs === \"number\" && timeoutMs > 0) {\n      cancelTimeout = scheduleTimeout(() => {\n        controller.abort({ kind: \"timeout\", afterMs: timeoutMs } satisfies CancelReason);\n      }, timeoutMs);\n    }\n\n    try {\n      await handler({\n        facts: ctx.facts,\n        payload: ctx.payload,\n        requeue: ctx.requeue,\n        signal: controller.signal,\n      });\n    } finally {\n      // Clean up: clear the timeout (if it hasn't fired) and release\n      // the supersession slot if it still belongs to this invocation.\n      cancelTimeout?.();\n      if (priorController === controller) {\n        priorController = undefined;\n      }\n    }\n  };\n}\n\n/**\n * Default `setTimeout` shim — wraps `globalThis.setTimeout` to match\n * the cancel-handle signature `cancellable()` expects.\n */\nfunction defaultSetTimeout(cb: () => void, ms: number): () => void {\n  const handle = globalThis.setTimeout(cb, ms);\n  return () => globalThis.clearTimeout(handle);\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@directive-run/mutator",
+  "version": "0.2.0",
+  "description": "Discriminated mutation helper for Directive — collapse the pendingAction ceremony to a typed handler map.",
+  "license": "(MIT OR Apache-2.0)",
+  "author": "Jason Comes",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/directive-run/directive",
+    "directory": "packages/mutator"
+  },
+  "homepage": "https://directive.run",
+  "bugs": {
+    "url": "https://github.com/directive-run/directive/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "directive",
+    "mutator",
+    "state-management",
+    "discriminated-union",
+    "optimistic-update"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@directive-run/core": "^1.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9",
+    "@directive-run/core": "1.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}