@demlik/tea 0.15.0 → 0.17.0

package/dist/testing/index.d.ts

@@ -1,111 +1,6 @@
-import { C as Cmd, S as Sub, M as Machine, I as Interpret } from '../core-DnzqWy6u.js';
-import { C as CtxArg, R as Runtime } from '../runtime-types-CMF13BBh.js';
-import 'zod';
-import 'better-result';
-
-/**
- * The composed Model shape every `withX` wrapper produces: the base machine's
- * state nested under `base`, and the wrapper's own NAMED, serializable slice
- * under a single `$`-prefixed key. This helper does not care WHICH `$`-key the
- * wrapper uses — it discovers it structurally (the one non-`base` field).
- */
-type WrapperModel<S> = {
-    readonly base: S;
-} & {
-    readonly [K: `$${string}`]: unknown;
-};
-/** Options for the conformance replay. Mirrors `replay`'s second argument. */
-interface AssertWrapperFaithfulOpts<S, WM, BaseM, BaseCtx, WrapperCtx> {
-    /** The Msg sequence to fold through BOTH machines. Use the base's Msgs. */
-    readonly msgs: readonly BaseM[];
-    /** Ctx for the WRAPPED machine (base ctx + wrapper ports). */
-    readonly ctx: WrapperCtx;
-    /** Ctx for the BARE base machine. Defaults to `ctx` when omitted. */
-    readonly baseCtx?: BaseCtx;
-    /** Optional pre-`init` snapshot of the COMPOSED Model (wrapped rehydrate). */
-    readonly loaded?: WM | null;
-    /**
-     * Optional pre-`init` snapshot of the BARE base state. Supply when the
-     * wrapped `loaded` is non-null so the base-equivalence check rehydrates the
-     * base machine from the matching nested slice. Defaults to `loaded?.base`.
-     */
-    readonly baseLoaded?: S | null;
-    /**
-     * Opt-in relaxation for an INTERCEPTING wrapper (e.g. `withResilience`).
-     *
-     * DEFAULT (`undefined` / `false`) — the OBSERVE-ONLY contract that
-     * `withTelemetry` and `withDeadline` satisfy: every bare base Cmd must appear
-     * UNCHANGED, in order, as a subsequence of the wrapped Cmd stream (properties
-     * 1 and 3b). The wrapper may APPEND its own Cmds but may NOT alter, drop, or
-     * retime a base Cmd. This is the strict default and it is NOT weakened.
-     *
-     * WHEN SET — for a wrapper whose whole job is to INTERCEPT a chosen base Cmd
-     * (retag it into a wrapper-owned carrier so the concern — cache / breaker /
-     * rate-limit / retry — can gate it), a target base Cmd LEGITIMATELY does not
-     * appear raw at the top level of the wrapped stream. The contract is still
-     * **retag-and-re-emit, never swallow** (rule 2): the Cmd must be RECORDED, not
-     * vanished. So when a bare base Cmd is ABSENT from the top-level wrapped
-     * subsequence, this option accepts it IFF, in that SAME transition window, it
-     * is recorded by the wrapper as one of:
-     *
-     *   - the inner payload of a `$x:*` "run" carrier Cmd (`carrierCmdType` +
-     *     `innerField`) — the retag path; OR
-     *   - any other `$x:*` divergence Cmd whose `recordsField` deep-equals the
-     *     base Cmd — the gate/defer path (e.g. a "fast-failed" or "deferred"
-     *     record Cmd that carries the base Cmd it diverged on).
-     *
-     * A target base Cmd that is NEITHER present raw NOR recorded by any `$x:*`
-     * Cmd in its window is a SWALLOW betrayal and still fails the gate.
-     *
-     * Provide the field names the carrier uses so the gate can unwrap it
-     * structurally without hard-coding `withResilience`'s vocabulary.
-     */
-    readonly intercepting?: InterceptingOpt;
-}
-/**
- * Configures the intercepting relaxation (see
- * `AssertWrapperFaithfulOpts.intercepting`). All fields name the carrier /
- * divergence shape so the gate can structurally find a retagged base Cmd
- * inside a `$x:*` Cmd. The gate only EVER inspects `$x:*`-prefixed wrapped
- * Cmds for a recorded base Cmd — it never relaxes the check for a base Cmd
- * that appears under any non-wrapper Cmd type.
- */
-interface InterceptingOpt {
-    /**
-     * The `Cmd.type` of the wrapper's run-carrier (e.g. `"$resilience:run"`).
-     * A bare base Cmd that is retagged appears as `carrier[innerField]`.
-     */
-    readonly carrierCmdType: string;
-    /** The field on the carrier Cmd that holds the original base Cmd. */
-    readonly innerField: string;
-    /**
-     * OPTIONAL field on ANY OTHER `$x:*` Cmd that records a base Cmd the wrapper
-     * gated/deferred without running it (e.g. a fast-fail record). When present
-     * on a `$x:*` Cmd and deep-equal to the missing base Cmd, it counts as a
-     * recorded divergence. Omit when the wrapper only ever retags via the
-     * carrier.
-     */
-    readonly recordsField?: string;
-}
-/**
- * Assert a `withX` wrapper is TEA-faithful. Replays the wrapped machine and the
- * bare base machine over the same Msgs and checks the four conformance
- * properties (see file header).
- *
- * @param base       the bare base `Machine`.
- * @param makeWrapped a thunk that wraps `base` and returns the composed machine
- *   (e.g. `() => withTelemetry(base, cfg)`). A thunk — not the wrapped value —
- *   so a wrapper that registers process-scoped ports (`definePort`) is
- *   constructed inside the assertion's control, and so the same betrayal-
- *   detector reads as `assertWrapperFaithful(base, () => withX(base, cfg), ...)`
- *   at every wrapper's test site.
- * @param opts       the conformance replay options.
- */
-declare function assertWrapperFaithful<S, BaseM extends {
-    type: string;
-}, BaseC extends Cmd, BaseU extends Sub, BaseCtx, WM extends WrapperModel<S>, WrapperM extends {
-    type: string;
-}, WrapperC extends Cmd, WrapperU extends Sub, WrapperCtx>(base: Machine<S, BaseM, BaseC, BaseU, BaseCtx>, makeWrapped: () => Machine<WM, WrapperM, WrapperC, WrapperU, WrapperCtx>, opts: AssertWrapperFaithfulOpts<S, WM, BaseM, BaseCtx, WrapperCtx>): void;
+import { C as Cmd, S as Sub, M as Machine, a as BuiltinSub, o as Interpret } from '../core-rDbOaJTN.js';
+import { C as CtxArg, R as Runtime } from '../runtime-types-B62Ucnxr.js';
+import '@standard-schema/spec';
 
 /**
  * Shared options shape for every test assertion below. Mirrors the
@@ -239,7 +134,7 @@ interface BoundMachine<S, M extends {
      * Assert the exact set of subs desired at the final state. Mirrors the
      * free `expectActiveSubs(machine, opts, expected)`.
      */
