@demlik/tea 0.14.0 → 0.16.0

package/dist/pbt/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/pbt/arbitraries/ctx.ts","../../src/pbt/arbitraries/msg.ts","../../src/pbt/arbitraries/sequence.ts","../../src/pbt/runners/replay-fold.ts","../../src/pbt/runners/property.ts","../../src/pbt/util/msg-keys.ts"],"names":["fc2","fc3"],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// `stubCtxThrowingProxy<Ctx>()` — a Proxy that satisfies the Ctx type-shape\n// at compile time but throws on every property access at runtime.\n//\n// Why this exists: PBT runs the pure reducer surface ONLY — `replay` never\n// invokes `interpret` and never starts a Sub, so Ctx should never be\n// dereferenced during property generation. But the substrate's `replay`\n// signature requires a `ctx: Ctx` value at compile time (it forwards ctx\n// into `init`, which on some machines IS pure but on others reads ctx). A\n// hand-rolled `{} as Ctx` would silently pass through any accidental ctx\n// access — exactly the silent footgun this proxy catches.\n//\n// Open question 2 (design doc): we ship this as the default. Tests that\n// genuinely need a working ctx (because their `init` reads from it) can\n// pass a real ctx value instead — the proxy is opt-in, not load-bearing.\n//\n// Strengthens invariant 6 (no silent failures — accidental ctx reads\n// produce a useful error, not a `undefined.foo` confusion later).\n// ---------------------------------------------------------------------------\n\n/**\n * Build a Ctx value whose every property access throws. Use as the `ctx`\n * argument to PBT runners when the reducer under test is pure (does not\n * read from ctx). Accidental ctx access during property generation\n * surfaces as a labelled error instead of a silent `undefined` or\n * downstream type-error.\n *\n * Returns a typed `Ctx` (via `as unknown as Ctx`) — the proxy satisfies the\n * type-shape requirement at the call site; the runtime contract is\n * \"throw on first read.\" The `as unknown` cast is the one boundary cast\n * this helper requires; the proxy is structurally a `Ctx` for every\n * property accessor.\n *\n * @example\n *   import { stubCtxThrowingProxy } from \"../index\";\n *   const ctx = stubCtxThrowingProxy<MyCtx>();\n *   propertyTerminates(machine, ctx, ...);\n *   // If anything reads ctx.someField during the run, an Error throws:\n *   //   \"@demlik/tea/pbt: ctx access denied (PBT operates on the pure\n *   //    reducer; ctx field 'someField' was read)\"\n */\nexport function stubCtxThrowingProxy<Ctx>(): Ctx {\n  const handler: ProxyHandler<object> = {\n    get(_target, prop: string | symbol): unknown {\n      // Allow vitest / fast-check internals to introspect via Symbol-keyed\n      // checks (e.g. Symbol.toStringTag, Symbol.iterator). Returning\n      // undefined on symbol keys keeps property-tree walks cheap; the\n      // throw fires on real domain field reads.\n      if (typeof prop === \"symbol\") return undefined;\n      // Some shrinkers / pretty-printers in fast-check probe a small set\n      // of conventional field names (`toJSON`, `toString`, `valueOf`,\n      // `then` — the last for thenable-check). Return undefined for those\n      // so the proxy doesn't fail a probe before the property body runs.\n      if (\n        prop === \"toJSON\" ||\n        prop === \"toString\" ||\n        prop === \"valueOf\" ||\n        prop === \"then\"\n      ) {\n        return undefined;\n      }\n      throw new Error(\n        `@demlik/tea/pbt: ctx access denied (PBT operates on the pure reducer; ` +\n          `ctx field '${prop}' was read). Pass a real ctx value if the reducer's ` +\n          `init reads from ctx.`,\n      );\n    },\n    has(): boolean {\n      return false;\n    },\n    ownKeys(): ArrayLike<string | symbol> {\n      return [];\n    },\n  };\n  return new Proxy({}, handler) as unknown as Ctx;\n}\n","// ---------------------------------------------------------------------------\n// Msg arbitrary builders.\n//\n// `MsgArbitraryTable<M>` is a strict mapped type — every Msg variant must\n// have an arbitrary entry, keyed by `M[\"type\"]`, narrowing the arbitrary's\n// `T` to `Extract<M, { type: K }>`. This mirrors the load-bearing discipline\n// of `Reducer<S, M, C>` and `Transitions<S, M, C>` in the substrate: adding\n// a Msg variant without an arbitrary fails to compile, not at runtime.\n//\n// `arbMsg(table, opts?)` collapses the table into a single `fc.Arbitrary<M>`\n// via `fc.oneof`. Optional per-variant weighting for sequence-skew tests.\n//\n// `arbConstantMsg(type)` / `arbRecordMsg(type, fields)` are sugar over\n// `fc.constant({ type })` / `fc.record({ type: fc.constant(type), ...fields })`.\n// They exist because every Msg variant arbitrary either (a) carries no\n// payload — `arbConstantMsg(\"stop\")` — or (b) carries a record of fields —\n// `arbRecordMsg(\"tick\", { now: fc.integer() })`. Naming the two shapes\n// prevents callers from hand-rolling `fc.record({ type: fc.constant(\"...\") })`\n// inconsistently across test files.\n//\n// Open question 1 from the design doc (strict vs Partial table): strict by\n// default. The mapped type catches drift at compile time; `arbMsgPartial`\n// sugar is a future addition iff friction becomes real.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\n\n/**\n * Strict per-variant Msg arbitrary table. Mapped type: every key in\n * `M[\"type\"]` MUST have an arbitrary entry whose `T` is the narrowed\n * variant. Adding a new Msg variant without an entry is a compile error\n * (same load-bearing discipline as `Reducer<S, M, C>` in the substrate).\n *\n * @example\n *   type Msg = { type: \"start\" } | { type: \"tick\"; now: number };\n *   const table: MsgArbitraryTable<Msg> = {\n *     start: arbConstantMsg(\"start\"),\n *     tick: arbRecordMsg(\"tick\", { now: fc.integer({ min: 0 }) }),\n *   };\n */\nexport type MsgArbitraryTable<M extends { type: string }> = {\n  [K in M[\"type\"]]: fc.Arbitrary<Extract<M, { type: K }>>;\n};\n\n/**\n * Build a single `fc.Arbitrary<M>` from a `MsgArbitraryTable<M>`. Picks one\n * variant per generation via `fc.oneof`; optional per-variant `weights`\n * bias the distribution (default uniform).\n *\n * @param table   Per-variant arbitrary table (strict — every variant required).\n * @param opts    Optional bias: `weights` is a `Partial<Record<M[\"type\"], number>>`.\n *                Variants without an explicit weight default to 1.\n *\n * @example\n *   const msgArb = arbMsg<Msg>({\n *     start: arbConstantMsg(\"start\"),\n *     tick:  arbRecordMsg(\"tick\", { now: fc.integer() }),\n *     stop:  arbConstantMsg(\"stop\"),\n *   }, { weights: { tick: 5, start: 1, stop: 1 } });\n */\nexport function arbMsg<M extends { type: string }>(\n  table: MsgArbitraryTable<M>,\n  opts?: { weights?: Partial<Record<M[\"type\"], number>> },\n): fc.Arbitrary<M> {\n  const weights = opts?.weights;\n  const entries = Object.entries(table) as [M[\"type\"], fc.Arbitrary<M>][];\n  if (entries.length === 0) {\n    throw new Error(\"@demlik/tea/pbt: arbMsg table is empty\");\n  }\n  const weighted = entries.map(([key, arb]) => ({\n    arbitrary: arb,\n    weight: weights?.[key] ?? 1,\n  }));\n  return fc.oneof(...weighted);\n}\n\n/**\n * Build a payload-free Msg variant arbitrary. Sugar for\n * `fc.constant({ type })` that narrows the result to `{ type: T }` literal.\n *\n * @example\n *   arbConstantMsg(\"stop\") // fc.Arbitrary<{ type: \"stop\" }>\n */\nexport function arbConstantMsg<T extends string>(\n  type: T,\n): fc.Arbitrary<{ type: T }> {\n  return fc.constant({ type });\n}\n\n/**\n * Build a record-shaped Msg variant arbitrary. Sugar for\n * `fc.record({ type: fc.constant(type), ...fields })` that stamps the\n * discriminator literal and combines with the per-field arbitraries.\n *\n * @example\n *   arbRecordMsg(\"tick\", { now: fc.integer({ min: 0 }) })\n *   // fc.Arbitrary<{ type: \"tick\"; now: number }>\n */\nexport function arbRecordMsg<T extends string, R>(\n  type: T,\n  fields: { [K in keyof R]: fc.Arbitrary<R[K]> },\n): fc.Arbitrary<{ type: T } & R> {\n  // `fc.record` builds an arbitrary of the merged-shape record. The\n  // `type: fc.constant(type)` field stamps the literal discriminator;\n  // the spread of `fields` provides every payload field's arbitrary.\n  //\n  // The intermediate `as Record<string, fc.Arbitrary<unknown>>` is the\n  // single load-bearing cast — fc.record's parameter type is invariant in\n  // its inferred field shape, and the merged literal-and-generic spread\n  // doesn't unify with the strict `{ [K in keyof R]: Arbitrary<R[K]> }`\n  // shape TS computes for us. The outer cast to `fc.Arbitrary<{ type: T }\n  // & R>` restates the result shape we know to be correct at this\n  // boundary. Mirrors the same discipline `fc.record` callers use\n  // throughout the prior-art branch.\n  const recordArbitraries: Record<string, fc.Arbitrary<unknown>> = {\n    type: fc.constant(type),\n    ...(fields as Record<string, fc.Arbitrary<unknown>>),\n  };\n  return fc.record(recordArbitraries) as unknown as fc.Arbitrary<\n    { type: T } & R\n  >;\n}\n","// ---------------------------------------------------------------------------\n// Msg-sequence arbitraries.\n//\n// `arbMsgSequence(msgArb, opts)` produces `fc.Arbitrary<readonly M[]>` —\n// fast-check's default-shrinker handles the array; the per-element shrinker\n// inside `msgArb` shrinks each variant. Optional `prefix` is prepended\n// verbatim (used by Test A: \"the bug-triggering Msg leads the sequence\").\n//\n// `arbGuidedSequence` is the state-aware sequence builder. In v1 it throws\n// — Phase 6 of the design doc lands the `fc.commands`-backed implementation.\n// The export exists today so the surface is forward-compatible: consumers\n// that need state-aware generation get a useful error pointing at the\n// design doc instead of \"is not a function.\"\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\n\n/**\n * Build an arbitrary of Msg sequences over a per-Msg arbitrary. Optionally\n * bounded in length and / or prefixed with a fixed sequence.\n *\n * - `minLength` (default 0) and `maxLength` (default 30) bound the random\n *   array length. `prefix` is prepended AFTER the random tail is built; the\n *   final length is `prefix.length + tail.length`.\n * - `prefix` is the load-bearing escape hatch for \"the first msg is the\n *   one that exercises the cell I care about\" (e.g. Test A's\n *   `[{ type: \"ws:client:hello\" }]` prefix to land in the\n *   `auditing.ws:client:hello` cell on the first transition).\n *\n * @example\n *   arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 });\n *   arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }], maxLength: 20 });\n */\nexport function arbMsgSequence<M extends { type: string }>(\n  msgArb: fc.Arbitrary<M>,\n  opts?: {\n    readonly minLength?: number;\n    readonly maxLength?: number;\n    readonly prefix?: readonly NoInfer<M>[];\n  },\n): fc.Arbitrary<readonly M[]> {\n  const minLength = opts?.minLength ?? 0;\n  const maxLength = opts?.maxLength ?? 30;\n  const prefix = opts?.prefix ?? [];\n  const tail = fc.array(msgArb, { minLength, maxLength });\n  if (prefix.length === 0) return tail;\n  return tail.map((arr) => [...prefix, ...arr]);\n}\n\n/**\n * State-aware Msg sequence arbitrary — generates only msgs whose\n * precondition holds in the current state. Backed by `fc.commands`\n * internally. Planned for a later phase.\n *\n * **NOT IMPLEMENTED IN v1.** The export exists today so the surface is\n * forward-compatible; this ships in a later phase alongside\n * shrinkers. Calling it throws.\n */\nexport function arbGuidedSequence<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  _machine: Machine<S, M, C, U, Ctx>,\n  _ctx: Ctx,\n  _cells: {\n    [K in M[\"type\"]]?: (\n      state: S,\n    ) => fc.Arbitrary<Extract<M, { type: K }>> | null;\n  },\n  _opts?: { maxLength?: number },\n): fc.Arbitrary<readonly M[]> {\n  throw new Error(\n    \"@demlik/tea/pbt: arbGuidedSequence is not implemented in v1. \" +\n      \"Use arbMsgSequence with \" +\n      \"an unguided arbMsg table for now; states that don't accept a given \" +\n      \"msg should noop in the reducer (mapped-type discipline).\",\n  );\n}\n","// ---------------------------------------------------------------------------\n// `foldEvents` — pure deterministic fold over a Msg sequence.\n//\n// PBT needs the per-step (prev/msg/next/cmds) structure to assert\n// step-shaped invariants. The substrate's `replay(machine, opts)` returns\n// only final state + cumulative cmds — insufficient. We use `replay` for\n// the boot step (calls `machine.init(loaded, ctx)` faithfully) then walk\n// msgs ourselves through `applyCell`, the substrate's own cell dispatch.\n//\n// Why walk cells directly instead of looping `replay` once per msg with\n// `loaded: prevState`? Because `init(loaded)` runs every call, and on\n// machines with non-trivial init transforms (e.g. the audit machine's\n// `auditing → attach_debugger` resume cell) that would either (a) re-fire\n// the transform on every step, or (b) require fragile cmd-subtraction to\n// isolate this step's cmds. Calling the cells directly keeps the fold pure\n// and the cmds per-step exactly.\n//\n// Dispatches through `applyCell` — the single primitive `run`/`replay` use —\n// so form classification agrees with production by construction (#275).\n//\n// `foldEvents` does NOT call `interpret`, does NOT touch a Store, does NOT\n// start Subs. The reducer surface is the contract.\n// ---------------------------------------------------------------------------\n\nimport {\n  applyCell,\n  type Cmd,\n  type Machine,\n  replay,\n  type Sub,\n} from \"../../index\";\n\n/**\n * One unit in a fold trace — the four pieces of data a property\n * invariant typically asserts on. `prev` is the state before the msg\n * applied; `next` is the state after; `cmds` is the cmds emitted by this\n * single step (NOT the running total).\n */\nexport interface Step<S, M, C> {\n  readonly prev: S;\n  readonly msg: M;\n  readonly next: S;\n  readonly cmds: readonly C[];\n}\n\n/**\n * Fold a Msg sequence through a machine's pure reducer, returning the\n * per-step trace, every state in order, and the final state. Initial\n * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.\n * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds\n * are NOT included in any `Step` (they're the boot moment, not a Msg).\n *\n * @param machine  The machine under test.\n * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when\n *                 init is pure. Pass a real ctx if init reads from it.\n * @param loaded   Optional pre-init snapshot (the `loaded` arg to\n *                 `machine.init`). Defaults to `null` (fresh boot).\n * @param msgs     The Msg sequence to fold.\n *\n * @example\n *   const { states, steps, finalState } = foldEvents(machine, ctx, null, [\n *     { type: \"start\" }, { type: \"tick\" }, { type: \"stop\" },\n *   ]);\n *   // steps[1] = { prev: { type: \"counting\", n: 0 }, msg: { type: \"tick\" }, ... }\n */\nexport function foldEvents<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  loaded: NoInfer<S> | null,\n  msgs: readonly NoInfer<M>[],\n): {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n} {\n  // Boot through `replay` so `init` runs faithfully and we honor the\n  // substrate's loaded-snapshot contract (init may transform the loaded\n  // value before the first Msg lands — e.g. the audit machine flips\n  // `debuggerAttached: false` on resume).\n  const { state: initialState } = replay(machine, {\n    msgs: [],\n    ctx,\n    loaded: loaded ?? null,\n  });\n\n  // Per-msg dispatch goes through `applyCell` — the same primitive `run` and\n  // `replay` use — so this runner classifies the update form identically to\n  // production (`formOf` honors the `__form` tag; #275).\n  const states: S[] = [initialState];\n  const steps: Step<S, M, C>[] = [];\n  let current = initialState;\n\n  for (const msg of msgs) {\n    const [next, emitted] = applyCell<S, M, C>(machine, current, msg);\n    steps.push({ prev: current, msg, next, cmds: [...emitted] });\n    states.push(next);\n    current = next;\n  }\n\n  return { states, steps, finalState: current };\n}\n","// ---------------------------------------------------------------------------\n// Property runners — three thin wrappers over `fc.assert(fc.property(...))`\n// that fold a generated Msg sequence through the machine via `foldEvents`\n// and pipe the result into a TEA-shaped predicate.\n//\n//   - `propertyTerminates` — every sequence ends in a terminal state.\n//   - `propertyInvariant`  — predicate holds on every (prev, msg, next, cmds) step.\n//   - `propertyTrace`      — predicate holds on the full (trace, final) shape.\n//\n// Each runner accepts `numRuns` (passed through to fast-check), an optional\n// `loaded` snapshot (forwarded to `foldEvents`), and the Msg-sequence\n// arbitrary. They return `void`; failures throw via fast-check's standard\n// shrinking output.\n//\n// Default shrinker is fast-check's built-in (open question 4): drop-msg /\n// prefix shrinkers can be layered later but are opt-in, not default. The\n// built-in shrinker handles array-shape shrinking + per-element variant\n// shrinking automatically.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\nimport { foldEvents, type Step } from \"./replay-fold\";\n\n/** Common options shared by every property runner. */\ninterface PropertyOpts<S> {\n  /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */\n  readonly loaded?: S | null;\n  /** Number of generated sequences to test. Forwarded to `fc.assert`. */\n  readonly numRuns?: number;\n  /** Optional fast-check seed for reproducibility. */\n  readonly seed?: number;\n}\n\n/** The `foldEvents` result a runner's `check` inspects. */\ntype FoldResult<S, M, C> = {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n};\n\n/**\n * Build the fast-check parameters shared by every runner: the 200-default\n * `numRuns` plus an optional `seed`. Single source of truth so a change to\n * the default lands in one place.\n */\nfunction resolveFcParams<M>(\n  opts: PropertyOpts<unknown> | undefined,\n): fc.Parameters<[readonly M[]]> {\n  return {\n    numRuns: opts?.numRuns ?? 200,\n    ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),\n  };\n}\n\n/**\n * The fold+assert core every runner shares: assert `check` over each\n * generated Msg sequence, folded once through the machine via `foldEvents`.\n * `check` throws on failure so the error message carries the offending\n * shape into fast-check's shrunk counter-example.\n */\nfunction runProperty<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: Ctx,\n  seqArb: fc.Arbitrary<readonly M[]>,\n  opts: PropertyOpts<S> | undefined,\n  check: (result: FoldResult<S, M, C>) => void,\n): void {\n  fc.assert(\n    fc.property(seqArb, (msgs) => {\n      check(foldEvents(machine, ctx, opts?.loaded ?? null, msgs));\n    }),\n    resolveFcParams<M>(opts),\n  );\n}\n\n/**\n * Assert every generated Msg sequence ends in a terminal state. `terminal`\n * is the predicate that names the acceptable final states (often\n * `(s) => s.type === \"done\" || s.type === \"idle\"`).\n *\n * The \"every sequence\" property catches stuck states (machine gets to a\n * non-terminal state and no further msg can escape) AND silent loops\n * (every msg variant is a noop from a given state).\n *\n * @example\n *   propertyTerminates(\n *     auditBackgroundMachine,\n *     stubCtxThrowingProxy<BackgroundCtx>(),\n *     arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 }),\n *     (s) => s.type === \"done\" || s.type === \"idle\",\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTerminates<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  terminal: (state: NoInfer<S>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ finalState }) => {\n    if (!terminal(finalState)) {\n      // Throwing here (vs returning false) lets the error message carry\n      // the offending final state — fast-check pretty-prints it inside\n      // the shrunk counter-example.\n      throw new Error(\n        `propertyTerminates: final state did not match terminal predicate. ` +\n          `Final: ${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n\n/**\n * Assert a predicate holds on EVERY transition step in a generated\n * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;\n * return true to accept, false (or throw) to fail.\n *\n * Use to pin a \"when X happens in state Y, cmd Z must be emitted\" rule.\n * The shrinker minimizes the offending sequence to the smallest Msg list\n * that still violates the predicate.\n *\n * @example\n *   // Pin the resume-handshake fix: `ws:client:hello` in auditing must\n *   // emit `send_ws { client:ready }`.\n *   propertyInvariant(\n *     auditBackgroundMachine, ctx,\n *     arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }] }),\n *     ({ prev, msg, cmds }) =>\n *       !(prev.type === \"auditing\" && msg.type === \"ws:client:hello\") ||\n *       cmds.some((c) => c.type === \"send_ws\" && c.msg.type === \"client:ready\"),\n *     { loaded: auditingState, numRuns: 200 },\n *   );\n */\nexport function propertyInvariant<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps }) => {\n    for (const step of steps) {\n      if (!invariant(step)) {\n        throw new Error(\n          `propertyInvariant: failed at step msg=${JSON.stringify(step.msg)} ` +\n            `prev=${JSON.stringify(step.prev)} next=${JSON.stringify(step.next)} ` +\n            `cmds=${JSON.stringify(step.cmds)}`,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Assert a predicate over the full trace plus the final state. Use when\n * the property is \"some Msg appeared in the trace before reaching the\n * final state\" or \"no two consecutive steps had the same state.type\" —\n * predicates that need the full sequence, not a single step.\n *\n * @example\n *   propertyTrace(\n *     machine, ctx, seqArb,\n *     (steps, final) =>\n *       final.type !== \"done\" ||\n *       steps.some((step) => step.msg.type === \"ws:audit:done\"),\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTrace<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  predicate: (\n    steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[],\n    finalState: NoInfer<S>,\n  ) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps, finalState }) => {\n    if (!predicate(steps, finalState)) {\n      throw new Error(\n        `propertyTrace: predicate failed on trace length=${steps.length}, ` +\n          `final=${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n","// ---------------------------------------------------------------------------\n// msgTypeKeys — read the Msg discriminant set at runtime from a machine's\n// Reducer record or Transitions table.\n//\n// TS Msg unions only exist at the type level; the discriminant strings are\n// erased at runtime. The reducer record / transitions table is the load-\n// bearing artifact that DOES carry the discriminants at runtime — its keys\n// (for Reducer) or any one cell's inner keys (for Transitions) are exactly\n// the set we need to build an `arbMsg` table without hand-listing them.\n//\n// Standalone helper: hand it a machine and it returns the Msg variants the\n// reducer/transitions record carries at runtime. `arbMsg` does NOT call it —\n// `MsgArbitraryTable<M>` enforces table coverage at compile time (adding a\n// variant without an arbitrary fails to compile, not at runtime). This helper\n// is for callers that want the discriminant set explicitly at runtime — e.g.\n// a test asserting a table covers every variant.\n// ---------------------------------------------------------------------------\n\nimport {\n  type Cmd,\n  msgKeysOf,\n  type Reducer,\n  type Transitions,\n  type UpdateForm,\n} from \"../../index\";\n\n/**\n * Extract the Msg discriminant set at runtime from a machine. Useful for\n * asserting that a user-supplied `MsgArbitraryTable<M>` covers every variant\n * the reducer can handle.\n *\n * Takes the MACHINE (not the bare `update` record) so the reducer-vs-\n * transitions branch honors the authoritative `__form` tag via `msgKeysOf` —\n * the same classification production `run` uses (#275).\n *\n * - **Reducer form** — keys of the top-level record ARE the Msg variants.\n * - **Transitions form** — keys of any single state's inner record. Every\n *   state's inner record must cover every Msg variant (mapped-type\n *   discipline), so reading the first state's keys is equivalent to reading\n *   the union.\n *\n * @example\n *   import { auditBackgroundMachine } from \"./reducer\";\n *   msgTypeKeys(auditBackgroundMachine);\n *   // → [\"start_audit\", \"stop_audit\", \"window_created\", ...]\n */\nexport function msgTypeKeys<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n>(machine: {\n  update:\n    | Reducer<S, M, C>\n    | ([S] extends [{ type: string }] ? Transitions<S, M, C> : never);\n  __form?: UpdateForm;\n}): readonly string[] {\n  return msgKeysOf(machine);\n}\n"]}
+{"version":3,"sources":["../../src/pbt/arbitraries/ctx.ts","../../src/pbt/arbitraries/msg.ts","../../src/pbt/arbitraries/sequence.ts","../../src/pbt/runners/replay-fold.ts","../../src/pbt/runners/property.ts","../../src/pbt/util/msg-keys.ts"],"names":["fc2","fc3"],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// `stubCtxThrowingProxy<Ctx>()` — a Proxy that satisfies the Ctx type-shape\n// at compile time but throws on every property access at runtime.\n//\n// Why this exists: PBT runs the pure reducer surface ONLY — `replay` never\n// invokes `interpret` and never starts a Sub, so Ctx should never be\n// dereferenced during property generation. But the substrate's `replay`\n// signature requires a `ctx: Ctx` value at compile time (it forwards ctx\n// into `init`, which on some machines IS pure but on others reads ctx). A\n// hand-rolled `{} as Ctx` would silently pass through any accidental ctx\n// access — exactly the silent footgun this proxy catches.\n//\n// Open question 2 (design doc): we ship this as the default. Tests that\n// genuinely need a working ctx (because their `init` reads from it) can\n// pass a real ctx value instead — the proxy is opt-in, not load-bearing.\n//\n// Strengthens invariant 6 (no silent failures — accidental ctx reads\n// produce a useful error, not a `undefined.foo` confusion later).\n// ---------------------------------------------------------------------------\n\n/**\n * Build a Ctx value whose every property access throws. Use as the `ctx`\n * argument to PBT runners when the reducer under test is pure (does not\n * read from ctx). Accidental ctx access during property generation\n * surfaces as a labelled error instead of a silent `undefined` or\n * downstream type-error.\n *\n * Returns a typed `Ctx` (via `as unknown as Ctx`) — the proxy satisfies the\n * type-shape requirement at the call site; the runtime contract is\n * \"throw on first read.\" The `as unknown` cast is the one boundary cast\n * this helper requires; the proxy is structurally a `Ctx` for every\n * property accessor.\n *\n * @example\n *   import { stubCtxThrowingProxy } from \"../index\";\n *   const ctx = stubCtxThrowingProxy<MyCtx>();\n *   propertyTerminates(machine, ctx, ...);\n *   // If anything reads ctx.someField during the run, an Error throws:\n *   //   \"@demlik/tea/pbt: ctx access denied (PBT operates on the pure\n *   //    reducer; ctx field 'someField' was read)\"\n */\nexport function stubCtxThrowingProxy<Ctx>(): Ctx {\n  const handler: ProxyHandler<object> = {\n    get(_target, prop: string | symbol): unknown {\n      // Allow vitest / fast-check internals to introspect via Symbol-keyed\n      // checks (e.g. Symbol.toStringTag, Symbol.iterator). Returning\n      // undefined on symbol keys keeps property-tree walks cheap; the\n      // throw fires on real domain field reads.\n      if (typeof prop === \"symbol\") return undefined;\n      // Some shrinkers / pretty-printers in fast-check probe a small set\n      // of conventional field names (`toJSON`, `toString`, `valueOf`,\n      // `then` — the last for thenable-check). Return undefined for those\n      // so the proxy doesn't fail a probe before the property body runs.\n      if (\n        prop === \"toJSON\" ||\n        prop === \"toString\" ||\n        prop === \"valueOf\" ||\n        prop === \"then\"\n      ) {\n        return undefined;\n      }\n      throw new Error(\n        `@demlik/tea/pbt: ctx access denied (PBT operates on the pure reducer; ` +\n          `ctx field '${prop}' was read). Pass a real ctx value if the reducer's ` +\n          `init reads from ctx.`,\n      );\n    },\n    has(): boolean {\n      return false;\n    },\n    ownKeys(): ArrayLike<string | symbol> {\n      return [];\n    },\n  };\n  return new Proxy({}, handler) as unknown as Ctx;\n}\n","// ---------------------------------------------------------------------------\n// Msg arbitrary builders.\n//\n// `MsgArbitraryTable<M>` is a strict mapped type — every Msg variant must\n// have an arbitrary entry, keyed by `M[\"type\"]`, narrowing the arbitrary's\n// `T` to `Extract<M, { type: K }>`. This mirrors the load-bearing discipline\n// of `Reducer<S, M, C>` and `Transitions<S, M, C>` in the substrate: adding\n// a Msg variant without an arbitrary fails to compile, not at runtime.\n//\n// `arbMsg(table, opts?)` collapses the table into a single `fc.Arbitrary<M>`\n// via `fc.oneof`. Optional per-variant weighting for sequence-skew tests.\n//\n// `arbConstantMsg(type)` / `arbRecordMsg(type, fields)` are sugar over\n// `fc.constant({ type })` / `fc.record({ type: fc.constant(type), ...fields })`.\n// They exist because every Msg variant arbitrary either (a) carries no\n// payload — `arbConstantMsg(\"stop\")` — or (b) carries a record of fields —\n// `arbRecordMsg(\"tick\", { now: fc.integer() })`. Naming the two shapes\n// prevents callers from hand-rolling `fc.record({ type: fc.constant(\"...\") })`\n// inconsistently across test files.\n//\n// Open question 1 from the design doc (strict vs Partial table): strict by\n// default. The mapped type catches drift at compile time; `arbMsgPartial`\n// sugar is a future addition iff friction becomes real.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\n\n/**\n * Strict per-variant Msg arbitrary table. Mapped type: every key in\n * `M[\"type\"]` MUST have an arbitrary entry whose `T` is the narrowed\n * variant. Adding a new Msg variant without an entry is a compile error\n * (same load-bearing discipline as `Reducer<S, M, C>` in the substrate).\n *\n * @example\n *   type Msg = { type: \"start\" } | { type: \"tick\"; now: number };\n *   const table: MsgArbitraryTable<Msg> = {\n *     start: arbConstantMsg(\"start\"),\n *     tick: arbRecordMsg(\"tick\", { now: fc.integer({ min: 0 }) }),\n *   };\n */\nexport type MsgArbitraryTable<M extends { type: string }> = {\n  [K in M[\"type\"]]: fc.Arbitrary<Extract<M, { type: K }>>;\n};\n\n/**\n * Build a single `fc.Arbitrary<M>` from a `MsgArbitraryTable<M>`. Picks one\n * variant per generation via `fc.oneof`; optional per-variant `weights`\n * bias the distribution (default uniform).\n *\n * @param table   Per-variant arbitrary table (strict — every variant required).\n * @param opts    Optional bias: `weights` is a `Partial<Record<M[\"type\"], number>>`.\n *                Variants without an explicit weight default to 1.\n *\n * @example\n *   const msgArb = arbMsg<Msg>({\n *     start: arbConstantMsg(\"start\"),\n *     tick:  arbRecordMsg(\"tick\", { now: fc.integer() }),\n *     stop:  arbConstantMsg(\"stop\"),\n *   }, { weights: { tick: 5, start: 1, stop: 1 } });\n */\nexport function arbMsg<M extends { type: string }>(\n  table: MsgArbitraryTable<M>,\n  opts?: { weights?: Partial<Record<M[\"type\"], number>> },\n): fc.Arbitrary<M> {\n  const weights = opts?.weights;\n  const entries = Object.entries(table) as [M[\"type\"], fc.Arbitrary<M>][];\n  if (entries.length === 0) {\n    throw new Error(\"@demlik/tea/pbt: arbMsg table is empty\");\n  }\n  const weighted = entries.map(([key, arb]) => ({\n    arbitrary: arb,\n    weight: weights?.[key] ?? 1,\n  }));\n  return fc.oneof(...weighted);\n}\n\n/**\n * Build a payload-free Msg variant arbitrary. Sugar for\n * `fc.constant({ type })` that narrows the result to `{ type: T }` literal.\n *\n * @example\n *   arbConstantMsg(\"stop\") // fc.Arbitrary<{ type: \"stop\" }>\n */\nexport function arbConstantMsg<T extends string>(\n  type: T,\n): fc.Arbitrary<{ type: T }> {\n  return fc.constant({ type });\n}\n\n/**\n * Build a record-shaped Msg variant arbitrary. Sugar for\n * `fc.record({ type: fc.constant(type), ...fields })` that stamps the\n * discriminator literal and combines with the per-field arbitraries.\n *\n * @example\n *   arbRecordMsg(\"tick\", { now: fc.integer({ min: 0 }) })\n *   // fc.Arbitrary<{ type: \"tick\"; now: number }>\n */\nexport function arbRecordMsg<T extends string, R>(\n  type: T,\n  fields: { [K in keyof R]: fc.Arbitrary<R[K]> },\n): fc.Arbitrary<{ type: T } & R> {\n  // `fc.record` builds an arbitrary of the merged-shape record. The\n  // `type: fc.constant(type)` field stamps the literal discriminator;\n  // the spread of `fields` provides every payload field's arbitrary.\n  //\n  // The intermediate `as Record<string, fc.Arbitrary<unknown>>` is the\n  // single load-bearing cast — fc.record's parameter type is invariant in\n  // its inferred field shape, and the merged literal-and-generic spread\n  // doesn't unify with the strict `{ [K in keyof R]: Arbitrary<R[K]> }`\n  // shape TS computes for us. The outer cast to `fc.Arbitrary<{ type: T }\n  // & R>` restates the result shape we know to be correct at this\n  // boundary. Mirrors the same discipline `fc.record` callers use\n  // throughout the prior-art branch.\n  const recordArbitraries: Record<string, fc.Arbitrary<unknown>> = {\n    type: fc.constant(type),\n    ...(fields as Record<string, fc.Arbitrary<unknown>>),\n  };\n  return fc.record(recordArbitraries) as unknown as fc.Arbitrary<\n    { type: T } & R\n  >;\n}\n","// ---------------------------------------------------------------------------\n// Msg-sequence arbitraries.\n//\n// `arbMsgSequence(msgArb, opts)` produces `fc.Arbitrary<readonly M[]>` —\n// fast-check's default-shrinker handles the array; the per-element shrinker\n// inside `msgArb` shrinks each variant. Optional `prefix` is prepended\n// verbatim (used by Test A: \"the bug-triggering Msg leads the sequence\").\n//\n// `arbGuidedSequence` is the state-aware sequence builder. In v1 it throws\n// — Phase 6 of the design doc lands the `fc.commands`-backed implementation.\n// The export exists today so the surface is forward-compatible: consumers\n// that need state-aware generation get a useful error pointing at the\n// design doc instead of \"is not a function.\"\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\n\n/**\n * Build an arbitrary of Msg sequences over a per-Msg arbitrary. Optionally\n * bounded in length and / or prefixed with a fixed sequence.\n *\n * - `minLength` (default 0) and `maxLength` (default 30) bound the random\n *   array length. `prefix` is prepended AFTER the random tail is built; the\n *   final length is `prefix.length + tail.length`.\n * - `prefix` is the load-bearing escape hatch for \"the first msg is the\n *   one that exercises the cell I care about\" (e.g. Test A's\n *   `[{ type: \"ws:client:hello\" }]` prefix to land in the\n *   `auditing.ws:client:hello` cell on the first transition).\n *\n * @example\n *   arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 });\n *   arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }], maxLength: 20 });\n */\nexport function arbMsgSequence<M extends { type: string }>(\n  msgArb: fc.Arbitrary<M>,\n  opts?: {\n    readonly minLength?: number;\n    readonly maxLength?: number;\n    readonly prefix?: readonly NoInfer<M>[];\n  },\n): fc.Arbitrary<readonly M[]> {\n  const minLength = opts?.minLength ?? 0;\n  const maxLength = opts?.maxLength ?? 30;\n  const prefix = opts?.prefix ?? [];\n  const tail = fc.array(msgArb, { minLength, maxLength });\n  if (prefix.length === 0) return tail;\n  return tail.map((arr) => [...prefix, ...arr]);\n}\n\n/**\n * State-aware Msg sequence arbitrary — generates only msgs whose\n * precondition holds in the current state. Backed by `fc.commands`\n * internally. Planned for a later phase.\n *\n * **NOT IMPLEMENTED IN v1.** The export exists today so the surface is\n * forward-compatible; this ships in a later phase alongside\n * shrinkers. Calling it throws.\n */\nexport function arbGuidedSequence<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  _machine: Machine<S, M, C, U, Ctx>,\n  _ctx: Ctx,\n  _cells: {\n    [K in M[\"type\"]]?: (\n      state: S,\n    ) => fc.Arbitrary<Extract<M, { type: K }>> | null;\n  },\n  _opts?: { maxLength?: number },\n): fc.Arbitrary<readonly M[]> {\n  throw new Error(\n    \"@demlik/tea/pbt: arbGuidedSequence is not implemented in v1. \" +\n      \"Use arbMsgSequence with \" +\n      \"an unguided arbMsg table for now; states that don't accept a given \" +\n      \"msg should noop in the reducer (mapped-type discipline).\",\n  );\n}\n","// ---------------------------------------------------------------------------\n// `foldEvents` — pure deterministic fold over a Msg sequence.\n//\n// PBT needs the per-step (prev/msg/next/cmds) structure to assert\n// step-shaped invariants. The substrate's `replay(machine, opts)` returns\n// only final state + cumulative cmds — insufficient. We use `replay` for\n// the boot step (calls `machine.init(loaded, ctx)` faithfully) then walk\n// msgs ourselves through `applyCell`, the substrate's own cell dispatch.\n//\n// Why walk cells directly instead of looping `replay` once per msg with\n// `loaded: prevState`? Because `init(loaded)` runs every call, and on\n// machines with non-trivial init transforms (e.g. the audit machine's\n// `auditing → attach_debugger` resume cell) that would either (a) re-fire\n// the transform on every step, or (b) require fragile cmd-subtraction to\n// isolate this step's cmds. Calling the cells directly keeps the fold pure\n// and the cmds per-step exactly.\n//\n// Dispatches through `applyCell` — the single primitive `run`/`replay` use —\n// so form classification agrees with production by construction (#275).\n//\n// `foldEvents` does NOT call `interpret`, does NOT touch a Store, does NOT\n// start Subs. The reducer surface is the contract.\n// ---------------------------------------------------------------------------\n\nimport {\n  applyCell,\n  type Cmd,\n  type Machine,\n  replay,\n  type Sub,\n} from \"../../index\";\n\n/**\n * One unit in a fold trace — the four pieces of data a property\n * invariant typically asserts on. `prev` is the state before the msg\n * applied; `next` is the state after; `cmds` is the cmds emitted by this\n * single step (NOT the running total).\n */\nexport interface Step<S, M, C> {\n  readonly prev: S;\n  readonly msg: M;\n  readonly next: S;\n  readonly cmds: readonly C[];\n}\n\n/**\n * Fold a Msg sequence through a machine's pure reducer, returning the\n * per-step trace, every state in order, and the final state. Initial\n * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.\n * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds\n * are NOT included in any `Step` (they're the boot moment, not a Msg).\n *\n * @param machine  The machine under test.\n * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when\n *                 init is pure. Pass a real ctx if init reads from it.\n * @param loaded   Optional pre-init snapshot (the `loaded` arg to\n *                 `machine.init`). Defaults to `null` (fresh boot).\n * @param msgs     The Msg sequence to fold.\n *\n * @example\n *   const { states, steps, finalState } = foldEvents(machine, ctx, null, [\n *     { type: \"start\" }, { type: \"tick\" }, { type: \"stop\" },\n *   ]);\n *   // steps[1] = { prev: { type: \"counting\", n: 0 }, msg: { type: \"tick\" }, ... }\n */\nexport function foldEvents<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  loaded: NoInfer<S> | null,\n  msgs: readonly NoInfer<M>[],\n): {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n} {\n  // Boot through `replay` so `init` runs faithfully and we honor the\n  // substrate's loaded-snapshot contract (init may transform the loaded\n  // value before the first Msg lands — e.g. the audit machine flips\n  // `debuggerAttached: false` on resume).\n  const { state: initialState } = replay(machine, {\n    msgs: [],\n    ctx,\n    loaded: loaded ?? null,\n  });\n\n  // Per-msg dispatch goes through `applyCell` — the same primitive `run` and\n  // `replay` use — so this runner classifies the update form identically to\n  // production (`formOf` honors the `__form` tag; #275).\n  const states: S[] = [initialState];\n  const steps: Step<S, M, C>[] = [];\n  let current = initialState;\n\n  for (const msg of msgs) {\n    const [next, emitted] = applyCell<S, M, C>(machine, current, msg);\n    steps.push({ prev: current, msg, next, cmds: [...emitted] });\n    states.push(next);\n    current = next;\n  }\n\n  return { states, steps, finalState: current };\n}\n","// ---------------------------------------------------------------------------\n// Property runners — three thin wrappers over `fc.assert(fc.property(...))`\n// that fold a generated Msg sequence through the machine via `foldEvents`\n// and pipe the result into a TEA-shaped predicate.\n//\n//   - `propertyTerminates` — every sequence ends in a terminal state.\n//   - `propertyInvariant`  — predicate holds on every (prev, msg, next, cmds) step.\n//   - `propertyTrace`      — predicate holds on the full (trace, final) shape.\n//\n// Each runner accepts `numRuns` (passed through to fast-check), an optional\n// `loaded` snapshot (forwarded to `foldEvents`), and the Msg-sequence\n// arbitrary. They return `void`; failures throw via fast-check's standard\n// shrinking output.\n//\n// Default shrinker is fast-check's built-in (open question 4): drop-msg /\n// prefix shrinkers can be layered later but are opt-in, not default. The\n// built-in shrinker handles array-shape shrinking + per-element variant\n// shrinking automatically.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\nimport { foldEvents, type Step } from \"./replay-fold\";\n\n/** Common options shared by every property runner. */\ninterface PropertyOpts<S> {\n  /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */\n  readonly loaded?: S | null;\n  /** Number of generated sequences to test. Forwarded to `fc.assert`. */\n  readonly numRuns?: number;\n  /** Optional fast-check seed for reproducibility. */\n  readonly seed?: number;\n}\n\n/** The `foldEvents` result a runner's `check` inspects. */\ntype FoldResult<S, M, C> = {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n};\n\n/**\n * Build the fast-check parameters shared by every runner: the 200-default\n * `numRuns` plus an optional `seed`. Single source of truth so a change to\n * the default lands in one place.\n */\nfunction resolveFcParams<M>(\n  opts: PropertyOpts<unknown> | undefined,\n): fc.Parameters<[readonly M[]]> {\n  return {\n    numRuns: opts?.numRuns ?? 200,\n    ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),\n  };\n}\n\n/**\n * The fold+assert core every runner shares: assert `check` over each\n * generated Msg sequence, folded once through the machine via `foldEvents`.\n * `check` throws on failure so the error message carries the offending\n * shape into fast-check's shrunk counter-example.\n */\nfunction runProperty<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: Ctx,\n  seqArb: fc.Arbitrary<readonly M[]>,\n  opts: PropertyOpts<S> | undefined,\n  check: (result: FoldResult<S, M, C>) => void,\n): void {\n  fc.assert(\n    fc.property(seqArb, (msgs) => {\n      check(foldEvents(machine, ctx, opts?.loaded ?? null, msgs));\n    }),\n    resolveFcParams<M>(opts),\n  );\n}\n\n/**\n * Assert every generated Msg sequence ends in a terminal state. `terminal`\n * is the predicate that names the acceptable final states (often\n * `(s) => s.type === \"done\" || s.type === \"idle\"`).\n *\n * The \"every sequence\" property catches stuck states (machine gets to a\n * non-terminal state and no further msg can escape) AND silent loops\n * (every msg variant is a noop from a given state).\n *\n * @example\n *   propertyTerminates(\n *     auditBackgroundMachine,\n *     stubCtxThrowingProxy<BackgroundCtx>(),\n *     arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 }),\n *     (s) => s.type === \"done\" || s.type === \"idle\",\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTerminates<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  terminal: (state: NoInfer<S>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ finalState }) => {\n    if (!terminal(finalState)) {\n      // Throwing here (vs returning false) lets the error message carry\n      // the offending final state — fast-check pretty-prints it inside\n      // the shrunk counter-example.\n      throw new Error(\n        `propertyTerminates: final state did not match terminal predicate. ` +\n          `Final: ${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n\n/**\n * Assert a predicate holds on EVERY transition step in a generated\n * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;\n * return true to accept, false (or throw) to fail.\n *\n * Use to pin a \"when X happens in state Y, cmd Z must be emitted\" rule.\n * The shrinker minimizes the offending sequence to the smallest Msg list\n * that still violates the predicate.\n *\n * @example\n *   // Pin the resume-handshake fix: `ws:client:hello` in auditing must\n *   // emit `send_ws { client:ready }`.\n *   propertyInvariant(\n *     auditBackgroundMachine, ctx,\n *     arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }] }),\n *     ({ prev, msg, cmds }) =>\n *       !(prev.type === \"auditing\" && msg.type === \"ws:client:hello\") ||\n *       cmds.some((c) => c.type === \"send_ws\" && c.msg.type === \"client:ready\"),\n *     { loaded: auditingState, numRuns: 200 },\n *   );\n */\nexport function propertyInvariant<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps }) => {\n    for (const step of steps) {\n      if (!invariant(step)) {\n        throw new Error(\n          `propertyInvariant: failed at step msg=${JSON.stringify(step.msg)} ` +\n            `prev=${JSON.stringify(step.prev)} next=${JSON.stringify(step.next)} ` +\n            `cmds=${JSON.stringify(step.cmds)}`,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Assert a predicate over the full trace plus the final state. Use when\n * the property is \"some Msg appeared in the trace before reaching the\n * final state\" or \"no two consecutive steps had the same state.type\" —\n * predicates that need the full sequence, not a single step.\n *\n * @example\n *   propertyTrace(\n *     machine, ctx, seqArb,\n *     (steps, final) =>\n *       final.type !== \"done\" ||\n *       steps.some((step) => step.msg.type === \"ws:audit:done\"),\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTrace<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  predicate: (\n    steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[],\n    finalState: NoInfer<S>,\n  ) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps, finalState }) => {\n    if (!predicate(steps, finalState)) {\n      throw new Error(\n        `propertyTrace: predicate failed on trace length=${steps.length}, ` +\n          `final=${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n","// ---------------------------------------------------------------------------\n// msgTypeKeys — read the Msg discriminant set at runtime from a machine's\n// Reducer record or Transitions table.\n//\n// TS Msg unions only exist at the type level; the discriminant strings are\n// erased at runtime. The reducer record / transitions table is the load-\n// bearing artifact that DOES carry the discriminants at runtime — its keys\n// (for Reducer) or any one cell's inner keys (for Transitions) are exactly\n// the set we need to build an `arbMsg` table without hand-listing them.\n//\n// Standalone helper: hand it a machine and it returns the Msg variants the\n// reducer/transitions record carries at runtime. `arbMsg` does NOT call it —\n// `MsgArbitraryTable<M>` enforces table coverage at compile time (adding a\n// variant without an arbitrary fails to compile, not at runtime). This helper\n// is for callers that want the discriminant set explicitly at runtime — e.g.\n// a test asserting a table covers every variant.\n// ---------------------------------------------------------------------------\n\nimport {\n  type Cmd,\n  msgKeysOf,\n  type Reducer,\n  type Transitions,\n  type UpdateForm,\n} from \"../../index\";\n\n/**\n * Extract the Msg discriminant set at runtime from a machine. Useful for\n * asserting that a user-supplied `MsgArbitraryTable<M>` covers every variant\n * the reducer can handle.\n *\n * Takes the MACHINE (not the bare `update` record) so the reducer-vs-\n * transitions branch honors the authoritative `__form` tag via `msgKeysOf` —\n * the same classification production `run` uses (#275).\n *\n * - **Reducer form** — keys of the top-level record ARE the Msg variants.\n * - **Transitions form** — keys of any single state's inner record. Every\n *   state's inner record must cover every Msg variant (mapped-type\n *   discipline), so reading the first state's keys is equivalent to reading\n *   the union.\n *\n * @example\n *   import { auditBackgroundMachine } from \"./reducer\";\n *   msgTypeKeys(auditBackgroundMachine);\n *   // → [\"start_audit\", \"stop_audit\", \"window_created\", ...]\n */\nexport function msgTypeKeys<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n>(machine: {\n  update:\n    | Reducer<S, M, C>\n    | ([S] extends [{ type: string }] ? Transitions<S, M, C> : never);\n  __form?: UpdateForm;\n}): readonly string[] {\n  return msgKeysOf(machine);\n}\n"]}

package/dist/persistence/index.d.ts

@@ -1,10 +1,9 @@
-import { T as Trace } from '../index-TvRb1KVf.js';
-export { B as BreadcrumbsOptions, a as Recorder, R as RecorderOptions, b as TraceAttachment, c as TraceBreadcrumb, d as breadcrumbsFromTrace, p as parseJSONL, r as recorder, t as traceAttachment } from '../index-TvRb1KVf.js';
-export { h as SnapshotConfig, d as SnapshotFailedMsg, i as SnapshotKnob, g as SnapshotLoadCmd, f as SnapshotLoadFailedMsg, e as SnapshotLoadedMsg, j as SnapshotPorts, c as SnapshotSavedMsg, a as SnapshotState, b as SnapshotStore, S as SnapshotWriteCmd, k as createSnapshot, s as snapshotFailed, l as snapshotLoad, m as snapshotLoadFailed, n as snapshotLoaded, o as snapshotSaved, p as snapshotWriteDef } from '../index-DMCeMPMJ.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import '../runtime-types-LWDoi943.js';
-import 'better-result';
-import 'zod';
+import { T as Trace } from '../index-DU6JpQ8G.js';
+export { B as BreadcrumbsOptions, a as Recorder, R as RecorderOptions, b as TraceAttachment, c as TraceBreadcrumb, d as breadcrumbsFromTrace, p as parseJSONL, r as recorder, t as traceAttachment } from '../index-DU6JpQ8G.js';
+export { c as SnapshotConfig, d as SnapshotFailedMsg, e as SnapshotKnob, f as SnapshotLoadCmd, g as SnapshotLoadFailedMsg, h as SnapshotLoadedMsg, b as SnapshotSavedMsg, a as SnapshotState, S as SnapshotWriteCmd, i as createSnapshot, s as snapshotLoadDef, j as snapshotWriteDef } from '../index-CjFDUBeq.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BbgtiXdg.js';
+import '../runtime-types-CiVpC0HN.js';
+import '@standard-schema/spec';
 
 /**
  * The outcome of {@link replayTrace}.

package/dist/persistence/index.js

@@ -1,6 +1,8 @@
-export { breadcrumbsFromTrace, deepEqual, parseJSONL, recorder, replayTrace, traceAttachment } from '../chunk-BLJ2JQSH.js';
-export { createSnapshot, snapshotFailed, snapshotLoad, snapshotLoadFailed, snapshotLoaded, snapshotSaved, snapshotWriteDef } from '../chunk-HUKZQX6U.js';
+export { breadcrumbsFromTrace, deepEqual, parseJSONL, recorder, replayTrace, traceAttachment } from '../chunk-BCTEOVOU.js';
+export { createSnapshot, snapshotLoadDef, snapshotWriteDef } from '../chunk-CIHSHLQX.js';
+import '../chunk-4LPY67E4.js';
+import '../chunk-GOX2CYIM.js';
+import '../chunk-CH5KTOEZ.js';
 import '../chunk-HWVW4AXC.js';
-import '../chunk-RQULHGYH.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/promise/index.d.ts

@@ -0,0 +1,186 @@
+import { C as Cmd, S as Sub, M as Machine, R as RunHandlers } from '../core-BbgtiXdg.js';
+import { B as BootingRuntime, C as CtxArg, S as Store, O as OnError, a as Supervision, T as TelemetrySink } from '../runtime-types-CiVpC0HN.js';
+import '@standard-schema/spec';
+
+/**
+ * @demlik/tea runtime — `run`: boot a machine and drive its serial dispatch loop
+ * on Promises; `driveToDone`: run one to its terminal State.
+ *
+ * `run` is assembly. The loop itself is `src/internal/engine/loop.ts` — a small
+ * core with no special case for any built-in, shared with the Effect engine —
+ * and every built-in is an extension of it (`src/internal/engine/builtins.ts`),
+ * built from `run`'s options in the order both engines share.
+ */
+
+declare function run<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx, E extends {
+    type: string;
+} = never>(machine: Machine<S, M, C, U, Ctx>, opts: CtxArg<Ctx> & NoInfer<RunHandlers<M, C, U, Ctx>> & {
+    store?: Store<S>;
+    onError?: OnError;
+    /**
+     * The clock that stamps `at` on a `Cmd.define`d effect's settled Msg at
+     * the interpret edge, and on each `telemetry` event. Defaults to
+     * `Date.now`. Inject a fixed one for a deterministic run; a `replay` log
+     * carries its own `at`s and never reads this.
+     */
+    clock?: () => number;
+    /**
+     * The SEMANTIC event projector. Maps one APPLIED transition `(msg, state)`
+     * to zero-or-more public events of `E`; `[]` skips the transition. Maps the
+     * machine's PRIVATE Msg vocabulary to NAMED events — the private names never
+     * reach `on`'s `E` surface. Omit → `E = never` and `on` is uncallable. PURE.
+     */
+    events?: (msg: M, state: S) => readonly E[];
+    /**
+     * Declared policy for a reducer (`update`) throw. Always surfaced via
+     * `onError` (`phase: "reduce"`); the strategy decides what the runtime does
+     * next. Defaults to `"stop"`. See `Supervision`.
+     */
+    supervision?: Supervision<S, M>;
+    /**
+     * The run-terminality predicate — makes the run's outcome first-class. Fed to
+     * `Runtime.result()` and `Runtime.done()`. PURE. Omit → never terminal.
+     */
+    terminal?: (state: S) => boolean;
+    /**
+     * A sink handed `{ seq, msgType, at }` for every applied transition —
+     * the observe-only telemetry `withTelemetry` used to add by wrapping the
+     * machine (#268). Fire-and-forget; see {@link TelemetrySink}.
+     */
+    telemetry?: TelemetrySink;
+    /**
+     * How long `stop()` waits for teardown work that returned a Promise (an
+     * async `release` in `defineManagedResource`, an async Sub cleanup) before
+     * giving up on it. Defaults to 5_000ms.
+     *
+     * `stop()` awaits those disposals so a host doing
+     * `await runtime.stop(); env.evict()` cannot drop the isolate mid-release —
+     * the leak the managed-resource battery exists to prevent, relocated to
+     * shutdown. The bound is what keeps a release that never settles from
+     * hanging the host: on expiry `stop()` reports a `DisposeTimeoutNotice`
+     * (warn-only, like every `RuntimeDiscardNotice`) and resolves anyway,
+     * because `stop()` resolving is a contract.
+     */
+    disposeTimeoutMs?: number;
+    /**
+     * Iteration cap for `idle()`'s quiescence wait. Defaults to 100_000. Test
+     * seam only. Production code must not set it.
+     *
+     * @internal test-only
+     */
+    __idleCap?: number;
+}): BootingRuntime<S, M, E>;
+/**
+ * The outside-in stop, as a PAIR. A signal is only cancellation if something can
+ * turn "aborted" into a transition this machine understands, and the kernel has
+ * no built-in cancel Msg any more than it has a built-in terminal set — so the
+ * `signal` and the `cancel` that reads it are one option, present together or
+ * absent together. A discriminated union rather than two optional fields, on the
+ * same reasoning as `AgentCompactionConfig`: a signal with no `cancel` is a stop
+ * button wired to nothing, and that is a state worth making unrepresentable
+ * rather than checking for.
+ */
+type DriveCancellation<S, M> = {
+    readonly signal?: undefined;
+    readonly cancel?: undefined;
+} | {
+    /**
+     * Abort the run through this signal. On abort the drive dispatches
+     * `cancel`'s Msg and resolves on the State that lands — it does NOT reject,
+     * and a cancellation is never a `DriveFailedError`. Already aborted when
+     * the drive is called → the cancel Msg goes in place of `start`, so the
+     * run ends without the start's effects ever firing.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * The Msg that settles this machine as cancelled, chosen off the current
+     * State exactly as `start` is. PURE. It must land a State `isTerminal`
+     * holds for — the drive resolves on the terminal predicate, not on the
+     * abort — and that State should be DURABLE, or a reload resumes the run
+     * its caller stopped.
+     */
+    readonly cancel: (state: S) => M;
+};
+/** Options for `driveToDone`. */
+type DriveToDoneOptions<S, M extends {
+    type: string;
+} = never> = DriveCancellation<S, M> & {
+    /**
+     * Marks a terminal State as a FAILURE. A State this holds for ends the drive
+     * like any terminal one — the runtime is stopped — but the drive REJECTS with
+     * `DriveFailedError` carrying it instead of resolving. A failed State is
+     * terminal by definition; it need not also satisfy `isTerminal`. Omit → the
+     * drive never rejects on State, only on a runtime error.
+     */
+    readonly failed?: (state: S) => boolean;
+};
+/**
+ * Drive a machine from `start` to its terminal State in one call, then tear the
+ * runtime down. The one-shot shape every "run this machine to done" test and
+ * caller boundary otherwise hand-wires as six steps — `await ready`, `observe`,
+ * park a promise, `dispatch(start)`, `getState()`, `stop()` — with the observer
+ * leak and the forgotten `stop` those six steps invite.
+ *
+ * Takes the handle `run()` returns (a `Runtime` extends it, so a booted one is
+ * accepted too), awaits `ready`, dispatches `start`, and resolves with the first
+ * State for which `isTerminal` holds. A machine that boots already terminal (a
+ * rehydrated finished run) resolves on its boot State and `start` is never
+ * dispatched — a finished run has nothing to set in motion. `start` may be a
+ * function of the boot State instead of a Msg: a machine rehydrated MID-run
+ * needs its resume Msg, not its start Msg, and only the boot State says which
+ * (the agent's `agent_boot` vs `agent_start` is the case in point). The
+ * observer is detached and `stop()` awaited on EVERY exit: resolve, `failed`,
+ * a stall, a boot or dispatch throw, the quiescence cap.
+ *
+ * Rejections are typed, never silent:
+ *   - `DriveFailedError<S>` when `opts.failed` marks the final State — the State
+ *     rides on `error.state`.
+ *   - `DriveStalledError<S>` when `start`'s follow-up chain quiesces on a State
+ *     that is neither terminal nor `failed` and the runtime has no live Sub and
+ *     no Cmd in flight — nothing inside it can deliver another transition, so
+ *     waiting would be a hang with the runtime leaked. The stalled State rides
+ *     on `error.state`. A machine that CAN still move is not stalled: a live Sub
+ *     that delivers the terminal Msg after the dispatch
+ *     quiesces keeps the drive waiting, and it resolves on that State. What the
+ *     runtime cannot see — a dispatch from outside it after quiescence — does
+ *     not count as live; a machine that depends on one declares it as a Sub.
+ *   - `QuiescenceTimeoutError` when `start`'s follow-up chain never settles —
+ *     the SAME cap `dispatch` and `idle()` already reject on (invariant 6), not a
+ *     second clock. A livelocking machine surfaces as its own failure class.
+ *   - the boot error, or whatever `dispatch(start)` rejects with, otherwise.
+ *
+ * `isTerminal` is caller-supplied, exactly as `run()`'s `terminal` option is —
+ * the kernel has no built-in terminal-set concept and this does not add one.
+ *
+ * Cancellation is the same story: `{ signal, cancel }` stops the drive from
+ * outside, and it settles the run rather than escaping it. On abort the drive
+ * dispatches `cancel`'s Msg and RESOLVES on the terminal State that transition
+ * lands — no rejection, no `DriveFailedError`, no `AbortError`. That is the whole
+ * point of routing a stop through the Model: the outcome is durable, so a killed
+ * process resumes reading a run that ended instead of restarting one someone
+ * stopped. A cancel that THROWS is the one abort that rejects: it lands
+ * no State, so its error is what the drive has to report — and that holds
+ * whether the `cancel` function throws synchronously or the fold it produced
+ * throws later, since both leave the run with no State to settle on. A State the
+ * caller's `failed` predicate marks rejects on an abort exit exactly as it does
+ * anywhere else. In-flight effects are not recalled — a promise cannot be cancelled —
+ * so they settle to their own end and `stop()` drains them as it always did;
+ * keeping their results off the public channels is the machine's own business.
+ * Omit the pair and every path here behaves exactly as it did before.
+ *
+ * @param handle     the handle `run(machine, opts)` returned.
+ * @param start      the Msg that sets the run in motion, or a function choosing
+ *                   it off the boot State. PURE.
+ * @param isTerminal the terminal predicate over the machine's State. PURE.
+ * @param opts       an optional `failed` predicate and an optional
+ *                   `{ signal, cancel }` pair (see {@link DriveToDoneOptions}).
+ */
+declare function driveToDone<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never>(handle: BootingRuntime<S, M, E>, start: M | ((booted: S) => M), isTerminal: (state: S) => boolean, opts?: DriveToDoneOptions<S, M>): Promise<S>;
+
+export { type DriveToDoneOptions, driveToDone, run };

package/dist/promise/index.js

@@ -0,0 +1,5 @@
+export { driveToDone, run } from '../chunk-WT5PBPLB.js';
+import '../chunk-5XU6ZJO2.js';
+import '../chunk-CH5KTOEZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/promise/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/protocol-ClRZBhHQ.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The closed set of cross-module Msg/Cmd discriminant strings. Declared `as
+ * const` so each entry is usable as both a value (construction / reducer keys /
+ * switch labels) and, via `typeof MsgType.X`, a literal type (`readonly type:`
+ * fields). The single source of truth for issue #60.
+ */
+declare const MsgType: {
+    /** The "run the port for `key`" effect Cmd resilient-call emits. */
+    readonly ResilientRun: "resilient_run";
+    /**
+     * PRIVATE success settle Msg (read only by `agentEvents`, #47). The engine
+     * mints it from the run Cmd's outcome (ADR 0021), so it is `<run>_ok`.
+     */
+    readonly ResilientOk: "resilient_run_ok";
+    /** Failure settle Msg — routed to `settle` (back off via retry). */
+    readonly ResilientErr: "resilient_run_err";
+    /** Begin a run. */
+    readonly AgentStart: "agent_start";
+    /** PRIVATE tool-fan-out success settle Msg (read only by `agentEvents`, #47). */
+    readonly AgentToolOk: "agent_tool_ok";
+    /** Tool-fan-out failure settle Msg. */
+    readonly AgentToolErr: "agent_tool_err";
+    /**
+     * Re-fire the one outstanding effect on rehydrate (the do↔agent seam). Fired
+     * by `do/host`'s `autoBoot` via the typed `agentBootMsg` constructor, matched
+     * by the agent reducer — see `AgentBootPort` in `../agent`.
+     */
+    readonly AgentBoot: "agent_boot";
+    /**
+     * Stop the run from outside and settle it `cancelled` — what an `AbortSignal`
+     * handed to `driveToDone` / a defined agent's `run` dispatches on abort. A
+     * transition, never a throw: the outcome lands in the Model, so a reload reads
+     * a run that ended rather than one to resume.
+     */
+    readonly AgentCancel: "agent_cancel";
+    /**
+     * The "summarize the oldest N turns" effect Cmd the agent emits when its
+     * `CompactionPolicy` asks to compact before a brain call. A DEDICATED
+     * round-trip (design B1), distinct from the brain call's `resilient_run`, so
+     * compaction is its own honest `Awaiting` state — see `../agent`.
+     */
+    readonly CompactRun: "compact_run";
+    /** Compaction round-trip resolved — carries the summary text the fold-back folds. */
+    readonly CompactOk: "compact_ok";
+    /** Compaction round-trip failed (exhausted retry) — surfaced as data, not a stall. */
+    readonly CompactErr: "compact_err";
+    /** The 401 the consumer dispatches when a guarded call comes back unauthorized. */
+    readonly Unauthorized: "unauthorized";
+};
+/** The union of every discriminant string in the protocol. */
+type MsgTypeValue = (typeof MsgType)[keyof typeof MsgType];
+
+export { MsgType as M, type MsgTypeValue as a };

package/dist/react/index.d.ts

@@ -1,7 +1,6 @@
-import { S as Store, R as Runtime } from '../runtime-types-LWDoi943.js';
-import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from '../core-CTzMJ82M.js';
-import 'better-result';
-import 'zod';
+import { E as EngineRun, S as Store, b as BootedRunHandle } from '../runtime-types-CiVpC0HN.js';
+import { C as Cmd, S as Sub, R as RunHandlers, M as Machine } from '../core-BbgtiXdg.js';
+import '@standard-schema/spec';
 
 /**
  * @packageDocumentation
@@ -27,28 +26,45 @@ import 'zod';
  */
 
 /**
- * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`
+ * Options passed to `useMachine`. `run` is the engine's `run` — `run` from
+ * `@demlik/tea/promise`, or any engine's; the hook imports no engine. `ctx`
  * is required (every machine has one), `store` is optional (omit it for
- * volatile-state machines).
+ * volatile-state machines), and the handlers are the ones `run` takes beside
+ * the machine: `interpret` (required once the machine emits a Cmd) and the
+ * `subscribe` runners (required once the machine declares a Sub type other
+ * than the built-in `timer`) — see {@link RunHandlers}. Same requiredness as
+ * `run`, because it is the same type.
  *
- * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,
- * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`
+ * **The handlers are read fresh, never memoized on.** A handler table written
+ * inline in the component is a new object every render; keying the runtime on
+ * it would reboot the machine on every render. So `useMachine` hands `run` a
+ * table that looks each cell up on the latest render's `interpret` /
+ * `subscribe` at the moment a Cmd runs or a Sub starts — a handler may close
+ * over props and state freely.
+ *
+ * **Identity matters.** The runtime is memoized on `[machine, opts.run,
+ * opts.ctx, opts.store]`. A new `ctx` reference rebuilds the runtime, and so
+ * does a new `run` — pass the engine's own function, not an inline wrapper. Always `useMemo`
  * (or otherwise stabilize) the ctx at the call site. See README.
  *
  * Forgetting to is no longer silent: the replaced runtime's `stop()` reports
  * `RuntimeDiscardedError` under `phase: "discard"` when Cmds were still in
  * flight, which the substrate's default sink warns about (issue #365).
  */
-interface UseMachineOpts<S, Ctx> {
+type UseMachineOpts<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx> = {
+    run: EngineRun<S, M, C, U, Ctx>;
     ctx: Ctx;
     store?: Store<S>;
-}
+} & RunHandlers<M, C, U, Ctx>;
 /**
- * Build and own a `Runtime<S, M>` for the lifetime of the component mount.
+ * Build and own a run of `machine` for the lifetime of the component mount, on
+ * the engine whose `run` the caller hands in.
  *
- * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,
- *   opts.store])` — runtime is recreated when ANY of the three identities
- *   change.
+ * - Builds via `useMemo(() => opts.run(machine, opts), [machine, opts.run,
+ *   opts.ctx, opts.store])` — the run is recreated when ANY of those
+ *   identities change.
  * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,
  *   runtime.getState)` — tearing-free under React 18 concurrent rendering.
  * - On unmount (or any dep change), `useEffect` cleanup calls
@@ -61,9 +77,10 @@ interface UseMachineOpts<S, Ctx> {
  */
 declare function useMachine<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: UseMachineOpts<S, Ctx & RequiredCtx<C>>): [S, (msg: M) => Promise<void>];
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: NoInfer<UseMachineOpts<S, M, C, U, Ctx>>): [S, (msg: M) => Promise<void>];
 /**
- * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.
+ * Lower-level escape hatch: consume an externally-built, booted run — any
+ * engine's {@link BootedRunHandle} (the Promise engine's `Runtime` is one).
  *
  * Use this when the runtime is owned by something OTHER than the component —
  * a parent component, a test harness, a singleton. **The component does NOT
@@ -77,6 +94,8 @@ declare function useMachine<S, M extends {
  */
 declare function useRuntime<S, M extends {
     type: string;
-}>(runtime: Runtime<S, M>): [S, (msg: M) => Promise<void>];
+}, E extends {
+    type: string;
+} = never>(runtime: BootedRunHandle<S, M, E>): [S, (msg: M) => Promise<void>];
 
 export { type UseMachineOpts, useMachine, useRuntime };

package/dist/react/index.js

@@ -1,12 +1,27 @@
-import { run } from '../chunk-RQULHGYH.js';
-import { useMemo, useRef, useReducer, useSyncExternalStore, useEffect } from 'react';
+import { useRef, useMemo, useReducer, useSyncExternalStore, useEffect } from 'react';
 
 function useMachine(machine, opts) {
+  const run = opts.run;
   const ctx = opts.ctx;
   const store = opts.store;
+  const handlersRef = useRef(opts);
+  handlersRef.current = opts;
+  const handlers = useMemo(
+    () => ({
+      interpret: latestTable(
+        () => handlersRef.current.interpret
+      ),
+      subscribe: latestTable(() => handlersRef.current.subscribe)
+    }),
+    []
+  );
   const booting = useMemo(
-    () => run(machine, { ctx, store }),
-    [machine, ctx, store]
+    () => run(machine, {
+      ctx,
+      store,
+      ...handlers
+    }),
+    [machine, run, ctx, store, handlers]
   );
   const readyRef = useRef(null);
   const [, markBooted] = useReducer((tick) => tick + 1, 0);
@@ -41,6 +56,14 @@ function useMachine(machine, opts) {
   }, [booting]);
   return [state, booting.dispatch];
 }
+function latestTable(current) {
+  return new Proxy(
+    {},
+    {
+      get: (_target, type) => current()?.[type]
+    }
+  );
+}
 function useRuntime(runtime) {
   const state = useSyncExternalStore(
     runtime.subscribe,