@demlik/tea 0.20.0 → 0.22.0

package/dist/paginate/index.d.ts

@@ -1,9 +1,9 @@
-import { C as Cmd, b as CmdDef, T as TimerDeps } from '../core-CtvAyPpH.js';
+import { C as Cmd, b as CmdDef, T as TimerDeps } from '../core-DNDAEhO2.js';
 import { RetryPolicy } from '../retry-backoff/index.js';
-import { a as DeadlineSub } from '../index-CVU7SK3a.js';
-import { b as ResilientState, a as ResilientTimerMsg, R as RunCmd, F as FailMsg, S as SucceedMsg, g as CircuitConfig, l as RateLimitConfig, m as DeadlineConfig } from '../index-CKtEKGyp.js';
+import { a as DeadlineSub } from '../index-Cg0QXnzf.js';
+import { b as ResilientState, a as ResilientTimerMsg, R as RunCmd, F as FailMsg, S as SucceedMsg, g as CircuitConfig, l as RateLimitConfig, m as DeadlineConfig } from '../index-C92SgNWz.js';
 import '@standard-schema/spec';
-import '../types-CXNzlbAg.js';
+import '../types-S53WDy_h.js';
 
 /**
  * internal/paginate/paginator — the cursor/offset/page-token walk loop as pure

package/dist/paginate/index.js

@@ -1,9 +1,9 @@
-export { PAGE_KEY, createPaginatedWalk, defaultPaginatorPolicy, drain, initPaginator, isDone, liftWalk, recordPage, resume, start } from '../chunk-FTCYY2DO.js';
-import '../chunk-72CN3VPY.js';
-import '../chunk-TAKPC6SD.js';
+export { PAGE_KEY, createPaginatedWalk, defaultPaginatorPolicy, drain, initPaginator, isDone, liftWalk, recordPage, resume, start } from '../chunk-CPE5ZQXQ.js';
+import '../chunk-NFOGYDRS.js';
+import '../chunk-UGTC33VH.js';
 import '../chunk-VBDU4JL6.js';
 import '../chunk-4LPY67E4.js';
-import '../chunk-DVNXEB7V.js';
-import '../chunk-RKVUVALV.js';
+import '../chunk-BVFS3ICC.js';
+import '../chunk-A3QPMX5M.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/parity/index.d.ts

@@ -1,16 +1,16 @@
-import { B as BootingRuntime } from '../runtime-types-DEluQgGO.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-CtvAyPpH.js';
-import { T as Trace, R as RecorderOptions } from '../index-Dl71V7kt.js';
+import { B as BootingRuntime } from '../runtime-types-CP-ykwgf.js';
+import { C as Cmd, c as Sub, M as Machine } from '../core-DNDAEhO2.js';
+import { T as Trace, R as RecorderOptions } from '../index-C1WhBZ6a.js';
 import '@standard-schema/spec';
 
 /**
  * the record → replay → normalized-diff go/no-go gate.
  *
  * The parity spike proved the mechanism already composes from in-tree
- * primitives: `recorder` captures a run's Msg sequence (the recording), `replay`
- * re-folds it purely, and `trace-replay`'s order-insensitive deep-equal diffs
+ * primitives: `recorder` captures the starting State and Msg sequence,
+ * `replayTrace` re-folds it purely, and `trace-replay`'s order-insensitive deep-equal diffs
  * the result. Non-determinism is a RECORD-TIME property — ids/timestamps freeze
- * into the recording, `replay` never re-mints them — so the same recording
+ * into the recording, `replayTrace` never re-mints them — so the same recording
  * replays byte-identical every time.
  *
  * This module is the thin packaging over that substrate plus the one genuinely
@@ -23,7 +23,7 @@ import '@standard-schema/spec';
  *
  * ```text
  *   recordRun(runtime)            → Recording        // wraps the recorder
- *   goldenReplay(machine, rec)    → State            // wraps replay
+ *   goldenReplay(machine, rec)    → State            // wraps replayTrace
  *   normalizeForParity(schema)    → (finding) => norm // strip + stable-sort
  *   parityEqual(a, b)             → boolean           // normalized deep-equal
  * ```
@@ -66,15 +66,11 @@ declare function recordRun<S, M extends {
     type: string;
 }>(runtime: BootingRuntime<S, M>, opts?: RecorderOptions): Recording<S, M>;
 /**
- * Reproduce a recording's final state by folding its msgs through the pure
- * `replay` — `init(loaded, ctx)` then `update` per msg, never `interpret`,
- * never a `Store`, never a live subscription. Accepts a live {@link Recording}
- * (snapshotted here) or a bare {@link Trace}.
+ * Reproduce a recording's final State by folding from its captured post-init
+ * State. Calls no init, handlers, Store operations or Sub runners. Accepts a
+ * live {@link Recording} or a bare {@link Trace}.
  *
- * `ctx` is the ENVIRONMENT supplied fresh at replay time (the trace is the
- * INPUT: `loaded` + `msgs`), mirroring `replayTrace`. It is optional so a
- * void-ctx machine can call `goldenReplay(machine, rec)`; a machine that reads
- * ctx passes it explicitly.
+ * `ctx` is an optional legacy argument; recorded replay needs no init context.
  */
 declare function goldenReplay<S, M extends {
     type: string;

package/dist/parity/index.js

@@ -1,7 +1,7 @@
-import { recorder, deepEqual } from '../chunk-TGJLXZAU.js';
+import { recorder, replayTrace, deepEqual } from '../chunk-ZRRET3RP.js';
 import '../chunk-HWVW4AXC.js';
-import '../chunk-DVNXEB7V.js';
-import { replay } from '../chunk-RKVUVALV.js';
+import '../chunk-BVFS3ICC.js';
+import '../chunk-A3QPMX5M.js';
 
 // src/parity/index.ts
 function recordRun(runtime, opts) {
@@ -14,12 +14,7 @@ function recordRun(runtime, opts) {
 }
 function goldenReplay(machine, recording, ctx) {
   const trace = asTrace(recording);
-  const { state } = replay(machine, {
-    msgs: trace.msgs,
-    ctx,
-    loaded: trace.loaded
-  });
-  return state;
+  return replayTrace(machine, trace, ctx).actual;
 }
 function asTrace(recording) {
   return typeof recording.trace === "function" ? recording.trace() : recording;

package/dist/parity/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/parity/index.ts"],"names":["key"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * the record → replay → normalized-diff go/no-go gate.\n *\n * The parity spike proved the mechanism already composes from in-tree\n * primitives: `recorder` captures a run's Msg sequence (the recording), `replay`\n * re-folds it purely, and `trace-replay`'s order-insensitive deep-equal diffs\n * the result. Non-determinism is a RECORD-TIME property — ids/timestamps freeze\n * into the recording, `replay` never re-mints them — so the same recording\n * replays byte-identical every time.\n *\n * This module is the thin packaging over that substrate plus the one genuinely\n * new helper, `normalizeForParity`: the finding-normalizer that strips\n * record-time non-determinism (generated ids/timestamps) and stable-key-sorts\n * collections, so an OLD-engine golden run and a NEW-engine run diff as equal\n * exactly when they are behaviourally equivalent. Every domain (audit, auth,\n * ingest, …) gets its old-vs-new parity check without reinventing the capture,\n * the normalization, and the diff.\n *\n * ```text\n *   recordRun(runtime)            → Recording        // wraps the recorder\n *   goldenReplay(machine, rec)    → State            // wraps replay\n *   normalizeForParity(schema)    → (finding) => norm // strip + stable-sort\n *   parityEqual(a, b)             → boolean           // normalized deep-equal\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { BootingRuntime, Cmd, Machine, Sub } from \"../index\";\nimport { replay } from \"../index\";\nimport {\n  type RecorderOptions,\n  recorder,\n  type Trace,\n} from \"../internal/persistence/recorder\";\nimport { deepEqual } from \"../internal/persistence/trace-replay\";\n\n/**\n * The two recorder types this module's own signatures name — `Trace` is what\n * {@link Recording.trace} returns and what {@link goldenReplay} accepts bare,\n * `RecorderOptions` is what {@link recordRun} takes. The recorder itself is\n * internal, so this door is the only place either type can be named from\n * outside the package.\n */\nexport type { RecorderOptions, Trace } from \"../internal/persistence/recorder\";\n\n/**\n * A live parity recording attached to a Runtime — the go/no-go gate's golden\n * artifact. Wraps a {@link recorder}: drive the runtime, then snapshot with\n * {@link Recording.trace} (or hand the live `Recording` straight to\n * {@link goldenReplay}, which snapshots for you).\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Recording<S, M> {\n  /**\n   * Snapshot the recording so far as a replayable {@link Trace} — `loaded`\n   * (boot state), the ordered non-null `msgs`, and `finalState`. Sufficient to\n   * reproduce the run via {@link goldenReplay}. Fresh object each call.\n   */\n  trace(): Trace<S, M>;\n  /** Serialize the recording as JSONL (see {@link recorder}'s `toJSONL`). */\n  toJSONL(): string;\n  /** Detach the underlying observer. Idempotent. */\n  stop(): void;\n}\n\n/**\n * Attach a parity recording to a Runtime, reusing the `recorder`/`historyTracker`\n * capture (the boot observe for `loaded` + every non-null msg in order) rather\n * than a fresh observer path.\n *\n * Attach on the synchronous `run()` handle so the boot transition is captured\n * as `loaded`; drive the runtime; then `trace()` (or pass the handle to\n * {@link goldenReplay}). See {@link RecorderOptions} for `captureSteps` (needed\n * only for the per-step / resume-cache-prefix inspection, not for replay).\n */\nexport function recordRun<S, M extends { type: string }>(\n  runtime: BootingRuntime<S, M>,\n  opts?: RecorderOptions,\n): Recording<S, M> {\n  const rec = recorder(runtime, opts);\n  return {\n    trace: () => rec.dump(),\n    toJSONL: () => rec.toJSONL(),\n    stop: () => rec.stop(),\n  };\n}\n\n/**\n * Reproduce a recording's final state by folding its msgs through the pure\n * `replay` — `init(loaded, ctx)` then `update` per msg, never `interpret`,\n * never a `Store`, never a live subscription. Accepts a live {@link Recording}\n * (snapshotted here) or a bare {@link Trace}.\n *\n * `ctx` is the ENVIRONMENT supplied fresh at replay time (the trace is the\n * INPUT: `loaded` + `msgs`), mirroring `replayTrace`. It is optional so a\n * void-ctx machine can call `goldenReplay(machine, rec)`; a machine that reads\n * ctx passes it explicitly.\n */\nexport function goldenReplay<\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  recording: Recording<S, M> | Trace<S, M>,\n  ctx?: Ctx,\n): S {\n  const trace = asTrace(recording);\n  const { state } = replay(machine, {\n    msgs: trace.msgs,\n    ctx: ctx as Ctx,\n    loaded: trace.loaded,\n  });\n  return state;\n}\n\n/** Narrow a `Recording | Trace` to a `Trace`, snapshotting a live recording. */\nfunction asTrace<S, M>(recording: Recording<S, M> | Trace<S, M>): Trace<S, M> {\n  return typeof (recording as Recording<S, M>).trace === \"function\"\n    ? (recording as Recording<S, M>).trace()\n    : (recording as Trace<S, M>);\n}\n\n/** Configuration for {@link normalizeForParity}. */\nexport interface ParitySchema {\n  /**\n   * Object keys stripped wherever they appear — the record-time\n   * non-determinism `replay` never re-mints. Default: `id`, `runId`,\n   * `timestamp`.\n   */\n  readonly stripKeys?: readonly string[];\n  /**\n   * Candidate keys used to stable-sort arrays of objects. For each array the\n   * first candidate present (as a primitive) on the items decides the order;\n   * arrays with no candidate fall back to canonical-JSON order. Default:\n   * `ruleId`, `selector`, `url`.\n   */\n  readonly sortKeys?: readonly string[];\n}\n\n// Defaults proven by the spike: strip the generated id/runId/timestamp,\n// stable-key-sort by ruleId | selector | url. Fan-out ordering is already\n// deterministic on this substrate (array order); the sort only defends against\n// intra-effect concurrency (Promise.all / Set).\nconst DEFAULT_STRIP_KEYS: readonly string[] = [\"id\", \"runId\", \"timestamp\"];\nconst DEFAULT_SORT_KEYS: readonly string[] = [\"ruleId\", \"selector\", \"url\"];\n\n/**\n * Build a finding-normalizer: a pure `(value) => normalized` that strips the\n * schema's `stripKeys`, recursively sorts object keys, and stable-key-sorts\n * arrays by the schema's `sortKeys`. Two runs that differ only in generated\n * ids/timestamps or intra-effect ordering normalize to a byte-identical value,\n * so {@link parityEqual} on the normalized pair reflects behavioural (not incidental)\n * difference.\n */\nexport function normalizeForParity(\n  schema?: ParitySchema,\n): (value: unknown) => unknown {\n  const stripKeys = new Set(schema?.stripKeys ?? DEFAULT_STRIP_KEYS);\n  const sortKeys = schema?.sortKeys ?? DEFAULT_SORT_KEYS;\n\n  const normalize = (value: unknown): unknown => {\n    if (Array.isArray(value)) {\n      const items = value.map(normalize);\n      // Decorate-sort-undecorate: primary key = first present sortKey value,\n      // secondary = canonical JSON (items are already normalized so keys are\n      // sorted), original index last for a stable total order.\n      return items\n        .map((item, index) => ({\n          item,\n          index,\n          primary: primarySortKey(item, sortKeys),\n          json: JSON.stringify(item) ?? \"\",\n        }))\n        .sort(\n          (a, b) =>\n            compareStrings(a.primary, b.primary) ||\n            compareStrings(a.json, b.json) ||\n            a.index - b.index,\n        )\n        .map((decorated) => decorated.item);\n    }\n    if (isPlainObject(value)) {\n      const out: Record<string, unknown> = {};\n      for (const key of Object.keys(value)\n        .filter((key) => !stripKeys.has(key))\n        .sort()) {\n        out[key] = normalize(value[key]);\n      }\n      return out;\n    }\n    return value;\n  };\n\n  return normalize;\n}\n\n/** The first present `sortKeys` candidate on `item` as a string, or `\"\"`. */\nfunction primarySortKey(item: unknown, sortKeys: readonly string[]): string {\n  if (!isPlainObject(item)) return \"\";\n  for (const key of sortKeys) {\n    const candidate = item[key];\n    if (\n      typeof candidate === \"string\" ||\n      typeof candidate === \"number\" ||\n      typeof candidate === \"boolean\"\n    ) {\n      return String(candidate);\n    }\n  }\n  return \"\";\n}\n\nfunction compareStrings(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * The parity verdict: `true` iff `a` and `b` are structurally equal. Reuses\n * `trace-replay`'s order-insensitive deep-equal (the comparator the\n * record/replay lane owns) rather than adding another boolean deep-compare —\n * feed it the pair produced by {@link normalizeForParity} for the\n * normalized-JSON equality the gate rests on.\n */\nexport function parityEqual(a: unknown, b: unknown): boolean {\n  return deepEqual(a, b);\n}\n"]}
+{"version":3,"sources":["../../src/parity/index.ts"],"names":["key"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * the record → replay → normalized-diff go/no-go gate.\n *\n * The parity spike proved the mechanism already composes from in-tree\n * primitives: `recorder` captures the starting State and Msg sequence,\n * `replayTrace` re-folds it purely, and `trace-replay`'s order-insensitive deep-equal diffs\n * the result. Non-determinism is a RECORD-TIME property — ids/timestamps freeze\n * into the recording, `replayTrace` never re-mints them — so the same recording\n * replays byte-identical every time.\n *\n * This module is the thin packaging over that substrate plus the one genuinely\n * new helper, `normalizeForParity`: the finding-normalizer that strips\n * record-time non-determinism (generated ids/timestamps) and stable-key-sorts\n * collections, so an OLD-engine golden run and a NEW-engine run diff as equal\n * exactly when they are behaviourally equivalent. Every domain (audit, auth,\n * ingest, …) gets its old-vs-new parity check without reinventing the capture,\n * the normalization, and the diff.\n *\n * ```text\n *   recordRun(runtime)            → Recording        // wraps the recorder\n *   goldenReplay(machine, rec)    → State            // wraps replayTrace\n *   normalizeForParity(schema)    → (finding) => norm // strip + stable-sort\n *   parityEqual(a, b)             → boolean           // normalized deep-equal\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { BootingRuntime, Cmd, Machine, Sub } from \"../index\";\nimport {\n  type RecorderOptions,\n  recorder,\n  type Trace,\n} from \"../internal/persistence/recorder\";\nimport { deepEqual, replayTrace } from \"../internal/persistence/trace-replay\";\n\n/**\n * The two recorder types this module's own signatures name — `Trace` is what\n * {@link Recording.trace} returns and what {@link goldenReplay} accepts bare,\n * `RecorderOptions` is what {@link recordRun} takes. The recorder itself is\n * internal, so this subpath is the only place either type can be named from\n * outside the package.\n */\nexport type { RecorderOptions, Trace } from \"../internal/persistence/recorder\";\n\n/**\n * A live parity recording attached to a Runtime — the go/no-go gate's golden\n * artifact. Wraps a {@link recorder}: drive the runtime, then snapshot with\n * {@link Recording.trace} (or hand the live `Recording` straight to\n * {@link goldenReplay}, which snapshots for you).\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Recording<S, M> {\n  /**\n   * Snapshot the recording so far as a replayable {@link Trace} — `loaded`\n   * (boot state), the ordered non-null `msgs`, and `finalState`. Sufficient to\n   * reproduce the run via {@link goldenReplay}. Fresh object each call.\n   */\n  trace(): Trace<S, M>;\n  /** Serialize the recording as JSONL (see {@link recorder}'s `toJSONL`). */\n  toJSONL(): string;\n  /** Detach the underlying observer. Idempotent. */\n  stop(): void;\n}\n\n/**\n * Attach a parity recording to a Runtime, reusing the `recorder`/`historyTracker`\n * capture (the boot observe for `loaded` + every non-null msg in order) rather\n * than a fresh observer path.\n *\n * Attach on the synchronous `run()` handle so the boot transition is captured\n * as `loaded`; drive the runtime; then `trace()` (or pass the handle to\n * {@link goldenReplay}). See {@link RecorderOptions} for `captureSteps` (needed\n * only for the per-step / resume-cache-prefix inspection, not for replay).\n */\nexport function recordRun<S, M extends { type: string }>(\n  runtime: BootingRuntime<S, M>,\n  opts?: RecorderOptions,\n): Recording<S, M> {\n  const rec = recorder(runtime, opts);\n  return {\n    trace: () => rec.dump(),\n    toJSONL: () => rec.toJSONL(),\n    stop: () => rec.stop(),\n  };\n}\n\n/**\n * Reproduce a recording's final State by folding from its captured post-init\n * State. Calls no init, handlers, Store operations or Sub runners. Accepts a\n * live {@link Recording} or a bare {@link Trace}.\n *\n * `ctx` is an optional legacy argument; recorded replay needs no init context.\n */\nexport function goldenReplay<\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  recording: Recording<S, M> | Trace<S, M>,\n  ctx?: Ctx,\n): S {\n  const trace = asTrace(recording);\n  return replayTrace(machine, trace, ctx).actual;\n}\n\n/** Narrow a `Recording | Trace` to a `Trace`, snapshotting a live recording. */\nfunction asTrace<S, M>(recording: Recording<S, M> | Trace<S, M>): Trace<S, M> {\n  return typeof (recording as Recording<S, M>).trace === \"function\"\n    ? (recording as Recording<S, M>).trace()\n    : (recording as Trace<S, M>);\n}\n\n/** Configuration for {@link normalizeForParity}. */\nexport interface ParitySchema {\n  /**\n   * Object keys stripped wherever they appear — the record-time\n   * non-determinism `replay` never re-mints. Default: `id`, `runId`,\n   * `timestamp`.\n   */\n  readonly stripKeys?: readonly string[];\n  /**\n   * Candidate keys used to stable-sort arrays of objects. For each array the\n   * first candidate present (as a primitive) on the items decides the order;\n   * arrays with no candidate fall back to canonical-JSON order. Default:\n   * `ruleId`, `selector`, `url`.\n   */\n  readonly sortKeys?: readonly string[];\n}\n\n// Defaults proven by the spike: strip the generated id/runId/timestamp,\n// stable-key-sort by ruleId | selector | url. Fan-out ordering is already\n// deterministic on this substrate (array order); the sort only defends against\n// intra-effect concurrency (Promise.all / Set).\nconst DEFAULT_STRIP_KEYS: readonly string[] = [\"id\", \"runId\", \"timestamp\"];\nconst DEFAULT_SORT_KEYS: readonly string[] = [\"ruleId\", \"selector\", \"url\"];\n\n/**\n * Build a finding-normalizer: a pure `(value) => normalized` that strips the\n * schema's `stripKeys`, recursively sorts object keys, and stable-key-sorts\n * arrays by the schema's `sortKeys`. Two runs that differ only in generated\n * ids/timestamps or intra-effect ordering normalize to a byte-identical value,\n * so {@link parityEqual} on the normalized pair reflects behavioural (not incidental)\n * difference.\n */\nexport function normalizeForParity(\n  schema?: ParitySchema,\n): (value: unknown) => unknown {\n  const stripKeys = new Set(schema?.stripKeys ?? DEFAULT_STRIP_KEYS);\n  const sortKeys = schema?.sortKeys ?? DEFAULT_SORT_KEYS;\n\n  const normalize = (value: unknown): unknown => {\n    if (Array.isArray(value)) {\n      const items = value.map(normalize);\n      // Decorate-sort-undecorate: primary key = first present sortKey value,\n      // secondary = canonical JSON (items are already normalized so keys are\n      // sorted), original index last for a stable total order.\n      return items\n        .map((item, index) => ({\n          item,\n          index,\n          primary: primarySortKey(item, sortKeys),\n          json: JSON.stringify(item) ?? \"\",\n        }))\n        .sort(\n          (a, b) =>\n            compareStrings(a.primary, b.primary) ||\n            compareStrings(a.json, b.json) ||\n            a.index - b.index,\n        )\n        .map((decorated) => decorated.item);\n    }\n    if (isPlainObject(value)) {\n      const out: Record<string, unknown> = {};\n      for (const key of Object.keys(value)\n        .filter((key) => !stripKeys.has(key))\n        .sort()) {\n        out[key] = normalize(value[key]);\n      }\n      return out;\n    }\n    return value;\n  };\n\n  return normalize;\n}\n\n/** The first present `sortKeys` candidate on `item` as a string, or `\"\"`. */\nfunction primarySortKey(item: unknown, sortKeys: readonly string[]): string {\n  if (!isPlainObject(item)) return \"\";\n  for (const key of sortKeys) {\n    const candidate = item[key];\n    if (\n      typeof candidate === \"string\" ||\n      typeof candidate === \"number\" ||\n      typeof candidate === \"boolean\"\n    ) {\n      return String(candidate);\n    }\n  }\n  return \"\";\n}\n\nfunction compareStrings(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * The parity verdict: `true` iff `a` and `b` are structurally equal. Reuses\n * `trace-replay`'s order-insensitive deep-equal (the comparator the\n * record/replay lane owns) rather than adding another boolean deep-compare —\n * feed it the pair produced by {@link normalizeForParity} for the\n * normalized-JSON equality the gate rests on.\n */\nexport function parityEqual(a: unknown, b: unknown): boolean {\n  return deepEqual(a, b);\n}\n"]}

package/dist/pbt/index.d.ts

@@ -1,5 +1,7 @@
 import * as fc from 'fast-check';
-import { C as Cmd, S as Sub, M as Machine, g as Reducer, i as Transitions, U as UpdateForm } from '../core-CtvAyPpH.js';
+import { C as Cmd, c as Sub, M as Machine, g as Reducer, i as Transitions, U as UpdateForm } from '../core-DNDAEhO2.js';
+import { S as Step } from '../laws-DTtCDDlU.js';
+export { F as Fold, L as LawBreak, f as foldEvents, l as lawInvariant, a as lawTerminates, b as lawTrace } from '../laws-DTtCDDlU.js';
 import '@standard-schema/spec';
 
 /**
@@ -137,7 +139,8 @@ declare function arbRecordMsg<T extends string, R>(type: T, fields: {
  *
  * - `minLength` (default 0) and `maxLength` (default 30) bound the random
  *   array length. `prefix` is prepended AFTER the random tail is built; the
- *   final length is `prefix.length + tail.length`.
+ *   final length is `prefix.length + tail.length`. `size` decides how much of
+ *   that bound the draws actually use.
  * - `prefix` is the load-bearing escape hatch for "the first msg is the
  *   one that exercises the cell I care about" (e.g. Test A's
  *   `[{ type: "ws:client:hello" }]` prefix to land in the
@@ -153,6 +156,7 @@ declare function arbRecordMsg<T extends string, R>(type: T, fields: {
  *
  * arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 });
  * arbMsgSequence(msgArb, { prefix: [{ type: "ws:client:hello" }], maxLength: 20 });
+ * arbMsgSequence(msgArb, { maxLength: 60, size: "max" });
  * ```
  */
 declare function arbMsgSequence<M extends {
@@ -161,85 +165,280 @@ declare function arbMsgSequence<M extends {
     readonly minLength?: number;
     readonly maxLength?: number;
     readonly prefix?: readonly NoInfer<M>[];
+    /**
+     * Forwarded to `fc.array`. Left out, fast-check's default size applies:
+     * `"small"` unless `fc.configureGlobal` changed it, which draws at most
+     * `2 * minLength + 10` Msgs however large `maxLength` is. So `maxLength: 60`
+     * comes out about 10 long, and a state that takes more steps than that is
+     * never reached. Pass `"max"` to draw up to `maxLength`.
+     */
+    readonly size?: fc.SizeForArbitrary;
 }): fc.Arbitrary<readonly M[]>;
 /**
- * State-aware Msg sequence arbitrary — generates only msgs whose
- * precondition holds in the current state. Backed by `fc.commands`
- * internally. Planned for a later phase.
+ * How one type of Cmd gets answered. `draw` runs before the fold, so a shrink
+ * can shrink its value, and it cannot see the state. `make` runs in the fold and
+ * gets the Cmd really sent, so an answer is `make: (cmd, v) => fetch.ok(cmd, v)`.
+ * To draw both outcomes, have `draw` choose between them.
+ */
+interface AnswerCell<K extends Cmd, V, M> {
+    readonly draw: fc.Arbitrary<V>;
+    readonly make: (cmd: K, value: V) => NoInfer<M>;
+}
+/**
+ * What {@link arbGuidedSequence} draws from. `outside` holds the Msgs nothing
+ * sends a Cmd for, by Msg type. `answers` holds an {@link AnswerCell} by Cmd type,
+ * and `A` is the value each one draws, inferred from its `draw`. A Cmd type with no
+ * cell is never answered. A Msg type in neither table is never drawn.
+ */
+interface GuidedCells<M extends {
+    type: string;
+}, C extends Cmd, A extends {
+    readonly [K in C["type"]]?: unknown;
+}> {
+    readonly outside?: {
+        readonly [K in M["type"]]?: fc.Arbitrary<Extract<M, {
+            type: K;
+        }>>;
+    };
+    readonly answers?: {
+        readonly [K in keyof A]: K extends C["type"] ? AnswerCell<Extract<C, {
+            type: K;
+        }>, A[K], M> : never;
+    };
+}
+/**
+ * Draw Msg lists in which every answer answers a Cmd that was sent and not yet
+ * answered, so a law that something must happen can be checked on random lists.
+ * The result is a plain list for any runner, such as `propertyTerminates`.
+ *
+ * It draws blind events, then folds them through the machine. An answer event
+ * holds a pick and one value per answer cell, and the fold reads the pick modulo
+ * the Cmds waiting at that point. With nothing waiting, the event is dropped.
+ *
+ * **Refusals.** An event whose Msg the state at that point has no cell for is
+ * dropped too, in either update form, so a transitions machine can leave a Msg out
+ * of a state and no list holds it there. A Cmd whose answer was refused keeps
+ * waiting, and a later event can still answer it. A list therefore never tests
+ * that a state refuses a Msg: send that Msg by hand for that.
+ *
+ * **Waiting** holds every Cmd that `init` and the steps have sent, that has a cell
+ * in `answers`, and that has no answer yet. A Cmd sent twice waits twice. The fold
+ * reads it off what the reducer returned, not `machine.cmds`, so a machine with no
+ * `cmds` field gets the same lists, and a hand-written Cmd is answered like a
+ * defined one. No answer is matched by its `cmd` field: the pick names the Cmd.
+ *
+ * A shrink deletes events and shrinks picks and values, and the fold reads what
+ * is left, so a shrunk list holds to the same rule. Blind picks find a narrow
+ * order less often than a guided draw would, which more runs pay for.
+ *
+ * A step that throws ends its list on the Msg that threw, so a runner's fold meets
+ * the same throw and reports it as that list's failure.
+ *
+ * - `maxLength` (default 60) caps the events drawn, and dropped ones count, so a
+ *   list comes out shorter. `size` (default `"max"`) is forwarded to `fc.array`:
+ *   with most answers dropped, fast-check's `"small"` rarely gets a run anywhere.
+ * - `loaded` starts the fold from a saved state. Give a runner the same one, or
+ *   its fold reads the list from a different start.
+ *
+ * Throws when `cells` has no cell at all, since that could only draw empty lists.
+ *
+ * @example
+ * ```ts
+ * import type { Machine } from "@demlik/tea";
+ * import {
+ *   arbConstantMsg,
+ *   arbGuidedSequence,
+ *   propertyTrace,
+ *   stubCtxThrowingProxy,
+ * } from "@demlik/tea/pbt";
+ * import * as fc from "fast-check";
+ *
+ * type Merge = { readonly type: "merge"; readonly pr: number };
+ * type State = { type: "idle" } | { type: "merging" } | { type: "landed" };
+ * type Msg = { type: "start" } | { type: "merged"; cmd: Merge; sha: string };
+ * declare const machine: Machine<State, Msg, Merge, never, object>;
+ * const ctx = stubCtxThrowingProxy<object>();
+ *
+ * const lists = arbGuidedSequence(machine, ctx, {
+ *   outside: { start: arbConstantMsg("start") },
+ *   answers: {
+ *     merge: {
+ *       draw: fc.string(),
+ *       make: (cmd, sha) => ({ type: "merged", cmd, sha }),
+ *     },
+ *   },
+ * });
  *
- * **NOT IMPLEMENTED IN v1.** The export exists today so the surface is
- * forward-compatible; this ships in a later phase alongside
- * shrinkers. Calling it throws.
+ * propertyTrace(
+ *   machine,
+ *   ctx,
+ *   lists,
+ *   (steps, final) =>
+ *     !steps.some((step) => step.msg.type === "merged") ||
+ *     final.type === "landed",
+ * );
+ * ```
  */
 declare function arbGuidedSequence<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(_machine: Machine<S, M, C, U, Ctx>, _ctx: Ctx, _cells: {
-    [K in M["type"]]?: (state: S) => fc.Arbitrary<Extract<M, {
-        type: K;
-    }>> | null;
-}, _opts?: {
-    maxLength?: number;
+}, C extends Cmd, U extends Sub, Ctx, A extends {
+    readonly [K in C["type"]]?: unknown;
+}>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, cells: GuidedCells<M, C, A>, opts?: {
+    readonly maxLength?: number;
+    readonly size?: fc.SizeForArbitrary;
+    readonly loaded?: NoInfer<S> | null;
 }): fc.Arbitrary<readonly M[]>;
 
+/** What a property run's lists did with one Msg type. */
+interface MsgCount {
+    /** How many of this Msg type the run's lists held. */
+    readonly drawn: number;
+    /**
+     * How many of those acted: the step's `next` differs from its `prev` by
+     * `structuralHash`, or the step sent a Cmd.
+     */
+    readonly acted: number;
+}
+
+/**
+ * What every property runner takes: the saved state to start from, the two checks
+ * below, and fast-check's `Parameters` (`numRuns` defaults to 200 here). Five of
+ * those settings are left out, each because it would break what a runner promises:
+ *
+ *   - `reporter` and `asyncReporter` stop a failing run from throwing. One set
+ *     through `fc.configureGlobal` still applies, as it does for `fc.assert`.
+ *   - `examples` has the shape of the drawn tuple, which an arbitrary `loaded`
+ *     changes.
+ *   - `timeout` applies only to async properties, and these runners are sync.
+ *     `interruptAfterTimeLimit` with `markInterruptAsFailure` is the limit that
+ *     works here.
+ *   - `plugins` is left out on every fast-check. Only the newest 4s have it, so a
+ *     call using it would compile and run on some of the versions tea promises and
+ *     not on others. `fc.timeout`, which it can carry, has the same limit as
+ *     `timeout`. fast-check 4.10.2 marks `interruptAfterTimeLimit`,
+ *     `markInterruptAsFailure`, `skipEqualValues`, `ignoreEqualValues` and `unbiased`
+ *     as deprecated in favor of plugins, and they still work on every version tea
+ *     promises, so they stay.
+ */
+interface PropertyOpts<S> extends Omit<fc.Parameters, "reporter" | "asyncReporter" | "examples" | "timeout" | "plugins"> {
+    /**
+     * Saved state passed to `machine.init(loaded, ctx)`. Default `null`. An
+     * arbitrary draws one per run, and a failure's counterexample shows the drawn
+     * state beside the shrunk list. It can draw `null` as well, the nothing storage
+     * hands back on a fresh start, which boots the machine fresh.
+     */
+    readonly loaded?: S | null | fc.Arbitrary<S | null>;
+    /**
+     * Fail a run whose laws all held when a Msg type never acted, naming each such
+     * type, so a cut path can't stay green. Default `false`.
+     *
+     * A deep path needs a `maxLength` well past its depth as well as `size: "max"`
+     * on `arbMsgSequence`. Lists too short to reach a healthy machine's deep state
+     * name that healthy path as never acted, in the same report a cut path gives. At
+     * the default `maxLength` of 30, a state 20 steps deep on 6 Msg types drawn evenly
+     * fails this way, since only one draw in 6 climbs. Allow about the depth times the
+     * number of Msg types, here `maxLength: 120`.
+     *
+     * This stays out of any run with a non-empty `path`, so drop `path` to have it
+     * check again. A path with a colon, such as `"0:0"`, replays one shrunk failure. A
+     * path with no colon, such as `"3"`, is what a failure with no shrinks reports, and
+     * it is no replay once that failure is gone: fast-check draws a full `numRuns` of
+     * lists starting from that one, and a cut path reads green. `path: ""` is no path
+     * to fast-check, so this applies there.
+     *
+     * A value `structuralHash` refuses (a `Date`, a `Map`, a class instance) leaves
+     * "acted" unreadable when a step's comparison reaches it, so this fails the run
+     * saying so. The comparison stops at the first difference and doesn't look inside
+     * an object `prev` and `next` share, so a refused value stays unread, and fails
+     * nothing, when it sits in a shared object or past a difference. The answer is
+     * right either way: a shared object didn't change, and a difference means the
+     * step acted. Fields are compared in the order the state's keys were set.
+     */
+    readonly failOnNeverActed?: boolean;
+    /**
+     * Fail a run when `init` or a step sends a Cmd whose `type` isn't in
+     * `machine.cmds`, naming that Cmd. Default `false`, because tea lets a machine
+     * keep a hand-written Cmd beside its defined ones. A machine with no `cmds` field
+     * has no list to check against, so this adds nothing there. `cmds: []` is a list
+     * with nothing on it, so every Cmd fails.
+     *
+     * A value with no string `type` is never a Cmd, so it fails with this off too, on
+     * every machine.
+     */
+    readonly failOnUndeclaredCmd?: boolean;
+}
 /**
- * One unit in a fold trace — the four pieces of data a property
- * invariant typically asserts on. `prev` is the state before the msg
- * applied; `next` is the state after; `cmds` is the cmds emitted by this
- * single step (NOT the running total).
+ * What a property run did. A passing runner returns it, and a failing one throws
+ * it on {@link PropertyFailure.run}, so a caller reads one shape on both arms and
+ * never parses error text.
  */
-interface Step<S, M, C> {
-    readonly prev: S;
-    readonly msg: M;
-    readonly next: S;
-    readonly cmds: readonly C[];
+interface PropertyRun {
+    /** Lists tried. On a failure, this counts up to and including the failing one. */
+    readonly numRuns: number;
+    /** Shrink steps a failure took. `0` on a pass. */
+    readonly numShrinks: number;
+    /** The seed this run drew from. Pass it back as `seed` to draw the same lists. */
+    readonly seed: number;
+    /**
+     * Where the shrunk failure sits. Pass it back as `path`, with `seed`, to replay
+     * that one failure. `null` when no list failed: on a pass, on an interrupt
+     * marked as a failure, when too many `fc.pre` skips fail the run, or when
+     * `failOnNeverActed` fails it.
+     */
+    readonly path: string | null;
+    /**
+     * What the run's lists did, per Msg type: every type the machine has a cell for,
+     * then any other that was drawn. A type never drawn reads zero. On a failure this
+     * stops at the failing list, so shrinking adds nothing, and a list skipped with
+     * `fc.pre` adds nothing either. A list whose reducer threw adds nothing as well,
+     * though `numRuns` includes it: its fold hands back no steps to count.
+     *
+     * A step counts as acted when its comparison reaches a value `structuralHash`
+     * refuses (a `Date`, a `Map`, a class instance). One in an object `prev` and `next`
+     * share, or past a difference, is never reached, so it changes no count.
+     */
+    readonly msgCounts: ReadonlyMap<string, MsgCount>;
 }
 /**
- * Fold a Msg sequence through a machine's pure reducer, returning the
- * per-step trace, every state in order, and the final state. Initial
- * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.
- * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds
- * are NOT included in any `Step` (they're the boot moment, not a Msg).
- *
- * @param machine  The machine under test.
- * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when
- *                 init is pure. Pass a real ctx if init reads from it.
- * @param loaded   Optional pre-init snapshot (the `loaded` arg to
- *                 `machine.init`). Defaults to `null` (fresh boot).
- * @param msgs     The Msg sequence to fold.
+ * Raised when a property fails. The message is fast-check's report, and
+ * {@link PropertyFailure.run} holds the same {@link PropertyRun} a pass returns.
+ * What the check threw sits where `fc.assert` puts it on the installed fast-check:
+ * on 4, in `cause` by default and in the message with `includeErrorInReport`; on 3,
+ * in the message by default and in `cause` with `errorWithCause`, on the 3s that have
+ * that setting. A reason the check returned is always in the message: when it went to
+ * `cause`, the message is the report plus a `reason:` line. A run that `failOnNeverActed` fails broke no list,
+ * so fast-check has no report: the message names the Msg types instead.
  *
  * @example
  * ```ts
  * import type { Machine } from "@demlik/tea";
- * import { foldEvents } from "@demlik/tea/pbt";
+ * import { PropertyFailure, propertyInvariant } from "@demlik/tea/pbt";
+ * import type * as fc from "fast-check";
  *
- * type State = { type: "idle" } | { type: "counting"; n: number } | { type: "stopped" };
- * type Msg = { type: "start" } | { type: "tick" } | { type: "stop" };
- * interface Ctx { readonly tabId: number }
- * declare const machine: Machine<State, Msg, never, never, Ctx>;
- * declare const ctx: Ctx;
+ * type State = { type: "idle" } | { type: "done" };
+ * type Msg = { type: "finish" };
+ * declare const machine: Machine<State, Msg, never, never, object>;
+ * declare const seqArb: fc.Arbitrary<readonly Msg[]>;
  *
- * const { states, steps, finalState } = foldEvents(machine, ctx, null, [
- *   { type: "start" }, { type: "tick" }, { type: "stop" },
- * ]);
- * // steps[1] = { prev: { type: "counting", n: 0 }, msg: { type: "tick" }, ... }
+ * try {
+ *   propertyInvariant(machine, {}, seqArb, ({ next }) => next.type === "idle");
+ * } catch (error) {
+ *   if (error instanceof PropertyFailure) {
+ *     // Replay this one failure with `{ seed, path }`.
+ *     const { numShrinks, seed, path } = error.run;
+ *     console.log(numShrinks, seed, path);
+ *   }
+ * }
  * ```
  */
-declare function foldEvents<S, M extends {
-    type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, loaded: NoInfer<S> | null, msgs: readonly NoInfer<M>[]): {
-    readonly states: readonly S[];
-    readonly steps: readonly Step<S, M, C>[];
-    readonly finalState: S;
-};
-
-/** Common options shared by every property runner. */
-interface PropertyOpts<S> {
-    /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */
-    readonly loaded?: S | null;
-    /** Number of generated sequences to test. Forwarded to `fc.assert`. */
-    readonly numRuns?: number;
-    /** Optional fast-check seed for reproducibility. */
-    readonly seed?: number;
+declare class PropertyFailure extends Error {
+    /** The run that failed. */
+    readonly run: PropertyRun;
+    readonly name = "PropertyFailure";
+    readonly _tag: "PropertyFailure";
+    constructor(report: string, 
+    /** The run that failed. */
+    run: PropertyRun, options?: ErrorOptions);
 }
 /**
  * Assert every generated Msg sequence ends in a terminal state. `terminal`
@@ -250,6 +449,8 @@ interface PropertyOpts<S> {
  * non-terminal state and no further msg can escape) AND silent loops
  * (every msg variant is a noop from a given state).
  *
+ * `terminal` also gets the Cmds `init` sent on that list's start.
+ *
  * @example
  * ```ts
  * import type { Machine } from "@demlik/tea";
@@ -278,11 +479,17 @@ interface PropertyOpts<S> {
  */
 declare function propertyTerminates<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, terminal: (state: NoInfer<S>) => boolean, opts?: NoInfer<PropertyOpts<S>>): void;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, terminal: (state: NoInfer<S>, initCmds: readonly NoInfer<C>[]) => boolean, opts?: NoInfer<PropertyOpts<S>>): PropertyRun;
 /**
  * Assert a predicate holds on EVERY transition step in a generated
- * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;
- * return true to accept, false (or throw) to fail.
+ * sequence. The predicate sees `{ prev, msg, next, cmds }` per step. Return
+ * `true` or `null` to accept. Return `false`, or a string saying why, to fail: the
+ * thrown error's message names that string. An empty string fails too. A throw
+ * still fails with its own message.
+ *
+ * The predicate's second argument is the Cmds `init` sent on that list's start. It
+ * runs once per step, so an empty list never shows them to it: use `propertyTrace`
+ * for a rule about `init` alone.
  *
  * Use to pin a "when X happens in state Y, cmd Z must be emitted" rule.
  * The shrinker minimizes the offending sequence to the smallest Msg list
@@ -317,13 +524,18 @@ declare function propertyTerminates<S, M extends {
  */
 declare function propertyInvariant<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean, opts?: NoInfer<PropertyOpts<S>>): void;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>, initCmds: readonly NoInfer<C>[]) => boolean | string | null, opts?: NoInfer<PropertyOpts<S>>): PropertyRun;
 /**
  * Assert a predicate over the full trace plus the final state. Use when
  * the property is "some Msg appeared in the trace before reaching the
  * final state" or "no two consecutive steps had the same state.type" —
  * predicates that need the full sequence, not a single step.
  *
+ * Return `true` or `null` to accept. Return `false`, or a string saying why, to
+ * fail: the thrown error's message names that string. An empty string fails too.
+ * A throw still fails with its own message. The last argument is the Cmds `init`
+ * sent on that list's start.
+ *
  * @example
  * ```ts
  * import type { Machine } from "@demlik/tea";
@@ -349,7 +561,7 @@ declare function propertyInvariant<S, M extends {
  */
 declare function propertyTrace<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, predicate: (steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[], finalState: NoInfer<S>) => boolean, opts?: NoInfer<PropertyOpts<S>>): void;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, predicate: (steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[], finalState: NoInfer<S>, initCmds: readonly NoInfer<C>[]) => boolean | string | null, opts?: NoInfer<PropertyOpts<S>>): PropertyRun;
 
 /**
  * Extract the Msg discriminant set at runtime from a machine. Useful for
@@ -388,4 +600,4 @@ declare function msgTypeKeys<S, M extends {
     __form?: UpdateForm;
 }): readonly string[];
 
-export { type MsgArbitraryTable, type Step, arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, foldEvents, msgTypeKeys, propertyInvariant, propertyTerminates, propertyTrace, stubCtxThrowingProxy };
+export { type AnswerCell, type GuidedCells, type MsgArbitraryTable, type MsgCount, PropertyFailure, type PropertyOpts, type PropertyRun, Step, arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, msgTypeKeys, propertyInvariant, propertyTerminates, propertyTrace, stubCtxThrowingProxy };