-    expectActiveSubs(opts: BoundOpts<S, M>, expected: readonly NoInfer<U>[]): void;
+    expectActiveSubs(opts: BoundOpts<S, M>, expected: readonly NoInfer<U | BuiltinSub<M>>[]): void;
     /**
      * Bound `replay` — returns `{ state, cmds, subs }` for the given opts.
      * Use for the "narrow-then-assert" pattern where the test inspects a
@@ -248,7 +143,7 @@ interface BoundMachine<S, M extends {
     replay(opts: BoundOpts<S, M>): {
         state: S;
         cmds: readonly C[];
-        subs: readonly U[];
+        subs: readonly (U | BuiltinSub<M>)[];
     };
 }
 /**
@@ -324,6 +219,12 @@ type DriveOptions<Ctx> = DriveCtxArg<Ctx> & {
      * {@link DEFAULT_MAX_ROUNDS} (100).
      */
     readonly maxRounds?: number;
+    /**
+     * The clock that stamps `at` on a `Cmd.define`d Cmd's minted `_ok` / `_err`
+     * Msg — the one `run` takes. Defaults to `Date.now`; pin it for a test that
+     * asserts on `at`.
+     */
+    readonly clock?: () => number;
 };
 /**
  * Raised when a driven machine is still emitting work after `maxRounds` rounds.
@@ -386,8 +287,8 @@ declare function driveTraceOf<M, C>(err: unknown): readonly DriveTraceEntry<M, C
  * `handlers`, feeding every settle Msg back until the machine goes quiet, and
  * hand back the settled state together with the whole history.
  *
- * `handlers` is the same record the machine declares as its `interpret` (e.g.
- * `ask.handlers()` for a jev knob), so the test drives the real interpreter and
+ * `handlers` is the same table a host hands `run` as its `interpret` (e.g.
+ * a jev knob's `resilient_run` handler), so the test drives the real interpreter and
  * mocks only the port beneath it.
  *
  * One round is: fold every pending Msg, then await a handler for every Cmd
@@ -409,6 +310,25 @@ declare function drive<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, initial: S, msg: M, handlers: Interpret<M, C, Ctx>, ...[opts]: Record<never, never> extends DriveOptions<Ctx> ? [opts?: DriveOptions<Ctx>] : [opts: DriveOptions<Ctx>]): Promise<DriveResult<S, M, C>>;
 
+/**
+ * Assert that replaying `opts.msgs` is a pure function of the Msg log: the
+ * final state and every emitted Cmd come out the same under two different
+ * global wall-clocks and RNG seeds.
+ *
+ * `init` and `update` never receive a clock, so a cell that reads
+ * `Date.now()` or `Math.random()` reaches for the global one, and a replay of
+ * the same log on another day or another host lands somewhere else. Two
+ * back-to-back replays under one clock would hide that; this helper stubs
+ * two distinct ambients and compares. Time belongs in the Msg (an `at`
+ * field), where it is identical across replays.
+ *
+ * Subs are not compared: they are derived from the final state, so a state
+ * that matches yields the same Subs.
+ */
+declare function expectReplayDeterministic<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: NoInfer<ReplayOpts<S, M, Ctx>>): void;
+
 /**
  * Construct an inert `Runtime<S, M>` value. Use at ctx sites that require
  * a Runtime reference but where the test never invokes `interpret` (so
@@ -468,4 +388,4 @@ declare function stateFactory<S extends {
     type: string;
 }>(defaults: StateFactoryDefaults<S>): StateFactoryAPI<S>;
 
-export { type AssertWrapperFaithfulOpts, type BoundMachine, DEFAULT_MAX_ROUNDS, type DriveCtxArg, DriveNoHandlerError, type DriveOptions, type DriveResult, DriveRoundsExceededError, type DriveTraceEntry, type InterceptingOpt, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, type WrapperModel, assertWrapperFaithful, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { type BoundMachine, DEFAULT_MAX_ROUNDS, type DriveCtxArg, DriveNoHandlerError, type DriveOptions, type DriveResult, DriveRoundsExceededError, type DriveTraceEntry, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };

package/dist/testing/index.js

@@ -1,180 +1,7 @@
-import { replay } from '../chunk-66PY5WYF.js';
+import '../chunk-C4U5D5HP.js';
+import { replay, cmdEdgeOver, Outcome, cmdEdge } from '../chunk-K4ETBNKS.js';
 import { expect, vi } from 'vitest';
 
-function assertWrapperFaithful(base, makeWrapped, opts) {
-  const baseCtx = opts.baseCtx ?? opts.ctx;
-  const wrappedMsgs = opts.msgs;
-  const baseLoaded = opts.baseLoaded ?? (opts.loaded != null ? opts.loaded.base : null);
-  const A0 = { now: 1e6, rng: 0.123 };
-  const A1 = { now: 9876543, rng: 0.987 };
-  const bare = underAmbient(
-    A0,
-    () => replay(base, { msgs: opts.msgs, ctx: baseCtx, loaded: baseLoaded })
-  );
-  const wrapped = underAmbient(A0, () => makeWrapped());
-  const wrappedA = underAmbient(
-    A0,
-    () => replay(wrapped, {
-      msgs: wrappedMsgs,
-      ctx: opts.ctx,
-      loaded: opts.loaded ?? null
-    })
-  );
-  const wrappedB = underAmbient(
-    A1,
-    () => replay(makeWrapped(), {
-      msgs: wrappedMsgs,
-      ctx: opts.ctx,
-      loaded: opts.loaded ?? null
-    })
-  );
-  expect(wrappedA.state.base).toEqual(bare.state);
-  expectCmdSubsequence(bare.cmds, wrappedA.cmds, void 0, opts.intercepting);
-  const sliceKey = wrapperSliceKey(wrappedA.state);
-  expect(
-    sliceOf(wrappedB.state, sliceKey),
-    `wrapper slice changed under a different ambient clock/RNG \u2192 update is reading Date.now()/Math.random(); time must enter only as Msg \`at\` data`
-  ).toEqual(sliceOf(wrappedA.state, sliceKey));
-  const wrapperFamily = `${sliceKey}:`;
-  const wrapperCmdsA = wrappedA.cmds.filter(
-    (c) => c.type.startsWith(wrapperFamily)
-  );
-  const wrapperCmdsB = wrappedB.cmds.filter(
-    (c) => c.type.startsWith(wrapperFamily)
-  );
-  expect(
-    wrapperCmdsB,
-    `wrapper Cmds ("${wrapperFamily}*") changed under a different ambient clock/RNG \u2192 a wrapper Cmd PAYLOAD is reading Date.now()/Math.random(); wrapper Cmds must be a pure function of the Msg log, time entering only as Msg \`at\` data`
-  ).toEqual(wrapperCmdsA);
-  if (opts.msgs.length > 0) {
-    expect(
-      wrapperCmdsA.length,
-      `expected at least one "${wrapperFamily}*" wrapper-decision Cmd in the replay log (found none across ${opts.msgs.length} transition(s)) \u2014 a wrapper whose decisions are invisible to the Msg/Cmd log has betrayed total visibility`
-    ).toBeGreaterThan(0);
-  }
-  for (let i = 0; i < opts.msgs.length; i++) {
-    const bareStep = stepCmds(
-      () => underAmbient(
-        A0,
-        () => replay(base, {
-          msgs: opts.msgs.slice(0, i),
-          ctx: baseCtx,
-          loaded: baseLoaded
-        })
-      ).cmds,
-      () => underAmbient(
-        A0,
-        () => replay(base, {
-          msgs: opts.msgs.slice(0, i + 1),
-          ctx: baseCtx,
-          loaded: baseLoaded
-        })
-      ).cmds
-    );
-    const wrappedStep = stepCmds(
-      () => underAmbient(
-        A0,
-        () => replay(wrapped, {
-          msgs: wrappedMsgs.slice(0, i),
-          ctx: opts.ctx,
-          loaded: opts.loaded ?? null
-        })
-      ).cmds,
-      () => underAmbient(
-        A0,
-        () => replay(wrapped, {
-          msgs: wrappedMsgs.slice(0, i + 1),
-          ctx: opts.ctx,
-          loaded: opts.loaded ?? null
-        })
-      ).cmds
-    );
-    expectCmdSubsequence(bareStep, wrappedStep, i, opts.intercepting);
-  }
-  const slice = sliceOf(wrappedA.state, sliceKey);
-  expect(JSON.parse(JSON.stringify(slice))).toEqual(slice);
-}
-function underAmbient(ambient, fn) {
-  const nowSpy = vi.spyOn(Date, "now").mockReturnValue(ambient.now);
-  const rngSpy = vi.spyOn(Math, "random").mockReturnValue(ambient.rng);
-  try {
-    return fn();
-  } finally {
-    nowSpy.mockRestore();
-    rngSpy.mockRestore();
-  }
-}
-function sliceOf(model, sliceKey) {
-  return model[sliceKey];
-}
-function stepCmds(prefixCmds, throughCmds) {
-  const before = prefixCmds();
-  const after = throughCmds();
-  return after.slice(before.length);
-}
-function wrapperSliceKey(model) {
-  const dollarKeys = Object.keys(model).filter((k) => k.startsWith("$"));
-  if (dollarKeys.length !== 1) {
-    throw new Error(
-      `assertWrapperFaithful: expected exactly one "$"-prefixed wrapper slice on the composed Model, found ${dollarKeys.length} (${dollarKeys.join(", ") || "none"}). Every withX wrapper owns exactly one named slice (e.g. "$telemetry").`
-    );
-  }
-  return dollarKeys[0];
-}
-function expectCmdSubsequence(needle, haystack, step2, intercepting) {
-  let i = 0;
-  for (const cmd of haystack) {
-    if (i >= needle.length) break;
-    if (__deepEqual(needle[i], cmd)) {
-      i++;
-      continue;
-    }
-    if (intercepting !== void 0 && recordsBaseCmd(cmd, needle[i], intercepting)) {
-      i++;
-    }
-  }
-  const where = step2 === void 0 ? "the wrapped Cmd stream" : `the wrapped Cmd stream AT TRANSITION ${step2} (a base Cmd deferred to a later transition is an intra-window retiming betrayal)`;
-  const swallowHint = intercepting === void 0 ? "a missing/rewritten/retimed base Cmd is a swallow betrayal" : `an intercepting wrapper must RETAG each target base Cmd into a "${intercepting.carrierCmdType}" carrier (inner field "${intercepting.innerField}") or record it on a "$*:" divergence Cmd \u2014 a base Cmd neither present raw NOR recorded by any "$*:" Cmd is a swallow betrayal`;
-  expect(
-    i,
-    `expected every base Cmd to pass through unchanged (matched ${i} of ${needle.length} base Cmds as an ordered subsequence of ${where}) \u2014 ${swallowHint}`
-  ).toBe(needle.length);
-}
-function recordsBaseCmd(cmd, baseCmd, opt) {
-  if (!cmd.type.startsWith("$")) return false;
-  const rec = cmd;
-  if (cmd.type === opt.carrierCmdType && __deepEqual(rec[opt.innerField], baseCmd))
-    return true;
-  if (opt.recordsField !== void 0 && __deepEqual(rec[opt.recordsField], baseCmd))
-    return true;
-  return false;
-}
-function __deepEqual(a, b) {
-  if (Object.is(a, b)) return true;
-  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
-    return false;
-  }
-  const aIsArray = Array.isArray(a);
-  if (aIsArray !== Array.isArray(b)) return false;
-  if (aIsArray) {
-    const bArr = b;
-    if (a.length !== bArr.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!__deepEqual(a[i], bArr[i])) return false;
-    }
-    return true;
-  }
-  const aRec = a;
-  const bRec = b;
-  const aKeys = Object.keys(aRec);
-  const bKeys = Object.keys(bRec);
-  if (aKeys.length !== bKeys.length) return false;
-  for (const key of aKeys) {
-    if (!Object.hasOwn(bRec, key)) return false;
-    if (!__deepEqual(aRec[key], bRec[key])) return false;
-  }
-  return true;
-}
 function expectFinalState(machine, opts, expected) {
   const { state } = replay(machine, opts);
   expect(state).toEqual(expected);
@@ -263,10 +90,14 @@ async function drive(machine, initial, msg, handlers, ...[opts]) {
   const options = opts ?? {};
   const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
   const bound = bindMachine(machine, options.ctx);
+  const settle = cmdEdgeOver(machine.cmds ?? [], options.clock ?? Date.now);
   const noopEmit = { emit: () => {
   } };
   const handlerCtx = {
     ...noopEmit,
+    ok: Outcome.ok,
+    err: Outcome.err,
+    [cmdEdge]: settle,
     ...options.ctx
   };
   const cells = handlers;
@@ -294,11 +125,14 @@ async function drive(machine, initial, msg, handlers, ...[opts]) {
       if (cell === void 0) {
         throw new DriveNoHandlerError(cmd.type, trace);
       }
-      let settle;
+      let settled;
       try {
-        settle = await cell(cmd, handlerCtx, (fired) => {
-          pending.push(fired);
-        });
+        settled = settle(
+          cmd,
+          await cell(cmd, handlerCtx, (fired) => {
+            pending.push(fired);
+          })
+        );
       } catch (err) {
         if (typeof err === "object" && err !== null) {
           Object.defineProperty(err, TRACE_KEY, {
@@ -310,11 +144,35 @@ async function drive(machine, initial, msg, handlers, ...[opts]) {
         }
         throw err;
       }
-      if (settle !== void 0) pending.push(settle);
+      if (settled !== void 0) pending.push(settled);
     }
   }
   return { state, trace };
 }
+var AMBIENT_A = { now: 1e6, rng: 0.123 };
+var AMBIENT_B = { now: 9876543, rng: 0.987 };
+function expectReplayDeterministic(machine, opts) {
+  const a = underAmbient(AMBIENT_A, () => replay(machine, opts));
+  const b = underAmbient(AMBIENT_B, () => replay(machine, opts));
+  expect(
+    b.state,
+    "final state changed under a different clock/RNG: init or update reads Date.now()/Math.random(); time must enter as Msg data"
+  ).toEqual(a.state);
+  expect(
+    b.cmds,
+    "emitted Cmds changed under a different clock/RNG: a Cmd payload reads Date.now()/Math.random(); time must enter as Msg data"
+  ).toEqual(a.cmds);
+}
+function underAmbient(ambient, fn) {
+  const nowSpy = vi.spyOn(Date, "now").mockReturnValue(ambient.now);
+  const rngSpy = vi.spyOn(Math, "random").mockReturnValue(ambient.rng);
+  try {
+    return fn();
+  } finally {
+    nowSpy.mockRestore();
+    rngSpy.mockRestore();
+  }
+}
 
 // src/testing/noop-runtime.ts
 function noopRuntime(opts) {
@@ -390,6 +248,6 @@ function stateFactory(defaults) {
   return api;
 }
 
-export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, assertWrapperFaithful, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, expectReplayDeterministic, noopRuntime, stateFactory, step };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map