@demlik/tea 0.1.0 → 0.1.1

package/dist/paginator/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @demlik/tea/paginator — the cursor/offset/page-token walk loop as pure
+ * state + ops.
+ *
+ * Same shape as `@demlik/tea/retry-backoff`, `@demlik/tea/circuit-breaker`,
+ * and `@demlik/tea/rate-limit`: a state type plus pure transition functions,
+ * host-agnostic by construction. Nothing here reads the clock, the RNG, or any
+ * I/O on its own behalf — the consumer fetches a page out-of-band and folds the
+ * *result* back in through `recordPage`. That keeps every function inside TEA's
+ * invariant 2 (transitions are pure: same inputs → same outputs) so a consumer
+ * can thread the walk through `update` and exercise it with `replay` / the pbt
+ * fold without a fake network.
+ *
+ * Every op returns a NEW state value and never mutates its input (invariant 1 —
+ * state is a value, not a place). All fields are `readonly` and plain data, so
+ * the whole walk is trivially JSON-serializable into a consumer's `Store<S>`
+ * and survives a Durable-Object eviction / reload mid-walk: the cursor lives in
+ * the Model, not a closure (the durability + replay non-negotiables every TEA
+ * knob preserves).
+ *
+ * ## The cursor is opaque, and the consumer advances it
+ *
+ * A paginated API hands back a *next cursor* however it likes: an offset
+ * (`?offset=40`), a page token (`?pageToken=ey…`), a "next" URL, or `null` at
+ * the end. This module is generic in `Cursor` and never inspects it — it only
+ * carries it forward. The consumer (who alone knows the API's shape) reads the
+ * next cursor off the just-fetched page and passes it to `recordPage`:
+ *
+ *   const next = page.nextPageToken ?? null;   // consumer-specific extraction
+ *   const walk = recordPage(state.walk, page.items.length, next);
+ *
+ * Passing `next: null` (or a missing `undefined` cursor — the op compares with
+ * loose `== null`) means "the API said there is no next page" → the walk
+ * finishes (`done`). Passing a `Cursor` means "fetch this one next" → the walk
+ * either keeps `fetching` or `pauses` for backpressure (below). Decoupling the
+ * extraction from the op is the same discipline `circuit-breaker` uses for the
+ * clock: the impure / domain-specific bit (`nextCursor(page)`) lives at the
+ * call site; the op stays a pure fold over the extracted value.
+ *
+ * ## The phase machine
+ *
+ * Four phases, each a discriminated-union arm carrying ONLY the data that phase
+ * needs so impossible states are unrepresentable (pattern 11):
+ *
+ *   - **idle** — created, not started. No cursor is armed yet; `start` arms the
+ *     first one. Carries the running `seen` / `pages` counters (both 0 here, but
+ *     present on every phase so a consumer reads them uniformly).
+ *
+ *   - **fetching** — a page request for `cursor` is outstanding. The walk sits
+ *     here while the consumer's fetch is in flight; `recordPage` resolves it.
+ *     Carries the `cursor` being fetched so a post-eviction resume re-issues the
+ *     SAME request (idempotent retry) rather than skipping a page.
+ *
+ *   - **paused** — backpressure tripped. The API still has more pages (a non-null
+ *     next cursor), but `seen` has reached `highWaterMark` and the consumer has
+ *     not drained yet. Carries the `cursor` to resume from. No fetch is
+ *     outstanding — the loop is deliberately idle until `resume`. This is the
+ *     valve that stops a fast producer (the API) from outrunning a slow consumer
+ *     (whatever processes each page) and blowing memory.
+ *
+ *   - **done** — the API returned a null next cursor; the walk is exhausted. A
+ *     terminal phase: `start` / `recordPage` / `resume` are all no-ops on it
+ *     (idempotent completion — a late duplicate result can't un-finish a walk).
+ *
+ * ### Transition table
+ *
+ * Rows are the current phase; columns are the op. `→` denotes the next phase;
+ * `self` means unchanged (a no-op for that (phase × op) pair). `next` is the
+ * cursor the consumer extracted from the page; `hwm` is `highWaterMark`.
+ *
+ * | from \ op   | start          | recordPage(count, next)                                              | resume                         |
+ * | ----------- | -------------- | -------------------------------------------------------------------- | ------------------------------ |
+ * | idle        | → fetching(c0) | self *(¹)*                                                            | self                           |
+ * | fetching    | self           | seen=max(0,seen+count), pages+=1; next==null → done; seen≥hwm → paused(next); else → fetching(next) | self                           |
+ * | paused      | self           | self *(¹)*                                                            | seen<hwm → fetching(cursor) *(²)* |
+ * | done        | self           | self                                                                  | self                           |
+ *
+ * *(¹)* `recordPage` only makes sense while `fetching` (a page was outstanding).
+ * On any other phase it is a no-op: a result that arrives when no fetch was in
+ * flight (a late duplicate, a double-dispatch) must not advance the cursor or
+ * double-count `seen`. The walk is a coordination aid, not a correctness gate —
+ * it absorbs the stray rather than corrupting the count.
+ *
+ * *(²)* `resume` re-arms the paused cursor ONLY once `seen` has dropped below
+ * `highWaterMark` (the consumer drained, lowering `seen` via `drain`). Calling
+ * `resume` while still over the mark is a no-op — the valve stays shut until
+ * there is real headroom, so a consumer that resumes optimistically can't
+ * defeat the backpressure. Resuming a walk that isn't `paused` is likewise a
+ * no-op.
+ *
+ * ## Backpressure
+ *
+ * `seen` is the count of items the API has produced that the consumer has not
+ * yet acknowledged as processed. `recordPage` adds each page's item count to it;
+ * `drain(n)` subtracts what the consumer finished. When `seen` reaches
+ * `highWaterMark`, `recordPage` parks the walk in `paused` instead of issuing
+ * the next fetch — the producer stops until `drain` + `resume` re-open the
+ * valve. A `highWaterMark` of `0` (or any non-positive value) disables
+ * backpressure: the comparison `seen >= hwm` is satisfied vacuously only when
+ * `hwm <= 0` would pause immediately, so we treat `hwm <= 0` as "unbounded" and
+ * never pause. The walk then runs flat-out, `fetching → fetching` until `done`.
+ *
+ * NOT exported from the package root — reached via the `@demlik/tea/paginator`
+ * subpath, same one-shape-per-package rule as `work-queue`, `retry-backoff`,
+ * `circuit-breaker`, and `rate-limit`. It is the L1 escape hatch the
+ * `paginated-walk` composition builds its walk loop on.
+ */
+/**
+ * Paginator policy — pure configuration, no mutable state. One policy is shared
+ * across the whole walk (often a module-scope const). `PaginatorState` carries
+ * the cursor + counters; this carries the knobs they're compared against.
+ *
+ * Generic in `Cursor` so `firstCursor` matches whatever the API's cursor shape
+ * is — an offset `number`, a page-token `string`, a `{ after: string }` record,
+ * etc. The module never inspects the cursor; the type just threads through.
+ */
+interface PaginatorPolicy<Cursor> {
+    /**
+     * The cursor the walk fetches first, armed by `start`. For an offset API this
+     * is typically `0`; for a token API, `null`-or-empty-meaning-"first page" is
+     * the API's call, so pass whatever sentinel the API treats as page one.
+     */
+    readonly firstCursor: Cursor;
+    /**
+     * Backpressure threshold: the number of un-drained items at which the walk
+     * pauses instead of fetching the next page. `recordPage` parks in `paused`
+     * once `seen >= highWaterMark`; `drain` + `resume` re-open the valve.
+     *
+     * A non-positive value (`<= 0`) disables backpressure — the walk never pauses
+     * and runs `fetching → fetching` until the API exhausts. Use that when the
+     * consumer processes each page synchronously inside `recordPage` and there is
+     * nothing to back up.
+     */
+    readonly highWaterMark: number;
+}
+/**
+ * Sensible defaults: start from a numeric offset of `0`, pause after 1000
+ * un-drained items. Tuned for an offset-paginated REST API whose consumer
+ * processes pages asynchronously; override per call site (especially
+ * `firstCursor`, which is API-specific) rather than mutating this shared const.
+ *
+ * Typed as `PaginatorPolicy<number>` because the only honest default cursor is
+ * the numeric offset `0`; a token-based API supplies its own `firstCursor` and
+ * its own `PaginatorPolicy<string>`.
+ */
+declare const defaultPaginatorPolicy: PaginatorPolicy<number>;
+/**
+ * The walk's phase. A discriminated union on `phase` so each phase carries ONLY
+ * its own data and impossible combinations are unrepresentable (pattern 11):
+ * there is no `done` state that still holds a pending cursor, no `idle` state
+ * mid-fetch. Every field is `readonly` so the whole value is trivially
+ * JSON-serializable into a consumer's `Store<S>` and safe to thread through a
+ * pure reducer / a Durable-Object reload.
+ *
+ * Two counters ride on every phase so a consumer reads them uniformly without
+ * narrowing first:
+ *   - `seen`  — items produced by the API but not yet drained (backpressure gauge).
+ *   - `pages` — total pages recorded so far (progress / observability).
+ *
+ *   - `idle`     — not started; `start` arms `firstCursor`.
+ *   - `fetching` — a page request for `cursor` is outstanding.
+ *   - `paused`   — backpressure tripped; `cursor` is the page to resume from.
+ *   - `done`     — API exhausted (null next cursor); terminal.
+ */
+type PaginatorState<Cursor> = {
+    readonly phase: "idle";
+    readonly seen: number;
+    readonly pages: number;
+} | {
+    readonly phase: "fetching";
+    readonly cursor: Cursor;
+    readonly seen: number;
+    readonly pages: number;
+} | {
+    readonly phase: "paused";
+    readonly cursor: Cursor;
+    readonly seen: number;
+    readonly pages: number;
+} | {
+    readonly phase: "done";
+    readonly seen: number;
+    readonly pages: number;
+};
+/** The starting state: idle, nothing seen, no pages recorded. */
+declare function initPaginator<Cursor>(): PaginatorState<Cursor>;
+/**
+ * Arm the first fetch. PURE — returns a new state; the input is never mutated.
+ *
+ *   - `idle` → `fetching(firstCursor)`. This is the only phase `start` acts on.
+ *   - any other phase → unchanged. Re-arming a walk that has already begun (or
+ *     finished) would skip back to page one and double-count; a stray `start`
+ *     after launch is absorbed, not honored. Use `initPaginator()` to begin a
+ *     genuinely fresh walk.
+ */
+declare function start<Cursor>(state: PaginatorState<Cursor>, policy: PaginatorPolicy<Cursor>): PaginatorState<Cursor>;
+/**
+ * Record the result of the outstanding fetch and decide what comes next. PURE —
+ * returns a new state; the input is never mutated.
+ *
+ * `count` is how many items the just-fetched page yielded (added to `seen` for
+ * backpressure accounting). `next` is the cursor the consumer extracted from the
+ * page — a `Cursor` to fetch next, or `null`/`undefined` (a missing optional
+ * cursor field) if the API signalled the end.
+ *
+ *   - `fetching` → `seen = max(0, seen + count)`, `pages += 1`, then branch on
+ *     `next`:
+ *       - `next == null`            → `done` (API exhausted; loose-null so a
+ *                                      missing/`undefined` cursor also finishes).
+ *       - `seen >= highWaterMark`   → `paused(next)` (backpressure; `hwm <= 0`
+ *                                      disables this branch — see policy docs).
+ *       - otherwise                 → `fetching(next)` (keep walking).
+ *   - any other phase → unchanged. A result with no fetch outstanding (a late
+ *     duplicate, a double-dispatch) must not advance the cursor or double-count;
+ *     it is absorbed. See the module header's note ¹.
+ *
+ * `count` is floored into the gauge: a non-finite `count` (`NaN`/`Infinity`) is
+ * treated as `0`, and the additive sum is clamped at `0`. A record can only hold
+ * or raise `seen`; only `drain` lowers it. This keeps a stray negative or
+ * non-finite count from poisoning the `seen >= highWaterMark` comparison and
+ * silently defeating backpressure.
+ *
+ * The new `seen` total — not the pre-page value — is what the backpressure check
+ * reads, so a single page large enough to cross the mark pauses immediately
+ * rather than fetching one more first.
+ */
+declare function recordPage<Cursor>(state: PaginatorState<Cursor>, count: number, next: Cursor | null | undefined, policy: PaginatorPolicy<Cursor>): PaginatorState<Cursor>;
+/**
+ * Acknowledge that the consumer finished processing `n` items, lowering the
+ * backpressure gauge. PURE — returns a new state; the input is never mutated.
+ *
+ * Subtracts `n` from `seen`, floored at 0 (a consumer that over-acks, or acks a
+ * page recorded before a reload, can never drive `seen` negative). `n <= 0` is a
+ * no-op on the count. `drain` does NOT change the phase — it only frees
+ * headroom; `resume` is the separate, explicit decision to re-issue a fetch once
+ * the headroom exists. Splitting "I drained" from "I want to continue" lets a
+ * consumer drain in several steps and resume once.
+ *
+ * Works on every phase: a consumer may drain while still `fetching` (the gauge
+ * just drops, no pause was reached) or while `paused` (freeing room for a later
+ * `resume`). On `done` the gauge can still be drained for accurate final
+ * accounting, though it no longer gates anything.
+ */
+declare function drain<Cursor>(state: PaginatorState<Cursor>, n: number): PaginatorState<Cursor>;
+/**
+ * Re-open the backpressure valve after a `drain`. PURE — returns a new state;
+ * the input is never mutated.
+ *
+ *   - `paused` AND `seen < highWaterMark` → `fetching(cursor)`: the consumer has
+ *     drained below the mark, so re-issue the parked fetch.
+ *   - `paused` but `seen >= highWaterMark` → unchanged. There is still no
+ *     headroom; the valve stays shut until a `drain` lowers `seen`. A consumer
+ *     that resumes optimistically can't defeat the backpressure. (When `hwm <=
+ *     0` backpressure is disabled, so the walk never reaches `paused` and this
+ *     branch is unreachable — but the guard reads `< hwm` consistently, and a
+ *     non-positive `hwm` makes `seen < hwm` false for any non-negative `seen`,
+ *     correctly refusing to resume a state that should never have paused.)
+ *   - any other phase → unchanged. Resuming a walk that isn't paused (idle,
+ *     fetching, done) is a no-op.
+ *
+ * See the module header's note ².
+ */
+declare function resume<Cursor>(state: PaginatorState<Cursor>, policy: PaginatorPolicy<Cursor>): PaginatorState<Cursor>;
+/**
+ * Whether the walk has finished (the API returned a null next cursor). PURE,
+ * read-only. A derived predicate so a consumer's reducer can branch
+ * (`if (isDone(walk)) return [doneState, [joinCmd]]`) without re-checking the
+ * `phase` discriminant by hand at every call site.
+ */
+declare function isDone<Cursor>(state: PaginatorState<Cursor>): boolean;
+
+export { type PaginatorPolicy, type PaginatorState, defaultPaginatorPolicy, drain, initPaginator, isDone, recordPage, resume, start };

package/dist/paginator/index.js

@@ -0,0 +1,3 @@
+export { defaultPaginatorPolicy, drain, initPaginator, isDone, recordPage, resume, start } from '../chunk-SINXE47Y.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/paginator/index.js.map

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

package/dist/parity/index.d.ts

@@ -0,0 +1,86 @@
+import { BootingRuntime } from '../index.js';
+import { Trace, RecorderOptions } from '../recorder/index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-CymXZCeY.js';
+
+/**
+ * A live parity recording attached to a Runtime — the go/no-go gate's golden
+ * artifact. Wraps a {@link recorder}: drive the runtime, then snapshot with
+ * {@link Recording.trace} (or hand the live `Recording` straight to
+ * {@link goldenReplay}, which snapshots for you).
+ *
+ * @typeParam S - the machine's State type.
+ * @typeParam M - the machine's Msg union.
+ */
+interface Recording<S, M> {
+    /**
+     * Snapshot the recording so far as a replayable {@link Trace} — `loaded`
+     * (boot state), the ordered non-null `msgs`, and `finalState`. Sufficient to
+     * reproduce the run via {@link goldenReplay}. Fresh object each call.
+     */
+    trace(): Trace<S, M>;
+    /** Serialize the recording as JSONL (see {@link recorder}'s `toJSONL`). */
+    toJSONL(): string;
+    /** Detach the underlying observer. Idempotent. */
+    stop(): void;
+}
+/**
+ * Attach a parity recording to a Runtime, reusing the `recorder`/`historyTracker`
+ * capture (the boot observe for `loaded` + every non-null msg in order) rather
+ * than a fresh observer path.
+ *
+ * Attach on the synchronous `run()` handle so the boot transition is captured
+ * as `loaded`; drive the runtime; then `trace()` (or pass the handle to
+ * {@link goldenReplay}). See {@link RecorderOptions} for `captureSteps` (needed
+ * only for the per-step / resume-cache-prefix inspection, not for replay).
+ */
+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}.
+ *
+ * `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.
+ */
+declare function goldenReplay<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, recording: Recording<S, M> | Trace<S, M>, ctx?: Ctx): S;
+/** Configuration for {@link normalizeForParity}. */
+interface ParitySchema {
+    /**
+     * Object keys stripped wherever they appear — the record-time
+     * non-determinism `replay` never re-mints. Default: `id`, `runId`,
+     * `timestamp`.
+     */
+    readonly stripKeys?: readonly string[];
+    /**
+     * Candidate keys used to stable-sort arrays of objects. For each array the
+     * first candidate present (as a primitive) on the items decides the order;
+     * arrays with no candidate fall back to canonical-JSON order. Default:
+     * `ruleId`, `selector`, `url`.
+     */
+    readonly sortKeys?: readonly string[];
+}
+/**
+ * Build a finding-normalizer: a pure `(value) => normalized` that strips the
+ * schema's `stripKeys`, recursively sorts object keys, and stable-key-sorts
+ * arrays by the schema's `sortKeys`. Two runs that differ only in generated
+ * ids/timestamps or intra-effect ordering normalize to a byte-identical value,
+ * so {@link diff} on the normalized pair reflects behavioural (not incidental)
+ * difference.
+ */
+declare function normalizeForParity(schema?: ParitySchema): (value: unknown) => unknown;
+/**
+ * The parity verdict: `true` iff `a` and `b` are structurally equal. Reuses
+ * `trace-replay`'s order-insensitive deep-equal (the single comparator this
+ * package owns) rather than adding a second one — feed it the pair produced by
+ * {@link normalizeForParity} for the normalized-JSON equality the gate rests on.
+ */
+declare function diff(a: unknown, b: unknown): boolean;
+
+export { type ParitySchema, type Recording, diff, goldenReplay, normalizeForParity, recordRun };

package/dist/parity/index.js

@@ -0,0 +1,77 @@
+import { recorder } from '../chunk-UYWUVEP6.js';
+import { deepEqual } from '../chunk-EDGDR5XX.js';
+import { replay } from '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
+
+// src/parity/index.ts
+function recordRun(runtime, opts) {
+  const rec = recorder(runtime, opts);
+  return {
+    trace: () => rec.dump(),
+    toJSONL: () => rec.toJSONL(),
+    stop: () => rec.stop()
+  };
+}
+function goldenReplay(machine, recording, ctx) {
+  const trace = asTrace(recording);
+  const { state } = replay(machine, {
+    msgs: trace.msgs,
+    ctx,
+    loaded: trace.loaded
+  });
+  return state;
+}
+function asTrace(recording) {
+  return typeof recording.trace === "function" ? recording.trace() : recording;
+}
+var DEFAULT_STRIP_KEYS = ["id", "runId", "timestamp"];
+var DEFAULT_SORT_KEYS = ["ruleId", "selector", "url"];
+function normalizeForParity(schema) {
+  const stripKeys = new Set(schema?.stripKeys ?? DEFAULT_STRIP_KEYS);
+  const sortKeys = schema?.sortKeys ?? DEFAULT_SORT_KEYS;
+  const normalize = (value) => {
+    if (Array.isArray(value)) {
+      const items = value.map(normalize);
+      return items.map((item, index) => ({
+        item,
+        index,
+        primary: primarySortKey(item, sortKeys),
+        json: JSON.stringify(item) ?? ""
+      })).sort(
+        (a, b) => compareStrings(a.primary, b.primary) || compareStrings(a.json, b.json) || a.index - b.index
+      ).map((decorated) => decorated.item);
+    }
+    if (isPlainObject(value)) {
+      const out = {};
+      for (const key of Object.keys(value).filter((key2) => !stripKeys.has(key2)).sort()) {
+        out[key] = normalize(value[key]);
+      }
+      return out;
+    }
+    return value;
+  };
+  return normalize;
+}
+function primarySortKey(item, sortKeys) {
+  if (!isPlainObject(item)) return "";
+  for (const key of sortKeys) {
+    const candidate = item[key];
+    if (typeof candidate === "string" || typeof candidate === "number" || typeof candidate === "boolean") {
+      return String(candidate);
+    }
+  }
+  return "";
+}
+function compareStrings(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function diff(a, b) {
+  return deepEqual(a, b);
+}
+
+export { diff, goldenReplay, normalizeForParity, recordRun };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/parity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/parity/index.ts"],"names":["key"],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// parity — 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//   recordRun(runtime)            → Recording        // wraps the recorder\n//   goldenReplay(machine, rec)    → State            // wraps replay\n//   normalizeForParity(schema)    → (finding) => norm // strip + stable-sort\n//   diff(a, b)                    → boolean           // normalized deep-equal\n// ---------------------------------------------------------------------------\n\nimport type { BootingRuntime, Cmd, Machine, Sub } from \"../index\";\nimport { replay } from \"../index\";\nimport { type RecorderOptions, recorder, type Trace } from \"../recorder\";\nimport { deepEqual } from \"../trace-replay\";\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 diff} 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 single comparator this\n * package owns) rather than adding a second one — feed it the pair produced by\n * {@link normalizeForParity} for the normalized-JSON equality the gate rests on.\n */\nexport function diff(a: unknown, b: unknown): boolean {\n  return deepEqual(a, b);\n}\n"]}

package/dist/pbt/arbitraries/index.d.ts

@@ -1,5 +1,5 @@
 import * as fc from 'fast-check';
-import { Cmd, Sub, Machine } from '../../index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../../core-CymXZCeY.js';
 
 /**
  * Build a Ctx value whose every property access throws. Use as the `ctx`

package/dist/pbt/arbitraries/index.js

@@ -1,3 +1,3 @@
-export { arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from '../../chunk-ZRUST6BK.js';
+export { arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from '../../chunk-7FYQGDMF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/pbt/index.d.ts

@@ -1,6 +1,6 @@
 export { MsgArbitraryTable, arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from './arbitraries/index.js';
 export { Step, foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from './runners/index.js';
-import { Cmd, Reducer, Transitions } from '../index.js';
+import { C as Cmd, R as Reducer, T as Transitions } from '../core-CymXZCeY.js';
 import 'fast-check';
 
 /**

package/dist/pbt/index.js

@@ -1,12 +1,13 @@
-export { arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from '../chunk-ZRUST6BK.js';
-export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from '../chunk-PYBQREFU.js';
-import '../chunk-CMG2KMWX.js';
+export { arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from '../chunk-7FYQGDMF.js';
+export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from '../chunk-A56GNPI7.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
 
 // src/pbt/util/msg-keys.ts
 function msgTypeKeys(update) {
   const keys = Object.keys(update);
   if (keys.length === 0) return [];
-  const firstValue = update[keys[0]];
+  const firstValue = update[keys[0] ?? ""];
   if (typeof firstValue === "function") {
     return keys;
   }

package/dist/pbt/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/pbt/util/msg-keys.ts"],"names":[],"mappings":";;;;;AAiCO,SAAS,YACd,MAAA,EACmB;AACnB,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,MAAgB,CAAA;AACzC,EAAA,IAAI,IAAA,CAAK,MAAA,KAAW,CAAA,EAAG,OAAO,EAAC;AAI/B,EAAA,MAAM,UAAA,GAAc,MAAA,CAAmC,IAAA,CAAK,CAAC,CAAE,CAAA;AAC/D,EAAA,IAAI,OAAO,eAAe,UAAA,EAAY;AACpC,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,OAAO,MAAA,CAAO,KAAK,UAAoB,CAAA;AACzC","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// msgTypeKeys — read the Msg discriminant set at runtime from a Reducer\n// record or a 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// Used by `arbMsg` to assert (in dev) that the user-supplied table covers\n// every Msg variant the reducer claims to handle. Strict drift detection\n// without runtime introspection of the type system.\n// ---------------------------------------------------------------------------\n\nimport type { Cmd, Reducer, Transitions } from \"../../index\";\n\n/**\n * Extract the Msg discriminant set at runtime from a Reducer record or a\n * Transitions table. Useful for asserting that a user-supplied\n * `MsgArbitraryTable<M>` covers every variant the reducer can handle.\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.update);\n *   // → [\"start_audit\", \"stop_audit\", \"window_created\", ...]\n */\nexport function msgTypeKeys<S, M extends { type: string }, C extends Cmd>(\n  update: Reducer<S, M, C> | ([S] extends [{ type: string }] ? Transitions<S, M, C> : never),\n): readonly string[] {\n  const keys = Object.keys(update as object);\n  if (keys.length === 0) return [];\n  // Reducer form: every top-level value is a function (the cell).\n  // Transitions form: every top-level value is an object (the inner record).\n  // `keys[0]` is present — the length guard above rules out the empty record.\n  const firstValue = (update as Record<string, unknown>)[keys[0]!];\n  if (typeof firstValue === \"function\") {\n    return keys;\n  }\n  // Transitions form — read inner record.\n  return Object.keys(firstValue as object);\n}\n"]}
+{"version":3,"sources":["../../src/pbt/util/msg-keys.ts"],"names":[],"mappings":";;;;;;AAiCO,SAAS,YACd,MAAA,EAGmB;AACnB,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,MAAgB,CAAA;AACzC,EAAA,IAAI,IAAA,CAAK,MAAA,KAAW,CAAA,EAAG,OAAO,EAAC;AAI/B,EAAA,MAAM,UAAA,GAAc,MAAA,CAAmC,IAAA,CAAK,CAAC,KAAK,EAAE,CAAA;AACpE,EAAA,IAAI,OAAO,eAAe,UAAA,EAAY;AACpC,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,OAAO,MAAA,CAAO,KAAK,UAAoB,CAAA;AACzC","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// msgTypeKeys — read the Msg discriminant set at runtime from a Reducer\n// record or a 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// Used by `arbMsg` to assert (in dev) that the user-supplied table covers\n// every Msg variant the reducer claims to handle. Strict drift detection\n// without runtime introspection of the type system.\n// ---------------------------------------------------------------------------\n\nimport type { Cmd, Reducer, Transitions } from \"../../index\";\n\n/**\n * Extract the Msg discriminant set at runtime from a Reducer record or a\n * Transitions table. Useful for asserting that a user-supplied\n * `MsgArbitraryTable<M>` covers every variant the reducer can handle.\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.update);\n *   // → [\"start_audit\", \"stop_audit\", \"window_created\", ...]\n */\nexport function msgTypeKeys<S, M extends { type: string }, C extends Cmd>(\n  update:\n    | Reducer<S, M, C>\n    | ([S] extends [{ type: string }] ? Transitions<S, M, C> : never),\n): readonly string[] {\n  const keys = Object.keys(update as object);\n  if (keys.length === 0) return [];\n  // Reducer form: every top-level value is a function (the cell).\n  // Transitions form: every top-level value is an object (the inner record).\n  // `keys[0]` is present — the length guard above rules out the empty record.\n  const firstValue = (update as Record<string, unknown>)[keys[0] ?? \"\"];\n  if (typeof firstValue === \"function\") {\n    return keys;\n  }\n  // Transitions form — read inner record.\n  return Object.keys(firstValue as object);\n}\n"]}

package/dist/pbt/runners/index.d.ts

@@ -1,5 +1,5 @@
-import { Cmd, Sub, Machine } from '../../index.js';
 import * as fc from 'fast-check';
+import { C as Cmd, S as Sub, M as Machine } from '../../core-CymXZCeY.js';
 
 /**
  * One unit in a fold trace — the four pieces of data a property

package/dist/pbt/runners/index.js

@@ -1,4 +1,5 @@
-export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from '../../chunk-PYBQREFU.js';
-import '../../chunk-CMG2KMWX.js';
+export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from '../../chunk-A56GNPI7.js';
+import '../../chunk-2WZHS4P2.js';
+import '../../chunk-BNJYE4AU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map